← Docs hub

SoC TaskManager Source-Level Implementation Guide

이 장은 SoC/DeviceAgent 업체가 실제 코드 기준으로 구현을 따라 할 수 있도록 정리한 소스 레벨 가이드다. 발표용 개념 설명은 Before/After Change Model을 보고, 실제 구현 위치와 method 단위 작업은 이 문서를 기준으로 본다.

1. 핵심 결론

TaskManager는 기존 domain 동작을 대체하는 별도 앱이 아니다. 기존 MainApi.executeMethod(...) 앞단에 공통 실행 layer를 넣고, 실제 기기 동작은 기존 executeMethodInternal(...) 또는 domain executor로 위임하는 구조다.

현재 코드에서 이 구조는 아래처럼 연결되어 있다.

MainApi.executeMethod(...)
-> TaskManager.handleControlMethod(...)
-> handled이면 TaskManager API 처리 후 return
-> 아니면 TaskManager.executeLegacy(...)
-> executeMethodInternal(...)로 기존 domain 기능 실행

근거:

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/main/api/MainApi.java
  import com.sk.airbot.deviceagent.task.TaskManager;
  executeMethod(...)에서 TaskManager.handleControlMethod(...)를 먼저 호출
  처리되지 않은 method는 executeLegacy(...)를 통해 executeMethodInternal(...)로 위임

2. 기존 진입점에 추가되는 Hook

기존 구조:

DeviceAgent
-> MainApi.executeMethod(method, indata, outdata)
-> executeMethodInternal(method, indata, outdata)
-> FrameworkCommandBridge 또는 기존 switch/handler

변경 구조:

DeviceAgent
-> MainApi.executeMethod(method, indata, outdata)
-> TaskManager.handleControlMethod(method, indata, outdata, factory)
   -> submitTask / submitWorkflow / getTaskStatus / cancelTask 등 TaskManager API면 여기서 처리
-> TaskManager.executeLegacy(...)
   -> 기존 executeMethodInternal(...) 호출 유지

업체 구현 포인트:

3. TaskManager API Entry

TaskManager.java는 아래 control method를 공통 API로 제공해야 한다.

submitTask
submitWorkflow
getTaskStatus
listTasks
getQueueStatus
updateTaskProgress
cancelTask
getTaskManagerStatus
getDevicePlanningContext
classifyTaskIngress

현재 코드 기준 책임:

3.1 Control Method별 입력/출력

3.2 공통 Bundle Key 규칙

4. submitTask 처리 상세

submitTask는 단일 실행 요청의 공통 admission gate다.

흐름:

enabled check
-> taskMethod 필수 확인
-> TaskBundleValidator.validateSubmitTask(...)
-> copyForTask(...)
-> TaskPolicyRegistry.resolve(...)
-> TaskSource.from(source)
-> caller policy check
-> state condition check
-> resource policy check
-> createTaskCommand(...)
-> DIRECT / QUEUED_WAIT / ASYNC 실행

업체 구현 의미:

5. submitWorkflow 처리 상세

submitWorkflow는 복합명령을 위한 핵심이다. 단순히 여러 method를 한 번에 보내는 것이 아니라, workflow 자체를 task로 만들고 subTask 상태를 추적한다.

흐름:

subTasks 필수 확인
-> workflow policy 생성
-> workflow TaskRecord 생성
-> 각 subTask 순차 실행
-> parallelGroup이면 병렬 그룹 실행
-> currentStepIndex / currentStepMethod 갱신
-> WORKFLOW_STEP_STARTED event
-> subCommand.run()
-> WORKFLOW_STEP_COMPLETED event
-> subTaskResults / subTaskStates 결과 기록

예시:

submitWorkflow
  workflowName = "living_room_clean_then_bedroom_move"
  subTasks[0] = { taskMethod: "setMoveTo", positionName: "거실" }
  subTasks[1] = { taskMethod: "setAirCleanerOperation", action: 1, mode: 2 }
  subTasks[2] = { taskMethod: "setMoveTo", positionName: "안방" }

