← Docs hub

SoC TaskManager Before/After Change Model

이 장은 SoC 업체 설명용 문서다. 핵심은 “기존 DeviceAgent 구조에 TaskManager layer를 왜 추가하는지”, “구조가 어떻게 바뀌는지”, “이 변경으로 어떤 이점이 생기는지”를 한 번에 설명하는 것이다.

1. 설명 대상

이 문서는 아래 상황에서 사용한다.

2. 기존 DeviceAgent 구조

현재 DeviceAgent는 이미 많은 기능을 수행한다. 주요 진입과 실행 경로는 다음 source에서 확인된다.

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/DeviceAgent.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/main/api/MainApi.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/app/AppCmd.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/framework/command/*.java

대표 흐름:

External method / Bundle
-> DeviceAgent
-> MainApi.executeMethod(...)
-> 개별 command/domain handler
-> AppCmd.sendModuleCommand_* 또는 AppCmd.sendModuleCallback_main(...)

소스에서 확인되는 기존 구조의 특징:

이 구조는 단일 기능 호출에는 동작한다. 하지만 Cloud LLM, MQTT 서버, 앱, 예약, 로컬 음성처럼 source가 늘어나고 복합명령이 들어오면 아래 문제가 생긴다.

3. 추가되는 TaskManager Layer

TaskManager layer는 기존 domain 기능을 대체하지 않는다. 기존 기능 앞에 공통 실행 관문을 추가한다.

Cloud / MQTT / App / Local Voice / Internal Schedule
-> submitTask / submitWorkflow
-> TaskManager
-> validation / policy / queue / workflow
-> TaskExecutorRegistry
-> 기존 domain handler 또는 SoC domain executor
-> onTaskEvent

핵심 source:

apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskManager.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskPolicyRegistry.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskBundleValidator.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskExecutorRegistry.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskExecutorBootstrap.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/TaskReasonContract.java
apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/task/DevicePlanningContextProvider.java

실제 연결 방식:

MainApi.executeMethod(method, indata, outdata)
  if TaskManager.handleControlMethod(method, indata, outdata, factory):
      return
  TaskManager.executeLegacy(method, indata, outdata, legacyRunnable)

즉 TaskManager는 기존 기능을 우회하거나 삭제하는 방식이 아니다. submitTask, submitWorkflow, getTaskStatus 같은 TaskManager API만 먼저 처리하고, 나머지는 기존 executeMethodInternal(...)로 보낸다.

4. 변경되는 구조

4.1 실행 path 비교

단일 청정 명령

기존:

method = setAirCleanerOperation
-> MainApi.executeMethodInternal(...)
-> FrameworkCommandBridge.tryHandle(...)
-> CleanOperationCommandHandler.handleSetAirCleanerOperation(...)
-> AppCmd.sendModuleCommand_iot(...)
-> domain policy/executor

TaskManager 적용 후:

method = submitTask
taskMethod = setAirCleanerOperation
source = cloud_a2a | mqtt_server | app_remote
-> TaskManager.submitTask(...)
-> validation: action/mode/speed/operation 확인
-> policy: cleaning queue, ASYNC, timeout, cancelMethod
-> executor: CleaningAmpTaskExecutor 또는 legacy adapter
-> CleanOperationCommandHandler / domain manager
-> onTaskEvent

차이:

• 외부 source는 더 이상 setAirCleanerOperation을 직접 호출하지 않아도 된다.
• TaskManager가 accepted/rejected/running/completed/failed 상태를 공통으로 남긴다.
• 실제 청정 조건 판단은 기존 CleanOperationCommandHandler와 cleaning domain이 계속 수행한다.

복합 이동/청정 명령

기존:

호출자가 setMoveTo, setAirCleanerOperation, setMoveTo를 직접 순서대로 호출해야 함
각 단계 실패 시 어느 단계가 실패했는지 공통 payload가 약함

TaskManager 적용 후:

method = submitWorkflow
subTasks:
  1. setMoveTo(positionName=거실)
  2. setAirCleanerOperation(action=1, mode=...)
  3. setMoveTo(positionName=안방)
-> currentStepIndex/currentStepMethod 갱신
-> WORKFLOW_STEP_STARTED / WORKFLOW_STEP_COMPLETED
-> 실패 시 parent workflow reason_code 기록

5. 기대 이점

5.1 정량/정성 효과

6. 업체 구현 관점의 핵심 요구

업체는 “기존 command handler를 모두 버리고 새로 만들라”가 아니라 아래 순서로 연결하면 된다.

1. 기존 MainApi.executeMethod(...) 기반 기능은 유지한다.
2. 외부 source는 직접 기능 method를 호출하지 않고 submitTask 또는 submitWorkflow로 들어오게 한다.
3. TaskManager가 validation, policy, queue, workflow를 먼저 처리한다.
4. 실제 기기 동작은 TaskExecutorRegistry를 통해 기존 domain handler 또는 새 domain executor에 위임한다.
5. 모든 task는 accepted 이후 terminal event를 보장한다.
6. 실패는 자유 문자열이 아니라 reason code와 params로 제공한다.
7. Cloud source는 replan 후보를, MQTT/App/예약 source는 ack/status/report/retry 정책을 각각 적용한다.

6.1 업체가 특히 조심해야 할 부분

7. 업체 설명 한 문장

이번 변경은 DeviceAgent에 Cloud LLM 전용 기능을 붙이는 작업이 아니라, 기존 직접 method 호출 구조 앞에 TaskManager 실행 layer를 추가해 Cloud/MQTT/App/예약/로컬 음성 명령을 하나의 SoC task framework로 수용하는 리팩터링이다.