DeviceAgent Layer Transition
이 문서는 DeviceAgent의 기존 layer 구조와 TaskManager Framework 적용 후 변경되는 layer 구조를 시각화한다. 업체 설명 시 가장 먼저 보여주기 위한 문서다.
MainApi 내부에서 실제로 TaskManager hook이 어느 위치에 들어가는지는 MainApi TaskManager Insertion을 같이 봐야 한다.
1. 기존 Layer 구조
기존 DeviceAgent는 대략 아래 layer로 볼 수 있다.
| Layer | 주요 책임 | 대표 코드 |
|---|---|---|
| External Entry | 외부 method/Bundle 수신 | DeviceAgent.java |
| Main API Dispatch | method별 분기, main state, blocked status, framework bridge 처리 | MainApi.java |
| Command Handler | 기능별 command normalize/policy/execution | framework/command/*.java |
| Domain Manager | 이동, 청정, 맵, 배터리, 설정 등 실제 domain 상태/동작 | moving/*, cleaning/*, device/manager/*, settings/* |
| AppCmd / Module Bridge | module command/callback 전송 | AppCmd.java |
| SoC/HAL/Device Service | 실제 기기 제어, MCU, IoT, 센서, 서비스 경계 | main/*, service/*, HAL/vendor interface |
기존 구조의 장점은 기능이 이미 동작한다는 점이다. 문제는 source가 늘어나고 복합명령이 들어오면 실행 상태, 실패 이유, workflow step, source trace를 공통으로 관리하기 어렵다는 점이다.
2. 변경 후 Layer 구조
TaskManager Framework를 추가하면 기존 domain layer를 유지하면서, MainApi와 command/domain 사이에 공통 실행 layer가 생긴다.
| Layer | 변경 상태 | 주요 책임 | 대표 코드 |
|---|---|---|---|
| External Entry | 유지/확장 | Cloud, MQTT, App, Local Voice, Internal Schedule 수신 | DeviceAgent.java, bridge/server entry |
| Main API Dispatch | 변경 | TaskManager API 선처리, legacy path 보존 | MainApi.java |
| TaskManager API Layer | 신규 | submitTask, submitWorkflow, query/cancel/status/context |
TaskManager.java |
| Admission/Policy Layer | 신규 | validation, queue, timeout, retry, source/caller policy | TaskBundleValidator.java, TaskPolicyRegistry.java |
| Workflow/Queue Layer | 신규 | task record, workflow step, executor queue, metrics | TaskManager.java, PriorityTaskExecutor |
| Executor Adapter Layer | 신규 | taskMethod를 기존 domain handler 또는 신규 executor에 연결 | TaskExecutorRegistry.java, TaskExecutorBootstrap.java |
| Domain Manager | 유지/연결 | 기존 이동/청정/맵/센서/설정 business logic 유지 | 기존 domain package |
| Event/Reason/Context Layer | 신규 | onTaskEvent, reason_code, DevicePlanningContext |
TaskReasonContract.java, DevicePlanningContextProvider.java |
| AppCmd / Module Bridge | 유지/확장 | 기존 callback path와 TaskManager event callback 전달 | AppCmd.java |
| SoC/HAL/Device Service | 유지 | 실제 기기 제어 | 기존 service/HAL/vendor boundary |
3. 신규/변경/유지 구분
| 구분 | Layer |
|---|---|
| 신규 | TaskManager API, Admission/Policy, Workflow/Queue, Executor Adapter, Event/Reason/Context |
| 변경 | Main API Dispatch, AppCmd callback 사용 방식 |
| 유지 | 기존 Command Handler, Domain Manager, SoC/HAL/Device Service |
| 확장 | External Entry source, source trace, callback payload |
4. 업체 구현 핵심
업체는 아래 순서로 작업하면 된다.
MainApi.executeMethod(...)앞단에 TaskManager hook을 적용한다.- 기존 command handler는 유지한다.
- 외부 source가 직접 기능 method를 호출하지 않고
submitTask/submitWorkflow로 들어오게 한다. TaskPolicyRegistry와TaskBundleValidator로 method별 실행 정책과 필수 slot을 정리한다.TaskExecutorRegistry로 기존 domain handler를 executor adapter에 연결한다.onTaskEvent로 progress/terminal/failure event를 공통 payload로 올린다.TaskReasonContract와DevicePlanningContextProvider를 실제 domain 상태와 연결한다.
5. 이 구조로 얻는 것
| 효과 | 설명 |
|---|---|
| source 통합 | Cloud/MQTT/App/예약/로컬 음성이 같은 task API를 사용 |
| 복합명령 기반 | workflow/subTask/currentStepIndex로 단계 관리 |
| 장애 분석 | taskId/workflowName/reasonCode/sourceTrace로 추적 가능 |
| domain 유지 | 기존 command/domain logic을 재작성하지 않고 adapter로 연결 |
| framework화 가능 | 장기적으로 TaskManager를 DeviceAgent 내부 package에서 SoC 실행 framework로 분리 가능 |