← Docs hub

TaskManager 사양 3 · 생명주기와 Workflow

TaskRecord, 실행 모드, Workflow, 완료 증거, 취소, 실패, 이벤트와 예약 실행을 정의한다.

이 장의 결론: API 반환은 완료가 아니며, 다음 단계는 각 도메인의 최신 완료 증거가 확인된 뒤에만 진행한다.

8. TaskRecord와 생명주기

8.1 TaskRecord가 보존하는 정보

8.2 상태 모델

CANCELLED는 COMPLETED가 아니다. PUI에서 사용자가 청정을 중단하거나 앱 세션을 취소한 경우에도 “작업 종료”와 “목표 성공”을 구분해야 한다.

8.3 ID와 보존

• Task ID는 런타임 순번을 바탕으로 생성된다.
• 스케줄 ID는 별도 순번을 사용한다.
• 메모리 내 실행 기록은 최근 100건으로 제한된다.
• Task 기록과 예약 기록의 영속성은 서로 다른 속성과 파일을 사용한다.
• 저장소에서 복원한 상태는 실제 하드웨어 상태와 다를 수 있으므로, 부팅 후 최신 상태와 대조해 정합해야 한다.

8.4 진행률

• updateTaskProgress는 진행률을 0~100 범위로 제한한다.
• stage는 의미 단계, message는 운영 설명을 담는다.
• 병렬 하위 Task의 진행률은 상위 Task의 평균 진행률로 집계한다.
• 상위 Workflow는 현재 단계 번호·메서드와 단계별 상태 목록을 함께 제공한다.
• 진행률은 완료 증거를 대체하지 않는다. 100% 값만으로 COMPLETED를 만들면 안 된다.

9. 실행 런타임

9.1 DIRECT

1. 실행 기록 생성 및 저장
2. RUNNING 상태와 STARTED 이벤트 기록
3. 호출 스레드에서 명령 실행
4. 결과 저장
5. 성공 시 COMPLETED, 예외 시 FAILED
6. 최종 상태 지표와 이벤트 기록

DIRECT는 짧은 조회에 적합하다. 물리 동작처럼 메서드 반환과 실제 완료 시점이 다른 기능에 사용하면 안 된다.

9.2 QUEUED_WAIT

1. 우선순위가 지정된 작업을 대기열에 제출
2. 호출자는 Future.get(timeout)으로 대기
3. 런타임이 재시도, 완료 대기와 최종 상태 관리
4. 시간 초과 또는 중단 발생 시 구조화된 실패 반환
5. 최종 결과를 호출자에게 반환

호출 스레드를 점유하므로 긴 사용자 세션에는 신중하게 사용한다.

9.3 ASYNC

1. 대기열에 Task 제출
2. accepted=true, taskId를 즉시 반환
3. 실제 실행과 완료 증거 대기는 실행기 스레드에서 계속됨
4. 진행·완료·실패는 이벤트와 상태 조회로 관찰

이동, 복귀, 청정, 보안처럼 시간이 걸리는 동작의 기본 실행 방식이다.

9.4 재시도

• maxRetries는 실행 정책 또는 요청의 retry로 결정한다.
• 실행 예외가 발생하면 재시도 횟수를 증가시키고, 상한에 도달할 때까지 같은 관리 대상 명령을 다시 실행한다.
• 기기 동작이 이미 일부 수행됐을 수 있으므로 재시도 가능한 메서드는 멱등성을 보장해야 한다.
• 물리 이동과 청정은 무조건 다시 호출하지 말고 현재 상태와 실패 사유를 확인해야 한다.

10. Workflow 런타임

10.1 상위 Workflow와 단계

submitWorkflow는 하나의 상위 TaskRecord를 만들고 subTasks를 순서대로 처리한다.

각 순차 단계는 다음 정보를 가진다.

10.2 순차 실행

각 단계의 기본 순서는 다음과 같다.

1. 별칭 정규화와 입력 검증
2. 도메인 자원 실행 허용 판정
3. 단계 상태를 PENDING으로 변경
4. 시작 조건과 실행 조건 평가
5. WORKFLOW_STEP_STARTED
6. 도메인 명령 생성과 실행
7. 완료 조건 대기
8. 결과 저장 후 COMPLETED로 변경
9. WORKFLOW_STEP_COMPLETED
10. 다음 단계 진입

