LLM Wiki

← Docs hub

TaskManager Callback Completion Wiki

Task 완료/Callback Correlation 구조

1. 목적

TaskManager에서 “명령 접수 성공”과 “실제 동작 완료”를 분리하고, 기존 DeviceAgent/AMRAgent callback을 task 완료 이벤트로 연결하는 기준을 정의한다.

2. 핵심 원칙

원칙 설명
command result와 completion은 다르다 executor 성공은 기존 Manager에 명령을 전달했다는 의미일 수 있다
완료는 event/callback 또는 timeout으로만 확정한다 장시간 동작은 즉시 COMPLETED 처리 금지
기존 callback에는 taskId가 없을 수 있다 correlation registry가 필요하다
SDK/LLM에는 typed event로 변환한다 raw Bundle 노출 금지

3. 필요한 correlation registry

TaskManager 또는 별도 helper에 다음 mapping을 둔다.

taskId -> taskMethod
taskId -> expectedCallbackMethod
taskId -> targetId or positionId
taskId -> startedAt
taskId -> timeoutMs
taskId -> state

예시:

taskMethod expected callback completion condition
setMoveTo onMoveStateChanged 또는 AllMovingInfo target 도착/실패 상태
returnToStation onMoveStateChanged 또는 docking state station 도착/docking 상태
setAirCleanerOperation cleaning state callback 청정 상태가 requested state로 전환
setLlmTts LLM/TTS callback 정책상 “전달 완료” 또는 “재생 완료” 중 하나
setFirmwareUpdateStatus OTA status callback 단계별 success/fail

4. Movement 완료

Movement는 가장 먼저 구현해야 하는 completion 대상이다.

4.1 setMoveTo

TaskManager는 executor return만으로 완료 처리하면 안 된다. 이동 명령은 RUNNING으로 두고, 도착/실패 callback을 받아 종료해야 한다.

4.2 returnToStation

4.3 rotation

회전 완료는 전용 ROTATION_COMPLETE callback이 아니다. AllMovingInfo.movingState == 6으로 판정한다.

상세 계약은 19_amr_rotation_completion_contract.md를 따른다.

5. Cleaning 완료

Cleaning은 command별 완료 기준을 기획/개발이 합의해야 한다.

command 완료 기준 후보
setAirCleanerOperation 청정 mode/state가 요청값으로 반영됨
setStatusClean status clean 변경 callback 또는 내부 state update 완료
stopCleaning 청정 state가 stopped/idle로 전환
ampStop AMP 관련 동작 중지 확인

완료 callback이 없다면 최소 기준은 “명령 전달 성공 + state query 확인”으로 정의한다.

6. LLM/TTS 완료

LLM/TTS는 두 가지 중 하나를 명확히 선택해야 한다.

완료 기준 장점 단점
전달 완료 구현 간단, latency 낮음 실제 TTS 재생 실패를 알 수 없음
재생 완료 사용자 경험 기준 정확 LLMAgent callback 계약 필요

현재는 LlmManager.INSTANCE.setTts(tts)와 setChangeStatus(newStatus) 호출 경로가 확인된다. 재생 완료 callback이 명확하지 않으면 첫 단계에서는 전달 완료로 정의하고, 후속 단계에서 playback callback을 추가한다.

7. OTA 완료

OTA는 단계형 task로 봐야 한다.

ARM update result
  -> MCU update 필요 여부 확인
  -> MCU update result
  -> SOC update 필요 여부 확인
  -> otaend

OTAUpdateArmResult, OTAUpdateMcuResult, setFirmwareUpdateStatus는 각각 독립 task라기보다 하나의 update workflow 단계로 묶는 것이 적절하다.

8. timeout 정책

도메인 권장 timeout
Movement 이동 120~300초, 거리/지도 상태에 따라 조정
Rotation 10~30초
Cleaning state change 10~30초
LLM/TTS 전달 완료 5~10초
TTS playback 완료 문장 길이 기반 + 여유 시간
OTA 단계별 수분 단위, 별도 정책 필요

9. onTaskEvent 외부 계약

Task 완료/실패/진행률은 외부에 onTaskEvent로 전달한다.

필수 필드:

key type 설명
method String onTaskEvent
taskId String TaskManager가 발급한 id
taskMethod String 원 실행 method
state String PENDING/RUNNING/COMPLETED/FAILED/CANCELLED
progress int 0~100
reason String 실패/취소 사유
source String llm/iot/app/internal
requestId String MCP/SDK request id

10. 구현 체크리스트