← Docs hub

SoC TaskManager Vendor Implementation Workbook

이 장은 업체가 실제로 구현해야 할 작업을 deliverable 단위로 정리한다.

업체 설명 순서는 Before/After Change Model로 구조 변화를 설명한 뒤, 이 workbook에서 실제 구현/검증 항목을 확인하는 방식이 좋다.

업체 구현 목표

Multi-source ingress
-> Source trace normalization
TaskManager API
-> Bundle validation
-> Policy/admission
-> Queue/workflow
-> Executor binding
-> Domain execution
-> Event callback
-> Reason contract
-> Planning context
-> Test evidence

필수 API

필수 ingress source

Sample 1: Cloud A2A 단일 task

method = submitTask
source = cloud_a2a
taskMethod = setAirCleanerOperation
cloud_workflow_id = wf_20260623_001
cloud_step_id = step_2
cloud_plan_id = plan_001
action = 1
mode = 2
speed = 2
strictValidation = true

기대 동작:

TaskManager가 cleaning queue에 task 등록
-> setAirCleanerOperation executor 실행
-> onTaskEvent RUNNING/COMPLETED 또는 FAILED
-> event에 cloud_workflow_id/cloud_step_id 보존

Sample 2: MQTT 서버 단일 task

method = submitTask
source = mqtt_server
external_command_id = cmd_98765
mqtt_message_id = mqtt_abc_001
taskMethod = setMoveTo
positionName = 거실
strictValidation = true

기대 동작:

TaskManager가 movement queue에 task 등록
-> 이동 executor 실행
-> onTaskEvent에 external_command_id/mqtt_message_id 보존
-> Cloud replan이 아니라 서버 ack/status/report 대상으로 처리

Sample 3: 복합 workflow

method = submitWorkflow
source = cloud_a2a
workflowName = living_room_clean_then_bedroom_move
cloud_workflow_id = wf_multi_001
subTasks = [
  { taskMethod = setMoveTo, positionName = 거실 },
  { taskMethod = setAirCleanerOperation, action = 1, mode = 2, speed = 2 },
  { taskMethod = setMoveTo, positionName = 안방 }
]

기대 event:

WORKFLOW_STEP_STARTED  currentStepIndex=0 currentStepMethod=setMoveTo
WORKFLOW_STEP_COMPLETED currentStepIndex=0 currentStepMethod=setMoveTo
WORKFLOW_STEP_STARTED  currentStepIndex=1 currentStepMethod=setAirCleanerOperation
WORKFLOW_STEP_COMPLETED currentStepIndex=1 currentStepMethod=setAirCleanerOperation
WORKFLOW_STEP_STARTED  currentStepIndex=2 currentStepMethod=setMoveTo
WORKFLOW_STEP_COMPLETED currentStepIndex=2 currentStepMethod=setMoveTo
WORKFLOW_COMPLETED 또는 COMPLETED

필수 event payload

method = "onTaskEvent"
eventName
taskId / task_id
taskMethod / task_method
taskState / status
executionMode
source
origin
caller
external_command_id / externalCommandId
mqtt_message_id / mqttMessageId
app_request_id / appRequestId
schedule_id / scheduleId
progress
stage
message
currentStepIndex
currentStepMethod
workflowName
taskErrorCode
taskReason
reason_code / reasonCode
reason_params / reasonParams
recoverability
suggested_action / suggestedAction
requires_cloud_decision / requiresCloudDecision
cloud_workflow_id / cloudWorkflowId
cloud_step_id / cloudStepId
cloud_plan_id / cloudPlanId
cloud_output_key / cloudOutputKey

실패 event sample

method = onTaskEvent
eventName = FAILED
taskId = task_17
taskMethod = setMoveTo
taskState = FAILED
source = mqtt_server
external_command_id = cmd_98765
mqtt_message_id = mqtt_abc_001
reason_code = PATH_BLOCKED
reason_params = {
  target_location_name = 거실
}
recoverability = user_action_required
suggested_action = ASK_USER_CLEAR_PATH
requires_cloud_decision = true

source별 해석:

필수 reason code