앞 단계의 실제 완료 증거가 없으면 다음 단계를 시작하면 안 된다.

10.3 단계 의존성

현재 구현은 두 가지 실행 조건을 지원한다.

예시:

{
  "stepId": "clean-if-available",
  "taskMethod": "setAirCleanerOperation",
  "conditions": [
    {
      "type": "step_output_equals",
      "stepId": "read-air-quality",
      "path": "result.needs_cleaning",
      "value": "true",
      "onFalse": "skip"
    }
  ]
}

step_output_equals는 현재 Boolean 또는 String 비교를 지원한다. 범위 비교, 숫자 연산자와 복합 AND/OR 조건식은 목표 확장이다.

10.4 이전 단계 기준 지연

after_step 시작 조건은 선행 단계 완료 후 일정 시간이 지나면 다음 단계를 시작한다.

{
  "stepId": "vital-after-move",
  "taskMethod": "setLauncherScreen",
  "screenName": "vitalSign",
  "trigger": {
    "type": "after_step",
    "stepId": "move-room-1",
    "delayMs": 30000
  },
  "conditions": [
    {
      "type": "step_completed",
      "stepId": "move-room-1"
    }
  ]
}

지연 시간 동안 단계 상태는 WAITING, 세부 단계는 scheduled_delay_wait가 되며 remainingDelayMs가 갱신된다. 현재 구현은 Workflow 스레드 안에서 대기하므로, 매우 긴 지연은 별도의 영속 예약 실행으로 처리해야 한다.

10.5 병렬 그룹

{
  "type": "parallelGroup",
  "groupId": "feedback-group",
  "joinPolicy": "all_success",
  "failurePolicy": "partial_success",
  "tasks": [
    {"taskMethod": "setEyeLedColor", "color": "calm"},
    {"taskMethod": "setLlmTts", "text": "청정을 시작합니다"}
  ]
}

현재 구현은 다음과 같다.

• 각 하위 Task에 별도 TaskRecord를 만든다.
• 각 하위 Task를 정책에 지정된 대기열에 동시에 제출한다.
• 상위 Task는 각 하위 Task의 실행 결과를 기다린 뒤 하나의 그룹 결과로 취합한다.
• 그룹 시간 제한은 하위 Task 시간 제한 중 가장 큰 값으로 계산한다.
• 상위 Workflow의 시간 제한은 순차 단계 제한 시간의 합과 병렬 그룹별 최대 제한 시간을 합산한다.
• joinPolicy 값은 상태에 보존하지만, 현재 런타임은 모든 하위 Task가 끝날 때까지 기다린다.

10.6 실패 정책

partial_success를 전체 성공으로 처리하면 안 된다. 상위 서비스와 UX는 “일부 완료” 상태를 명시적으로 다뤄야 한다.

10.7 Workflow 대기열의 책임 경계

• 상위 Task는 workflow 대기열을 사용한다.
• 하위 Task는 메서드 정책에 지정된 도메인 대기열을 사용한다.
• 상위 Task를 취소할 때는 실행 중인 하위 Task의 취소 명령과 비동기 실행도 함께 정리한다.
• 상위 Task만 취소되고 실제 기기 동작이 계속되는 상태를 허용하면 안 된다.

11. 완료 증거

11.1 왜 메서드 반환만으로 부족한가

setMoveTo()가 성공을 반환해도 이동 요청이 전달됐다는 뜻일 뿐, 목표 공간 도착을 보장하지 않는다. setLauncherScreen()도 화면 전환 요청과 사용자의 측정 완료는 서로 다른 사건이다.

TaskManager는 다음 세 시점을 분리한다.

11.2 현재 완료 조건

현재 DeviceAgent Core의 완료 조건 목록과 AAR 공개 상수 목록은 완전히 같지 않다. Core에는 movement.rotationCompleted, tts.playbackStarted, tts.playbackEnded, ui.screenApplied가 있지만 현재 TaskManagerClient.TaskCompletionTargets에는 이 네 상수가 없다. 원시 문자열로는 요청할 수는 있지만 타입 기반 SDK 계약이 완성된 것은 아니다. AAR 상수 추가와 계층 간 상수 정합성 검사가 필요하다.

11.3 CompletionStateStore

