← Docs hub

DeviceAgent TaskManager

기존 기기 기능을 관리 가능한 실행 Framework로 연결

TaskManager는 이동, 청정, 화면, TTS, 보안, 설정과 예약 기능을 다시 만드는 모듈이 아니다. 호출자와 기존 기기 기능 사이에서 실행 접수, 허용, 순서, 상태, 취소, 실패와 실제 완료 증거를 공통 계약으로 관리한다.

1. TaskManager가 없던 기존 DeviceAgent

DeviceAgent에는 이미 기능 API가 있었다. 하지만 여러 기능을 묶는 호출자가 다음 책임까지 직접 가져가야 했다.

• 어떤 기능을 먼저 호출할지 결정
• 이전 기능이 실제로 끝났는지 판단
• 중간 취소와 실패 처리
• timeout과 retry 관리
• 앱, PUI, IoT 등 여러 요청의 충돌 처리
• 최종 결과와 실패 원인 보고

기능 수와 호출 채널이 늘수록 이 책임이 서비스 코드와 callback에 반복됐다. 동일한 이동이나 청정도 호출자마다 다른 순서, 상태와 실패 처리를 갖기 쉬웠다.

2. 구축 전과 구축 후의 차이

단일 호출도 TaskManager를 통과하면 동일한 상태와 결과 계약을 얻는다. 여러 동작은 caller 코드가 아니라 Workflow 데이터로 조합된다.

3. TaskManager Framework 전체 구성

Framework의 핵심 데이터 흐름

1. 앱, PUI, IoT, 예약 또는 내부 서비스가 구조화된 요청을 제출한다.
2. MainApi.executeMethod()가 control API와 legacy API를 구분한다.
3. TaskManager가 입력, 호출자, 상태와 자원 정책을 검사한다.
4. 허용된 Task를 queue 또는 Workflow에 배치한다.
5. Executor가 기존 DeviceAgent 도메인 API를 호출한다.
6. callback과 상태 변화가 completion evidence로 변환된다.
7. TaskManager가 terminal 상태를 확정하고 호출자와 모니터에 event를 전달한다.

4. TaskManager Core가 실제로 소유하는 기능

TaskManager가 관리하는 실행 단위

Core 기능 범위

현재 workflow queue 경계

상위 Workflow는 workflow queue가 소유하고, 하위 Task는 movement, cleaning, state 같은 도메인 queue를 사용한다. 상위 queue가 모든 물리 자원을 직접 잠그지 않으므로 서로 다른 Workflow의 하위 Task 간 충돌은 도메인 policy와 queue에서 차단해야 한다.

5. AOSP와 SKIX 안에서의 위치

TaskManager는 이 표준 계층 중 privileged product app 내부에 있다. frameworks/base 내부의 Android SystemService나 Android public SDK API가 아니다.

자연어 해석, 대화 라우팅, 장기 목표 판단은 범위에서 제외한다. TaskManager는 실행할 기기 행동이 이미 결정된 이후의 허용, 수행과 완료를 관리한다.

System / Product Application
-> TaskManagerClient AAR
-> Binder/AIDL product IPC
-> SKIX namuh Product Execution Framework
-> DeviceAgent domain API
-> AIDL / HIDL / HAL / MCU / Sensor

Binder/AIDL은 SDK가 아니라 IPC 계약이다. TaskManagerClient AAR이 앱 개발자에게 안정된 typed facade를 제공하고, DeviceAgent 내부의 TaskManager가 실제 실행 lifecycle을 소유한다.

Product Execution Framework의 의미

• 여러 제품 앱이 같은 실행 계약을 사용한다.
• 기존 도메인 API와 HAL을 유지한다.
• 기기 기능을 Task 단위로 편입하고 조합한다.
• UIManager 등 다른 SKIX Framework와 책임을 분리한다.
• 제품별 시나리오는 Core 수정 대신 Workflow 구성으로 확장한다.

6. MainApi에 삽입된 세 실행 경로

TaskManager는 선택 적용으로 도입한다. 기능을 편입해도 executor가 기존 API를 재사용하며, 문제가 있으면 동일 method의 direct legacy 경로로 원복할 수 있어야 한다.

7. 전체 기능 API를 공통 Framework로 묶는 원리

1. 기존 공개 기능명을 canonical taskMethod로 보존한다.
2. validator가 필수 payload와 type을 검사한다.
3. policy catalog가 queue, mode, priority, timeout과 completion target을 선언한다.
4. executor adapter가 기존 DeviceAgent API를 호출한다.
5. domain callback을 공통 completion evidence로 변환한다.
6. reason contract와 event가 호출자에 결과를 반환한다.

새 기능은 Core에 조건문을 계속 추가하는 대신 validator, policy, executor와 completion adapter를 등록한다. 조합 기능은 callback 체인 코드를 새로 만들기보다 이미 등록된 Task를 Workflow로 구성한다.

8. 실행 예시

단일 Task: 스테이션 복귀

submitTask(returnToStation)
-> movement admission
-> 기존 복귀 API 호출
-> movement.started
-> docking/charging evidence
-> COMPLETED

접수 성공은 완료가 아니다. 스테이션 도킹 또는 제품이 정한 동등한 완료 증거가 있어야 terminal 상태가 된다.

Workflow: 이동 후 청정하고 복귀

setMoveTo(room)
-> movement.arrived
-> startBasicAirClear
-> cleaning.stopped
-> returnToStation
-> movement.stationCharging

중간 단계가 실패하거나 취소되면 의존하는 후속 단계는 실행하지 않는다. 실패 정책에 따라 Workflow를 종료하거나, 안전한 보상 Task를 수행하거나, 상위 호출자에 판단을 요청한다.

지연 실행

scheduleWorkflow(runAt or relativeDelayMs)
-> SCHEDULED
-> due 시점에 fresh context로 재검증
-> 기존 submitWorkflow runtime 재진입

TaskManager scheduling은 실행 시점을 관리한다. 반복 제품 일정의 UI·DB·정책은 기존 Schedule 도메인이 유지하고, due 이후 실제 동작을 공통 Task runtime에 연결한다.

9. 완료, 취소와 실패

호출자는 내부 예외 문자열이 아니라 reason_code, recoverability, suggested_action과 관련 상태를 받아 사용자 안내, 재시도 또는 원복을 결정한다.

10. 현재 구현과 검증 범위

현재 소스 정합 기준은 다음과 같이 구분한다.

SET_MAIN_STATE처럼 정책은 있으나 모든 제품 상태에서의 물리 acceptance가 닫히지 않은 기능은 “구현됨”과 “제품 검증 완료”를 분리해 표시한다. 시스템 앱 교체 검증은 platform certificate 일치 후 release APK를 /system/priv-app에 반영해야 하며 debug certificate APK를 사용하지 않는다.

11. 구조 변화의 효과

TaskManager의 목적은 queue 자체가 아니라, 기기 기능을 수명주기와 증거를 가진 실행 단위로 만들고 그 조합을 제품 자산으로 재사용하는 데 있다.

12. 기준 문서

• DeviceAgent TaskManager 기준 사양서
• TaskManager AS-IS / TO-BE 가이드
• Source-Level Implementation Guide
• DeviceAgent TaskManager API Contract
• TaskManagerClient AAR API
• Scheduling Runtime Readiness

외부 구조 원리 참고:

• Android platform architecture
• AIDL
• HAL