← Docs hub

TaskManager 사양 4 · 도메인 기능과 기기 컨텍스트

기존 DeviceAgent 기능을 Task 실행기로 연결하는 방법과 계획에 제공할 기기 상태 계약을 정의한다.

이 장의 결론: 기능은 등록된 실행기와 완료 증거를 통해 Task가 되고, 기기 컨텍스트는 사실과 최신성을 보존해 상위 호출자에 제공한다.

16. 도메인 기능과 실행기 연결

16.1 실행기 등록 원칙

TaskExecutorBootstrap은 표준 taskMethod를 도메인 어댑터에 등록한다.

실행 연결은 SKIX 제품 앱에서 기기 도메인까지의 호출 계층에 표시한 것처럼 taskMethod를 TaskExecutorRegistry, 도메인별 TaskExecutor, 기존 DeviceAgent manager·controller·API 순서로 전달한다.

실행기 어댑터가 해야 할 일:

1. Task 계약 필드를 도메인 입력으로 정규화한다.
2. 기존 도메인 기능을 호출한다.
3. 요청 전달 결과를 outdata에 기록한다.
4. 비동기 기능이면 완료 연결부가 사용할 상관관계 키를 등록한다.
5. 실제 완료는 도메인 콜백을 통해 TaskCompletionStateStore에 기록한다.

실행기 어댑터가 하면 안 되는 일:

• 자연어 원문이나 채널별 요청 문자열을 다시 파싱한다.
• 임의의 기본값으로 잘못된 공간이나 모드를 추정한다.
• 콜백 없이 고정 대기 시간만으로 물리 완료를 선언한다.
• 동일 기능의 핵심 로직을 복제한다.
• 등록되지 않은 메서드를 리플렉션으로 무제한 실행한다.

16.2 현재 실행기 그룹

16.3 공개 메서드 목록

기기 정보와 상태

이동과 지도

청정

LLM, TTS, UI와 루틴

설정

제품 스케줄과 상호작용

보안

업데이트

16.4 기능 등록 체크리스트

새 DeviceAgent 기능을 TaskManager에 연결할 때 다음을 모두 정의한다.

1. 표준 taskMethod
2. 조회·제어·장기 실행 분류
3. 입력 스키마와 별칭
4. 요청 출처 허용 범위
5. 실행 방식
6. 대기열과 우선순위
7. 시간 제한, 재시도와 멱등성
8. 필수 자원
9. 실행기 어댑터
10. 시작·완료·중단 증거
11. 취소 메서드
12. 보상 동작 필요 여부
13. 실패 사유 변환
14. 계획 컨텍스트에 노출할 상태
15. 단위·통합·실기기 인수 시험

17. 기기 계획 컨텍스트

getDevicePlanningContext는 기능 정의가 아니라 현재 기기 상태의 스냅숏이다.

17.1 컨텍스트 구조

{
  "schema_version": "device_context.v1",
  "snapshot_ts": 1786400000000,
  "updated_at_ms": 1786400000000,
  "main_state": "...",
  "battery": {},
  "map": {},
  "location": {},
  "station": {},
  "air_quality": {},
  "cleaning": {},
  "movement": {},
  "network": {},
  "voice_llm": {},
  "security": {},
  "interactions": {},
  "task_manager": {},
  "semantic_observations": {},
  "capabilities": {}
}

17.2 컨텍스트 도메인

17.3 공간 정보 계약

각 room은 최소 다음을 제공한다.

{
  "id": "5",
  "name": "안방",
  "x": "...",
  "y": "...",
  "theta": "...",
  "station": false
}

상위 호출자는 공간 이름을 areaId와 연결한 뒤 Workflow를 만든다. TaskManager는 존재하지 않는 공간을 임의로 대체하면 안 된다.

17.4 정보 최신성

컨텍스트 출처는 다음 메타데이터를 가질 수 있다.

• observed_at_ms
• freshness_ms
• ttl_ms
• source_valid
• stale
• usable
• source_state
• expiry_mode

조건부 Workflow는 available=true만 보지 말고 최신성과 사용 가능 여부를 함께 확인해야 한다.

17.5 계획 컨텍스트 사용 원칙

• 컨텍스트 필드 이름을 사용자 TTS에 그대로 노출하지 않는다.
• current_room_name이 있으면 자연어 공간명으로 답한다.
• 스테이션 도킹 상태이면 공간 이름이 비어 있어도 “스테이션에 있다”고 안내할 수 있다.
• 공기질 원시값은 의미 등급과 권장 행동으로 변환한다.
• 실행 중인 Task가 있으면 새 Task의 실행 허용과 선점 정책에 반영한다.
• 스냅숏은 조회 시점의 정보다. 실행 직전의 중요한 조건은 DeviceAgent에서 다시 확인한다.