TaskManager 사양 8 · 적합성, 용어와 설계 근거
None요구사항 ID, 적합성 수준, 추적 사슬, 용어와 외부 실행 제어 설계 근거를 제공한다.
이 장의 결론: 기능 적합성은 요구사항, 구현, 코드 검증, 실기기 증거와 운영 확인이 연결될 때 확정된다.
31. 규범 요구사항과 적합성 판정
이 장은 앞의 설명을 구현과 출시 단계에서 판정할 수 있는 요구사항으로 고정한다. 요구사항 ID는 이슈, 소스 검토, 테스트 케이스, 실기기 증거와 릴리스 노트에서 공통으로 사용한다.
31.1 핵심 요구사항 ID
| 요구사항 ID | 강도 | 요구사항 | 쉬운 한 줄 설명 | 최소 증거 |
|---|---|---|---|---|
TM-CORE-001 |
MUST | 모든 관리 대상 실행은 고유 taskId와 생명주기 상태를 가져야 한다. |
무엇이 언제 시작하고 끝났는지 추적할 수 있어야 한다. | TaskRecord 단위 테스트와 런타임 이벤트 |
TM-CORE-002 |
MUST | 최종 상태는 COMPLETED, FAILED, PARTIAL_FAILED, CANCELLED를 구분해야 한다. |
성공, 실패, 일부 실패와 취소를 같은 결과로 합치면 안 된다. | 생명주기 전이 테스트 |
TM-ADM-001 |
MUST | 실행기 호출 전에 메서드, 호출자, 상태와 자원에 대한 실행 허용 판정을 수행해야 한다. | 실행할 수 없는 작업은 기기 동작이 시작되기 전에 차단해야 한다. | 거절 테스트와 미실행 증거 |
TM-ADM-002 |
MUST NOT | TaskManager의 실행 허용 판정은 기존 기기 도메인 안전 정책을 우회하면 안 된다. | 대기열 우선순위가 배터리·오류·개인정보 보호 제한보다 강할 수 없다. | 도메인 정책 회귀 테스트 |
TM-POL-001 |
MUST | 관리 경로는 기존 DeviceAgent 도메인 정책 담당자를 통해 기능을 실행해야 한다. | Task로 감싸도 기존 제품 정책은 그대로 적용돼야 한다. | 기존·관리 경로 허용 결과 비교와 도메인 진입 로그 |
TM-POL-002 |
MUST NOT | 틸트·LCD·팬·도킹 처리처럼 기능에 내재된 정책을 호출자가 재배열 가능한 독립 단계로 분해하면 안 된다. | 내부 안전 동작은 해당 기능이 책임져야 한다. | 이동·일시정지·도착 상태별 부수 정책 증거 |
TM-POL-003 |
MUST | 도메인 정책의 거절, 대기와 자동 전환 결과를 구조화된 Task 결과로 보존해야 한다. | 실행하지 않았는데 성공으로 끝난 것처럼 보이면 안 된다. | errorCode, reason, outcome 계약 시험 |
TM-EXE-001 |
MUST | 관리 대상 실행기는 승인된 기존 기기 도메인 담당자를 호출해야 한다. | TaskManager 안에 이동·청정 기능을 다시 만들지 않는다. | 실행기 연결 검토와 도메인 진입 로그 |
TM-EXE-002 |
MUST | 같은 요청의 중복 물리 효과를 식별하고 방지해야 한다. | 재시도나 재전송으로 같은 동작이 두 번 실행되면 안 된다. | requestId 재전송 테스트 |
TM-CMP-001 |
MUST | 비동기 물리 작업은 최신 완료 증거가 있을 때만 COMPLETED 처리해야 한다. |
함수 호출 성공이 아니라 실제 동작 완료를 확인해야 한다. | 시각 정보가 포함된 콜백·상태 증거 |
TM-CMP-002 |
MUST NOT | 시간 제한을 성공 완료의 대체 조건으로 사용하면 안 된다. | 시간이 지났다는 이유만으로 바이탈사인이나 이동을 성공 처리하지 않는다. | 시간 제한 실패 테스트 |
TM-CAN-001 |
MUST | 취소 가능 Task는 취소 요청과 실제 기기 도메인 중단 결과를 구분해야 한다. | 취소 버튼 접수와 기기가 실제로 멈춘 것은 별도 상태다. | 취소 명령과 정지 증거 |
TM-WF-001 |
MUST | Workflow 단계는 의존 단계가 실제 최종 조건을 만족한 뒤 시작해야 한다. | 앞 단계가 끝나기 전에 다음 동작이 실행되면 안 된다. | 순서가 확인되는 단계 이벤트 추적 |
TM-WF-002 |
MUST | 부분 실패 시 성공한 물리 효과와 실패 단계를 모두 보존해야 한다. | 일부만 실행된 상황을 전체 성공이나 전체 미실행으로 숨기지 않는다. | 부분 실패 결과 테스트 |
TM-SCH-001 |
MUST | 제품 반복 스케줄과 TaskManager 단발 예약의 담당자와 저장소를 분리해야 한다. | 생활 일정과 단발 지연 Task를 같은 예약으로 취급하지 않는다. | DB·저장소 분리 테스트 |
TM-CTX-001 |
MUST | 계획 컨텍스트는 출처, 시각과 최신성을 포함해야 한다. | 오래된 기기 상태를 현재 상태처럼 사용하면 안 된다. | 컨텍스트 스키마·최신성 테스트 |
TM-OBS-001 |
MUST | Task, Workflow, 단계와 콜백은 전체 실행의 상관관계를 복원할 수 있어야 한다. | 화면과 로그에서 어떤 결과가 어떤 요청의 것인지 찾을 수 있어야 한다. | traceId·requestId·taskId 이벤트 사슬 |
TM-COMPAT-001 |
MUST | 선택 적용하지 않은 기존 호출자는 기존 실행 경로를 유지해야 한다. | TaskManager 추가로 기존 앱 명령이 갑자기 다르게 동작하면 안 된다. | 기존 동작 기준 회귀 테스트 |
TM-COMPAT-002 |
MUST | 관리 경로 전환으로 달라지는 반환 시점과 결과 구조를 호출자별로 검증해야 한다. | “접수됨”을 기존의 “완료됨”으로 오해하지 않게 해야 한다. | 기존·관리 경로 응답 비교 |
TM-COMPAT-003 |
MUST | 기존 기기 도메인 콜백은 소비자 전환이 끝날 때까지 유지해야 한다. | Task 이벤트를 추가했다고 기존 화면이나 IoT 콜백을 끊으면 안 된다. | 이중 콜백 테스트 |
TM-COMPAT-004 |
MUST | 관리 Task와 기존 direct 명령은 같은 도메인 실행권과 자원 충돌 판정을 공유해야 한다. | 대기열 밖 명령이 실행 중 Task를 조용히 덮어쓰면 안 된다. | direct↔managed 동시 실행 매트릭스 |
TM-COMPAT-005 |
MUST | 기존 PUI·안전 명령이 관리 동작을 중단하면 관련 Task도 구조화된 최종 상태로 닫혀야 한다. | 기기는 멈췄는데 Task만 계속 실행 중으로 남으면 안 된다. | PUI 취소·저전력 선점 실기기 이벤트 사슬 |
TM-SEC-001 |
MUST | 공개 제어 API는 호출자 권한과 허용 출처를 검증해야 한다. | 아무 앱이나 이동·보안·긴급 명령을 실행할 수 없어야 한다. | Binder·출처 권한 테스트 |
TM-DEP-001 |
MUST | priv-app 배포는 기존 플랫폼 인증서, 소유자·모드와 SELinux 조건을 유지해야 한다. |
디버그 APK나 잘못된 권한으로 시스템 앱을 교체하면 안 된다. | 인증서·해시·권한 증거 |
TM-REL-001 |
MUST | 출시 승인에는 코드, 자동 테스트, 실기기와 원복 증거가 모두 필요하다. | 빌드 성공만으로 제품 동작 완료를 선언하지 않는다. | 출시 증거 묶음 |
31.2 적합성 수준
기능별 상태는 가장 높은 통과 수준 하나로 표현한다.
| 수준 | 이름 | 판정 기준 | 아직 주장하면 안 되는 것 |
|---|---|---|---|
L0 |
정의됨 | 메서드와 요구사항이 문서에 정의됨 | 소스 구현 완료 |
L1 |
연결됨 | 정책, 검증기, 실행기와 콜백 경로가 소스에 연결됨 | 자동 검증 또는 실기기 동작 |
L2 |
코드 검증 | 단위·JVM·빌드·계약 시험 통과 | 물리 기기 성공 |
L3 |
실기기 확인 | 지정 기기·APK·설정에서 실제 성공 증거 확인 | 다른 출시 조합의 보편 동작 |
L4 |
출시 적합 | 호출자 조합, 오류, 취소, 재부팅과 원복 인수 시험 통과 | 장기 운영 안정성 |
L5 |
운영 확인 | 배포 후 지표, 장애와 원복 훈련까지 확인 | 이후 출시 버전의 자동 적합 |
예를 들어 Vision Task가 정상 콜백으로 COMPLETED된 것은 최대 L3의 “관찰 호출 성공” 근거다. 원하는 객체를 찾았거나 추적 기능이 있다는 뜻은 아니다. 의미 있는 객체가 실제로 검출됐는지는 별도 인수 시험으로 확인한다.
31.3 기능 적합성 카드
각 taskMethod는 코드와 문서에 흩어진 내용을 다음 한 장의 카드로 모아야 한다.
| 항목 | 작성 내용 |
|---|---|
| 기능 | 표준 taskMethod, 사용자·시스템 목적 |
| 실제 담당자 | 기존 기기 도메인 관리자·제어기·API |
| 입력 계약 | 필수 필드, 타입, 허용 별칭과 기본값 금지 항목 |
| 호출자 계약 | 허용 출처, 권한과 우선순위 상한 |
| 실행 계약 | 실행 방식, 대기열, 시간 제한, 재시도와 중복 방지 키 |
| 상태·자원 | 허용 주 상태, 차단 상태와 필수 자원 |
| 완료 계약 | 시작·완료·중단 증거, 식별 키, 최신성과 안정 조건 |
| 취소·복구 | 취소 가능 여부, 취소 메서드와 보상 동작 |
| 결과 계약 | 성공 결과, 실패 사유 연결과 복구 가능성 |
| 관찰 계약 | 진행률, 이벤트와 계획 컨텍스트 반영 필드 |
| 호환 계약 | 기존 메서드·필드·콜백, 반환 차이와 원복 |
| 검증 상태 | L0~L5 수준, 테스트·증거 위치와 미해결 이슈 |
기능 카드 예시: setMoveTo
| 항목 | 현재 기준 |
|---|---|
| 목적 | 등록된 목표 공간 또는 좌표로 이동 |
| 실제 담당자 | Movement 실행기를 거친 기존 AMR·MovingController 계열 |
| 입력 | 표준 위치·공간 ID와 표시 이름. 임의 공간 추정 금지 |
| 실행 | ASYNC, movement 대기열, HIGH 우선순위와 시간 제한 정책 적용 |
| 시작 조건 | AMR 연결, 지도·대상 확인과 배터리·개인정보 보호·오류·LLM 정책 허용 |
| 완료 | 목표와 일치하는 최신 movement.arrived 및 이동 안정 상태 |
| 취소 | stopMovement 요청 후 실제 이동 중지 증거 |
| 선행 정리 | 청정 중이면 중지 후 cleaning.stopped를 확인하는 관리 전환 가능 |
| 실패 | 대상 없음, 정책 거절, AMR 사용 불가와 시간 초과 등을 실패 사유로 분리 |
| 호환 | 기존 원시 이동 경로를 유지하며 호출자별 forceTaskManager 선택 적용 |
31.4 요구사항 추적 사슬
구조도는 제품 요구사항에서 TM 요구사항 ID, 기능 카드, 정책·검증기·실행기·완료 증거 소스, 자동화 시험, 실기기 증거, 출시 판정과 원복 절차까지 이어지는 추적 사슬을 나타낸다.
각 변경 PR 또는 출시 노트에는 최소한 다음을 남긴다.
requirements: [TM-CMP-001, TM-COMPAT-002]
capabilities: [setMoveTo]
callers: [APP, CLOUD]
source_changes: [...]
automated_tests: [...]
device_evidence: [...]
compatibility_result: pass | conditional | fail
원복: forceTaskManager 제거 또는 출시 산출물 복원
open_risks: [...]
31.5 출시 판정표
| 판정 | 조건 | 출시 처리 |
|---|---|---|
PASS |
필수 요구사항과 대상 호출자·기기 조합이 모두 통과 | 계획 범위 출시 가능 |
CONDITIONAL |
핵심 안전·호환 요구는 통과했지만 일부 조합이 미검증 | 범위 제한, 기능 플래그와 원복 방법 명시 |
FAIL |
중복 실행, 잘못된 완료, 기존 기능 회귀, 권한 또는 원복 실패 | 출시 차단 |
NOT_APPLICABLE |
해당 기능에 적용되지 않는 요구사항 | 적용 제외 근거 기록 |
다음 항목은 예외 승인으로 넘길 수 없는 출시 차단 조건이다.
- 기존 호출자의 기능 회귀 또는 중복 물리 실행
- 실제 완료 증거 없는 성공 처리
- 취소 후 기기 동작이 계속되는 상태
- 권한 없는 호출자의 제어 API 실행
- 디버그 인증서 또는 플랫폼 서명 불일치
- 원복 경로 부재
31.6 변경 관리
- 공개 필드, 생명주기, 실패 사유 또는 콜백 변경은 계약 변경으로 분류한다.
- 선택 필드 추가는 minor version, 기존 의미 변경이나 삭제는 major version 대상으로 본다.
- 내부 클래스 이름 변경은 외부 계약 변경이 아니지만 소스 추적 정보를 갱신한다.
- 별칭 추가는 호환 범위 확대다. 별칭을 제거하려면 호출자 현황과 폐기 유예 기간이 필요하다.
- 정책 기본값 변경은 API 구조가 같아도 동작 호환성 변경이다. 실기기 회귀 시험과 릴리스 노트가 필요하다.
- 목표 사양을 현재 구현으로 승격할 때 해당 요구사항의 테스트와 증거를 함께 연결한다.
제7부 · 용어와 최종 원칙 — 32~34장은 용어, 최종 설계 원칙과 세부 참조 문서를 정리한다.
32. 용어집
| 용어 | 정의 |
|---|---|
| Task | 하나의 관리 가능한 실행 단위 |
| Workflow | 순차·병렬 단계를 가진 상위 Task |
| 단계(Step) | Workflow 내부의 실행 항목 |
| 실행 허용(Admission) | 실행 전에 입력, 출처, 상태와 자원을 검사하는 과정 |
| 실행 정책(Policy) | 메서드별 실행 방식, 대기열, 우선순위, 시간 제한, 재시도와 취소 규칙 |
| 실행기(Executor) | Task 계약을 기존 기기 도메인 호출에 연결하는 어댑터 |
| 완료 증거(Evidence) | 실제 완료·취소·실패를 증명하는 콜백 또는 상태 |
| 완료 조건(Completion target) | 어떤 완료 증거를 기다릴지 나타내는 문자열 |
| 최종 상태(Terminal) | 더 이상 실행되지 않는 완료·실패·취소 상태 |
| 보상 동작(Compensation) | 이미 발생한 물리 효과를 안전한 상태로 되돌리는 작업 |
| 선점(Preempt) | 새 요청이 기존 Task를 정리하거나 대체하는 정책 |
| 단발 예약 Task(Deferred task) | 미래의 특정 시각에 한 번 실행 허용 절차에 진입하는 TaskManager 예약 |
| 제품 스케줄(Product schedule) | 반복 생활 일정과 제품 고유 스케줄 |
| 계획 컨텍스트(Planning context) | 계획에 사용할 현재 기기 상태 스냅숏 |
| 재계획(Replan) | 기존 목표를 유지하면서 단계와 기능을 다시 구성하는 상위 판단 |
| AAR | 제품 시스템 앱이 TaskManager를 타입 기반 API로 호출하기 위한 Android 라이브러리 |
33. 최종 설계 원칙
- 기능을 다시 만들지 말고 실행 생명주기를 공통화한다.
- 명령 접수와 실제 완료를 분리한다.
- 행동 요청과 센서·콜백을 분리한다.
- 상위 호출자는 목적과 실행 구성을, TaskManager는 실행 관리를, 기기 도메인은 물리 동작과 상태를 소유한다.
- 모든 기능은 정책, 스키마, 실행기와 완료 증거가 갖춰져야 실제 사용 가능한 기능이 된다.
- 취소는 성공이 아니며, 부분 실패도 성공으로 숨기지 않는다.
- 정상 진행은 기기 런타임이 처리하고 의미적 변경이 필요할 때만 재계획한다.
- 기존 기능과 호출자를 유지하면서 호환 경로를 통해 단계적으로 전환한다.
- AAR과 스키마 버전으로 외부 계약을 내부 코드와 분리한다.
- 구현, 코드 검증, 실기기 검증과 제품 인수를 항상 구분한다.
34. 관련 문서
문서 전체 진입점은 SoC TaskManager Framework다.
- 개념: AS-IS / TO-BE 가이드
- 구현: Source-Level Implementation Guide
- API: DeviceAgent Contract · AAR API · MQTT Contract
- 실행 확장: Scheduling Readiness · Device Context Planning
- 검증: Live Monitor · Voice Closed Loop
- 인수: Vendor Implementation Workbook
설계 배경과 외부 사례
TaskManager와 유사한 실행 제어 구조는 Android 작업 관리, 로봇 장시간 동작, Fleet Mission, 인프라 제어와 장기 Workflow에서 공통적으로 사용된다. 비교의 목적은 외부 플랫폼 자체를 도입하는 것이 아니라, 작업 수명주기·진행·취소·의존관계·실제 완료 증거가 왜 별도 실행 계층에 필요한지 확인하는 데 있다.
| 설계 참조 | 검증된 실행 원리 | SKIX TaskManager 적용 | 현재 범위 |
|---|---|---|---|
| Android WorkManager | 의존 작업, 상태 전파, 제약, 재시도와 취소 | TaskRecord, TaskPolicy, queue, retry, timeout, schedule |
작업 관리 원리 적용. AndroidX WorkManager 런타임은 사용하지 않음 |
| ROS 2 Actions | 장시간 Goal, Feedback, Cancel과 Result | Task ID, 진행 이벤트, 최종 상태와 취소 명령 | Action 상태 원리 적용. ROS 통신 규격은 범위 밖 |
| Nav2 | 기능 서버 조합, 단계 의존관계와 Recovery | subTasks, 조건, 지연, 제한적 병렬과 실패 정책 |
Workflow 제어 적용. 범용 Behavior Tree와 지속 재계획은 미지원 |
| NVIDIA Isaac Missions | Mission을 Task의 연속으로 관리하고 상태 추적 | Workflow·Step ID, source·trace와 단계 이벤트 | 단일 기기 Workflow 중심. Fleet 배정은 범위 밖 |
| Kubernetes·Borg | Admission, priority, 자원 경쟁과 상태 수렴 | 호출자·상태·CPU·RAM·열·도메인 자원 정책 | 기기 내부 자원 판정 중심. 범용 controller loop는 미지원 |
| AWS Step Functions | 응답, 장기 Job과 callback 대기를 구분하는 Workflow | ACK와 completion callback 분리, 단계 대기와 timeout | Cloud state machine은 사용하지 않으며 기기 내부 실행 권한은 TaskManager가 유지 |
| Durable Workflow | Step, Wait, Timer, Callback, Retry와 실행 이력 | completion target, watcher, 외부 event, delay와 timeout | 예약 복원 지원. 실행 중 Workflow 전체 replay는 보강 대상 |
SKIX TaskManager는 이 원리를 DeviceAgent의 물리 기능, 안전 정책, 완료 증거와 기존 API 호환성에 맞게 결합한다. 가장 가까운 설명은 작업 수명 관리 + 장시간 물리 실행 상태 + 단계형 Workflow 제어를 하나의 기기 실행 Core로 구성한 것이다.
설계 참조: Android WorkManager 작업 연결, ROS 2 Actions, Nav2 Behavior Tree, NVIDIA Isaac Missions, AWS Step Functions, Microsoft Durable Task.