업체 구현 포인트:

5.1 Workflow에서 실행 시점 조건 판단

복합명령에서 중요한 점은 “workflow 등록 시점”과 “subTask 실행 시점”의 기기 상태가 다를 수 있다는 것이다.

예:

1. 거실로 이동
2. 거실에서 청정 시작
3. 안방으로 이동

이 경우 2번 청정 조건은 workflow 등록 시점이 아니라 1번 이동 완료 후 확인해야 한다. 따라서 업체 구현은 아래 원칙을 따른다.

5.2 Workflow Event 순서

정상 순차 workflow:

ACCEPTED
RUNNING
WORKFLOW_STEP_STARTED(index=0)
WORKFLOW_STEP_COMPLETED(index=0)
WORKFLOW_STEP_STARTED(index=1)
WORKFLOW_STEP_COMPLETED(index=1)
WORKFLOW_STEP_STARTED(index=2)
WORKFLOW_STEP_COMPLETED(index=2)
COMPLETED or WORKFLOW_COMPLETED

실패 workflow:

ACCEPTED
RUNNING
WORKFLOW_STEP_STARTED(index=0)
WORKFLOW_STEP_COMPLETED(index=0)
WORKFLOW_STEP_STARTED(index=1)
FAILED(reason_code=PATH_BLOCKED or STATE_CONDITION_FAILED)

6. Policy Registry

TaskPolicyRegistry.java는 method별 실행 정책을 정의한다.

현재 주요 queue:

emergency
movement
cleaning
state
update
sound
settings
ai
default

대표 정책:

업체 구현 포인트:

• get/is/info/version/dump 성격은 기본적으로 DIRECT 후보로 둔다.
• 이동/청정/AI/TTS처럼 시간이 걸리는 제어는 ASYNC 또는 QUEUED_WAIT로 둔다.
• stop/emergency/error/reset 계열은 emergency 성격으로 우선순위를 높인다.
• cancel/compensation method는 queue별 default를 제공한다.

7. Bundle Validation

TaskBundleValidator.java는 strict validation이 켜졌을 때 method별 필수 입력을 검사한다.

현재 schema 예시:

주의:

• 이 validation은 domain safety logic을 대체하지 않는다.
• 기능 내부 조건 판단은 기존 handler/domain manager가 계속 수행한다.
• validation의 목적은 명백한 slot 누락을 execution 전에 차단하는 것이다.

8. Executor Binding

TaskExecutorBootstrap.java는 task method와 executor를 연결한다.

현재 skeleton binding:

업체가 해야 할 일:

1. skeleton executor를 실제 domain manager 호출로 연결한다.
2. dry-run executor와 real executor를 구분한다.
3. long-running 동작은 progress update 또는 event callback을 보장한다.
4. cancel method가 있는 domain은 stop/cancel path까지 연결한다.
5. domain 실패를 TaskReasonContract가 이해 가능한 error code로 넘긴다.

8.1 Domain Adapter 작성 패턴

TaskManager executor는 가능하면 얇은 adapter로 유지한다.

TaskExecutor
-> input Bundle normalize
-> 기존 domain handler 호출
-> domain 결과/error를 task output 또는 exception/errorCode로 변환

청정 예시:

taskMethod = setAirCleanerOperation
-> CleaningAmpTaskExecutor
-> CleanOperationCommandHandler.handleSetAirCleanerOperation(...)
-> CleaningTransaction / PolicyGate / Executor
-> success or domain error

이동 예시:

taskMethod = setMoveTo
-> MovementTaskExecutor
-> MovingController / RobotMovementController / map location lookup
-> success, PATH_BLOCKED, ROOM_NOT_FOUND 등

금지할 구현:

• TaskManager executor 안에 청정/이동 business rule을 중복 구현
• source가 cloud인지 mqtt인지에 따라 domain 동작 자체를 다르게 구현
• event를 보내지 않고 domain method만 호출
• 실패를 exception message나 toast string으로만 남김