• 완료 조건과 선택적 공간 ID를 기준으로 최신 완료 이벤트를 저장한다.
• 완료 조건의 전역 키와 공간별 키를 함께 기록한다.
• observedAtMs가 task의 completionSinceMs보다 최신이어야 한다.
• completionStableMs 동안 상태가 유지돼야 안정적인 완료 증거로 인정한다.
• 중단 이벤트는 성공 이벤트와 별도 저장소에 기록한다.
• 완료 이벤트는 의미 관찰 기록에도 남긴다.

11.4 CompletionWatcher

이 since 기준이 없으면 이전 이동이나 TTS 이벤트가 새 Task를 즉시 완료시키는 과거 증거 재사용 문제가 생긴다.

11.5 장기 세션 완료 의미

화면이 열렸다는 이유로 Vital Sign 측정 Task 전체를 완료하면 안 된다. 이 경우 setLauncherScreen은 시작 단계이고 app.sessionEnded가 완료 단계다.

11.6 AppSessionCompletionBridge

• 패키지가 running이면 app.sessionStarted를 기록한다.
• 현재 활성 패키지의 최종 이벤트만 수용한다.
• 취소 결과는 app.sessionEnded 중단으로 기록한다.
• 실패 결과는 실패 사유를 중단 증거로 기록한다.
• 그 밖의 최종 결과는 성공 app.sessionEnded로 기록한다.

11.7 LlmTaskCompletionBridge

• TTS Task마다 completionKey가 필요하다.
• 동시에 하나의 재생만 활성화할 수 있다.
• 처리 중 또는 재생 중 상태에서 시작 증거를 기록한다.
• 시작 뒤 상태가 IDLE이 되면 재생 종료를 기록한다.
• 호출어 취소와 STOP은 중단 증거다.

12. 취소와 보상 동작

12.1 취소 처리 순서

1. 대상 실행 기록과 최종 상태 여부 확인
2. cancellable 확인
3. CANCELLING 전이
4. 실행 중인 Workflow 하위 Task 취소
5. 실행 중이면 취소 명령 실행
6. 비동기 실행 취소와 대기열 제거
7. 취소 증거가 충분하면 CANCELLED
8. 취소 확인이 불충분하면 FAILED(cancel_failed)

12.2 확인된 생명주기 계약

12.3 보상 동작

보상 동작은 취소와 다르다.

• 취소는 현재 실행을 멈춘다.
• 보상 동작은 이미 발생한 기기 변화를 안전한 상태로 되돌린다.

예를 들어 이동 후 화면 전환에 실패한 Workflow에서 “원위치 복귀”가 항상 올바른 보상 동작은 아니다. 배터리와 장애 상태에 따라 스테이션 복귀나 현 위치 대기가 더 안전할 수 있다. 따라서 보상 메서드는 기능별 안전성 검토를 거쳐 등록한다.

12.4 PUI 취소

PUI 버튼이 기기 도메인을 직접 중단한 경우에도 TaskManager가 최종 상태 증거를 받아야 한다.

PUI와 음성 경로가 별도 상태를 관리하면 실제 기기는 멈췄는데 TaskManager에는 계속 RUNNING으로 남는 고립 Task가 생긴다.

13. 실패 사유 계약

실패를 자연어 한 문장으로만 전달하면 상위 시스템이 안전하게 분기할 수 없다. TaskManager는 하위 오류와 제품 수준의 실패 사유를 분리한다.

13.1 실패 사유 코드

13.2 실패 사유 매개변수

현재 공통 매개변수는 다음을 보존한다.

• task_method
• target_location_id
• target_location_name
• target_position

13.3 복구 가능성과 후속 조치

13.4 Cloud 판단 경계

현재 requiresCloudDecision은 실패 사유에 따라 계산된다. 다만 이 값이 true라고 해서 반드시 LLM을 호출해야 하는 것은 아니다.

20.5 콜백 이후 재계획 경계의 구조도처럼 짧은 대기 후 재시도, 저전력 복귀와 명시적 취소 종료는 기기 내부 정책으로 처리할 수 있다. 목표 공간 대체, 기능 변경, Workflow 재구성이나 사용자 동의가 필요하면 상위 판단으로 전달한다.

14. 이벤트 계약

14.1 이벤트 종류

14.2 이벤트 데이터