TIMEOUT
INTERRUPTED
USER_CANCELLED
DEVICE_BUSY
RESOURCE_LIMIT
STATE_CONDITION_FAILED
CAPABILITY_UNAVAILABLE
PATH_BLOCKED
ROOM_NOT_FOUND
LOW_BATTERY
SENSOR_ERROR
UNKNOWN

업체 제출 evidence

Diff summary 제출 양식

업체는 원본 대비 변경 내역을 아래 형태로 제출한다.

업체 구현 범위 체크리스트

업체에게 전달할 작업 요청서 형태

아래 내용을 그대로 업체 작업 요청 범위로 사용할 수 있다.

요청 1: TaskManager Hook 연결

MainApi.executeMethod(...) 진입 시 TaskManager.handleControlMethod(...)를 먼저 호출한다.
TaskManager가 처리한 method는 즉시 return한다.
처리하지 않은 method는 기존 executeMethodInternal(...) 경로로 유지한다.

완료 증거:

• submitTask가 TaskManager에서 처리되는 log
• 기존 legacy method가 TaskManager 미처리 후 정상 동작하는 log

요청 2: Multi-source Task API 구현

Cloud A2A, MQTT server, App/Remote, Local Voice, Internal Schedule source를 구분한다.
모든 source는 submitTask/submitWorkflow API를 공통 사용한다.
source별 trace id는 onTaskEvent까지 보존한다.

완료 증거:

• cloud_workflow_id 보존 sample
• mqtt_message_id 보존 sample
• app_request_id 보존 sample

요청 3: Workflow와 Step Event 구현

submitWorkflow는 subTasks를 순차 실행한다.
각 step마다 currentStepIndex/currentStepMethod를 event에 포함한다.
step 실패 시 parent workflow 실패 event에 reason_code를 포함한다.

완료 증거:

• 3-step workflow 정상 trace
• 2번째 step 실패 trace
• subTaskStates, subTaskResults sample

요청 4: Domain Executor Adapter 구현

TaskExecutorRegistry에 movement, cleaning, LLM/TTS, IoT, update executor를 등록한다.
executor는 기존 domain handler를 호출하는 adapter로 구현한다.
domain business logic은 TaskManager에 중복 구현하지 않는다.

완료 증거:

• setMoveTo 실제 이동 domain 연결 trace
• setAirCleanerOperation 기존 청정 handler 연결 trace
• cancel/stop method 연결 trace

요청 5: Reason/Context Contract 구현

domain error를 표준 reason_code로 변환한다.
reason_params, recoverability, suggested_action을 event에 포함한다.
getDevicePlanningContext는 실행 전 판단에 필요한 device snapshot을 제공한다.

완료 증거:

• PATH_BLOCKED, ROOM_NOT_FOUND, LOW_BATTERY, DEVICE_BUSY sample
• battery/map/location/cleaning/movement/task_manager/capabilities context sample

업체 Q&A 예상 질문

인수 기준

PASS 조건:

• submitTask accepted 후 반드시 terminal event가 온다.
• submitWorkflow는 subtask 순서와 currentStepIndex를 event에 반영한다.
• 실패 event에는 reason_code와 requires_cloud_decision이 들어간다.
• source trace field가 event까지 보존된다.
• Cloud source는 cloud_workflow_id 계열 trace를 보존한다.
• MQTT source는 external_command_id 또는 mqtt_message_id 계열 trace를 보존한다.
• getDevicePlanningContext가 Cloud planner 또는 서버 정책 판단 전에 호출 가능한 snapshot을 제공한다.
• unit/integration/instrumented/logcat evidence가 제출된다.

FAIL 조건:

• method만 실행하고 event를 보내지 않는다.
• 실패 이유가 자유 자연어 문자열뿐이다.
• queue/workflow 없이 복합명령을 즉시 함수 호출로만 처리한다.
• source trace field가 사라진다.
• Cloud LLM 전용으로만 구현되어 MQTT/App/예약 source가 같은 TaskManager API를 타지 못한다.
• TaskManager API는 있으나 실제 domain executor와 연결되지 않는다.