9. 기존 Domain Handler와의 관계

예를 들어 setAirCleanerOperation은 기존 CleanOperationCommandHandler에서 이미 많은 조건 판단을 수행한다.

근거:

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/framework/command/CleanOperationCommandHandler.java
  handleSetAirCleanerOperation(...)
  AppCmd.INSTANCE.sendModuleCommand_iot(indata)
  Settings lock mode 확인
  InputNormalizer.normalize(...)
  PolicyGate.shouldSkipCurrentStep(...)
  PolicyGate.applyBeforeExecution(...)
  Executor.execute(...)

따라서 TaskManager가 해야 하는 일과 domain handler가 해야 하는 일을 분리해야 한다.

10. Reason Contract

TaskReasonContract.java는 내부 error를 상위가 이해 가능한 reason으로 정규화한다.

대표 mapping:

후처리 필드:

중요:

• LOW_BATTERY, DEVICE_BUSY, RESOURCE_LIMIT은 기본적으로 Cloud LLM 재판단 없이 device/server policy로 처리 가능하다.
• PATH_BLOCKED, ROOM_NOT_FOUND, STATE_CONDITION_FAILED, SENSOR_ERROR 등은 사용자 질문 또는 replan 후보가 된다.
• MQTT/App source에서는 requires_cloud_decision을 그대로 Cloud 호출로 해석하지 말고, server report/user notification 정책과 분리해서 사용한다.

11. Planning Context

DevicePlanningContextProvider.java는 실행 전 상위 planner/server가 참고할 수 있는 snapshot을 만든다.

현재 snapshot field:

schema_version = device_context.v1
snapshot_ts
updated_at_ms
main_state
battery
map
location
cleaning
movement
task_manager
capabilities

세부 내용:

업체 구현 포인트:

• rooms는 실제 map/room 정보를 채워야 한다.
• current_room_id/name은 가능한 경우 localization 결과로 채운다.
• blocked는 이동 controller가 제공하는 장애물/path 상태와 연결해야 한다.
• capability는 제품/펌웨어/설정에 따라 false가 될 수 있어야 한다.

12. Ingress Classification

TaskIngressClassifier.java는 method를 task/control/progress/result/sensor/event/trigger로 분류한다.

분류 결과는 아래 용도로 쓴다.

업체 구현 포인트:

• MQTT 서버에서 내려온 method도 이 classifier를 통과시키면 task로 넣을지, progress/result로 볼지 일관되게 판단할 수 있다.
• 예약/알람은 곧바로 실행하기보다 trigger로 분류한 뒤 policy를 거쳐 task 생성하는 편이 안전하다.

12.1 Source별 정책 분기

13. Event Payload Contract

TaskManager event는 notifyTaskEvent(...)에서 생성된다.

공통 흐름:

record.writeSummaryTo(eventData)
eventData.method = "onTaskEvent"
eventData.eventName = eventName
listener.onTaskEvent(eventName, eventData)
AppCmd.INSTANCE.sendModuleCallback_main(eventData)

event에 반드시 남겨야 할 계열:

14. 업체 구현 순서

권장 구현 순서:

1. MainApi.executeMethod(...) 앞단에 TaskManager hook을 붙인다.
2. submitTask, submitWorkflow, query/cancel/status API를 구현한다.
3. TaskPolicyRegistry에 method별 queue/mode/timeout/cancel 정책을 채운다.
4. TaskBundleValidator에 필수 slot schema를 채운다.
5. TaskExecutorRegistry에 기존 domain handler adapter를 연결한다.
6. TaskReasonContract에 domain error mapping을 추가한다.
7. DevicePlanningContextProvider에 실제 map/location/movement/cleaning/battery 상태를 채운다.
8. onTaskEvent payload를 Cloud/MQTT/App/예약 source별 trace와 함께 검증한다.
9. unit/integration/instrumented/logcat evidence를 제출한다.

15. 구현 완료 기준

업체 구현은 아래가 모두 확인되어야 한다.

16. 최소 테스트 시나리오