{
  "type": "task_event",
  "deviceId": "A1-board-005",
  "eventName": "WORKFLOW_STEP_COMPLETED",
  "taskId": "task-42",
  "taskMethod": "setMoveTo",
  "source": "CLOUD",
  "state": "RUNNING",
  "queue": "workflow",
  "progress": 33,
  "traceId": "trace-001",
  "workflowName": "room_clean_return",
  "currentStepIndex": 0,
  "currentStepMethod": "setMoveTo",
  "cloud_workflow_id": "wf-001",
  "cloud_step_id": "move-bedroom",
  "stage": "movement",
  "message": "안방 이동 완료",
  "completionTarget": "movement.arrived",
  "requires_cloud_decision": false,
  "ts": 1786400000000
}

14.3 이벤트 처리 원칙

• 정상 진행·완료 이벤트는 기기 내부 상태와 UI 갱신에 사용한다.
• 모든 이벤트마다 Planner를 다시 호출하지 않는다.
• 실패 이벤트도 기기 내부에서 복구할 수 있는 사유인지 먼저 확인한다.
• Cloud Workflow와 단계의 상관관계 필드를 보존한다.
• 콜백 수신자는 중복 이벤트를 견딜 수 있어야 한다.
• 최종 이벤트 이후 도착한 과거 진행 이벤트는 무시해야 한다.

15. 예약 실행

TaskManager의 예약 실행은 제품의 반복 스케줄 기능과 구분해야 한다.

15.1 세 시간 계층

15.2 예약 등록과 실행 분리

scheduleTask와 scheduleWorkflow는 등록 시점에 기기 기능을 실행하지 않는다.

15.3 예약 유형

현재 TaskManager.normalizeDeferredScheduleKind()는 Core 예약 등록을 deferred_task로 제한한다. 제품 스케줄은 기존 스케줄 메서드를 Task로 호출할 수 있지만, 일정 데이터의 저장과 관리 책임은 제품 Schedule 도메인에 남는다.

15.4 실행 조건과 미실행 처리

예약 요청은 절대 시각 또는 상대 지연 시간을 정규화해 실행 시각을 저장한다. 주요 필드는 다음과 같다.

• trigger
• triggerAtMs
• relativeDelayMs
• missedRunGraceMs / missed_run_grace_ms
• requireFreshDeviceContext
• blockWhenTaskManagerBusy

실행 시각이 허용 유예 시간을 지난 Task는 MISSED_RUN_EXPIRED로 차단할 수 있다. 오래된 예약을 뒤늦게 무조건 실행하면 이동이나 청정이 예상하지 않은 시간에 시작될 수 있다.

15.5 예약 상태

15.6 영속성

기본 예약 저장소:

/mnt/data2/db/taskmanager_scheduled_tasks.json

관련 시스템 속성:

persist.sys.deviceagent.taskmanager.schedule_persist
persist.sys.deviceagent.taskmanager.schedule_persist_path

등록 후 스냅숏을 저장하고 AlarmManager 실행기가 다음 실행 시각을 재예약한다. 부팅 복원 후에는 기기 식별자, 시계 변경과 미실행 유예 시간을 다시 검증해야 한다.

예약 런타임이 코드에 존재한다고 자동 실행되는 것은 아니다. 현재 기본값은 다음과 같다.

따라서 출시 형상에서 예약 자동 실행을 보장하려면 등록 성공뿐 아니라 해당 속성, 수신기·서비스 생명주기, 정확한 알람 권한, 재부팅 복원과 실행 시각 이벤트를 함께 확인해야 한다.

15.7 현재 검증 경계

• API 등록, 조회, 취소, 영속 저장과 수동 실행 허용 경로는 구현돼 있다.
• 실기기에서 일부 스케줄 등록, 복원과 실행 시각 검증 기록이 있다.
• 모든 제품 모드와 복합 Workflow의 정확한 알람 자동 실행은 기기·APK 조합별 출시 인수 시험이 필요하다.
• “코드가 있다”와 “장시간, 재부팅, 네트워크, 시계 변경 시나리오를 통과했다”를 구분한다.

제4부 · 도메인과 외부 연동 — 16~20장은 기존 기기 기능, 계획 컨텍스트, AAR, IoT/MQTT와 선택적 Planner 연결을 설명한다.