DeviceAgent TaskManager Layer Source Map
이 문서는 TaskManager Framework의 각 layer가 실제 DeviceAgent 소스의 어떤 파일과 연결되는지 정리한다.
업체가 구현을 시작할 때 이 문서를 먼저 보면 “어느 파일을 수정하고, 어느 파일은 기존 domain logic으로 유지해야 하는지”를 빠르게 구분할 수 있다.
1. 가장 중요한 결론
기존 DeviceAgent는 여러 source의 명령이 MainApi.executeMethod(...)로 모인 뒤 executeMethodInternal(...)의 기존 분기와 domain manager로 내려갔다.
TaskManager 적용 후에도 이 집결 지점은 유지한다. 대신 MainApi.executeMethod(...) 안에 아래 두 path가 생긴다.
Task control method
-> TaskManager.handleControlMethod(...)
-> submitTask / submitWorkflow / status / cancel / context 처리
Legacy device method
-> TaskManager.executeLegacy(...)
-> 기존 executeMethodInternal(...)
-> 기존 command/domain/service 로직 실행
2. Layer별 실제 소스 매핑
| Layer | 실제 파일 | 업체 작업 |
|---|---|---|
| External Entry | DeviceAgent.java, bridge/server entry |
Cloud, MQTT, App, Schedule, Local Voice가 method/Bundle 또는 task contract로 들어오게 정리 |
| Main API Dispatch | main/api/MainApi.java |
TaskManager.handleControlMethod(...) 선처리와 executeLegacy(...) wrapper 유지 |
| TaskManager API | task/TaskManager.java |
submitTask, submitWorkflow, getTaskStatus, cancelTask, getDevicePlanningContext 처리 |
| Admission / Validation | task/TaskBundleValidator.java, task/TaskAdmissionResult.java, task/TaskValidationResult.java |
method별 필수 slot, task/workflow payload 검증 |
| Policy / Source | task/TaskPolicyRegistry.java, task/TaskPolicy.java, task/TaskSource.java, task/TaskCallerPolicy.java |
queue, timeout, retry, cancellable, source별 허용 정책 정의 |
| Resource / Queue | task/TaskResourceMonitor.java, task/TaskResourcePolicy.java, task/TaskResourceSnapshot.java, TaskManager.java 내부 queue |
battery, movement, cleaning, queue busy 같은 실행 조건 관리 |
| Executor Registry | task/TaskExecutorRegistry.java, task/TaskExecutorBootstrap.java |
taskMethod를 실제 executor 또는 legacy domain call에 연결 |
| Domain Executor | task/MovementTaskExecutor.java, task/IotTaskExecutor.java, task/LlmTtsTaskExecutor.java, task/UpdateTaskExecutor.java, task/CleaningAmpTaskExecutor.java |
movement/cleaning/LLM/TTS/update 등 domain 실행 어댑터 구현 |
| Existing Domain Logic | framework/command/*.java, moving/*, cleaning/*, settings/*, device/manager/* |
기존 조건 판단과 실제 실행 로직은 최대한 유지하고 executor에서 호출 |
| Event / Reason | task/TaskEventListener.java, task/TaskReasonContract.java, TaskManager.notifyTaskEvent(...) |
onTaskEvent, reason_code, recoverability, suggested_action 공통화 |
| Planning Context | task/DevicePlanningContextProvider.java |
planning 전 battery/map/location/cleaning/movement/task queue/capability snapshot 생성 |
| Ingress Classification | task/TaskIngressClassifier.java, task/TaskIngressClassification.java, task/TaskSignalType.java |
payload가 task, control, progress, result, sensor, trigger, callback 중 무엇인지 분류 |
| AppCmd / Module Bridge | app/AppCmd.java, main/*, service/* |
기존 module command/callback 경로로 실제 SoC/HAL/service boundary 전달 |
3. 신규/변경/유지 파일 구분
| 구분 | 파일 |
|---|---|
| 변경 필수 | main/api/MainApi.java |
| 신규/확장 핵심 | task/TaskManager.java, task/TaskPolicyRegistry.java, task/TaskBundleValidator.java, task/TaskExecutorRegistry.java, task/TaskExecutorBootstrap.java |
| 신규/확장 보조 | task/TaskReasonContract.java, task/DevicePlanningContextProvider.java, task/TaskIngressClassifier.java, task/TaskResourceMonitor.java |
| domain adapter | task/MovementTaskExecutor.java, task/IotTaskExecutor.java, task/LlmTtsTaskExecutor.java, task/UpdateTaskExecutor.java, task/CleaningAmpTaskExecutor.java |
| 유지/연결 | framework/command/*.java, moving/*, cleaning/*, settings/*, device/manager/*, app/AppCmd.java |
4. 구현 순서
업체가 실제로 따라갈 구현 순서는 아래가 적절하다.
| 순서 | 작업 | 완료 기준 |
|---|---|---|
| 1 | MainApi.executeMethod(...)에 TaskManager hook 추가 |
모든 method가 TaskManager 선처리 또는 legacy wrapper 중 하나를 통과 |
| 2 | TaskManager.handleControlMethod(...) 구현 |
submitTask, submitWorkflow, status, cancel, context method 처리 |
| 3 | TaskBundleValidator와 TaskPolicyRegistry 구성 |
method별 필수 slot과 queue/timeout/retry 정책 정의 |
| 4 | TaskExecutorRegistry에 domain executor 등록 |
setMoveTo, setAirCleanerOperation, returnToStation 등 주요 method 연결 |
| 5 | 기존 domain handler 연결 | 기존 조건 판단과 실행 로직을 중복 구현하지 않고 호출 |
| 6 | notifyTaskEvent(...) event payload 고정 |
taskId, workflowId, eventName, status, reason_code 포함 |
| 7 | DevicePlanningContextProvider 실제 값 연결 |
planning 전 기기 상태 snapshot이 실제 runtime 상태를 반영 |
| 8 | source별 sample 테스트 | Cloud/MQTT/App/Schedule/Local Voice source가 같은 contract를 통과 |
5. 업체에게 반드시 강조할 점
| 항목 | 설명 |
|---|---|
MainApi는 없애지 않는다 |
기존 명령 집결점으로 유지하고 TaskManager hook을 삽입한다 |
| 기존 domain logic은 재작성하지 않는다 | 조건 판단이 이미 있는 곳은 executor adapter에서 호출한다 |
submitWorkflow는 단순 bulk call이 아니다 |
step 상태, 실행 시점 조건, 실패 reason, terminal event를 관리한다 |
| get/status는 대부분 queue task가 아니다 | planning context 또는 direct query로 처리한다 |
| Cloud만 대상이 아니다 | MQTT/App/예약/로컬 음성도 같은 TaskManager contract를 써야 한다 |
| 정상 event에 Cloud가 매번 개입하지 않는다 | progress/completed는 로컬 상태 갱신이고, replan 필요 실패만 상위 판단 후보가 된다 |