← Docs hub

SKIX Product Framework 공개 경계 검토 기록

상위 구조: 이 문서는 SKIX 제품 프레임워크 전체 중 외부 앱과 제품 기능 사이의 북향 API·신뢰 경계를 다룬다. 상태, 정책, 자원, lifecycle, Task 실행과 Domain Framework 전체 구성은 SKIX 리팩터링 프레임워크 설계안을 기준으로 본다.

현재 결정: Gateway는 별도 프로세스의 확정 구성요소가 아니다. 1차 단계에서는 DeviceAgent의 제품 Runtime Binder 진입점 안에 호출자 검증·계약 변환·결과 필터링 책임을 논리 모듈로 둔다. 별도 APK나 프로세스는 승인 파트너 공개, 독립 업데이트 또는 장애 격리가 필요할 때 검토한다.

1. 결정 요약

SKIX 제품 기능은 DeviceAgent 안에 이동, 청정, 환경, 화면, TTS, 보안, 예약, Vision, 업데이트 등으로 축적되어 있다. TaskManager는 이 기능을 Task와 Workflow 단위로 실행하고 상태, 순서, 취소, 실패, 완료 증거를 관리하는 실행 Core다.

공개 경계에는 시스템 앱과 승인된 파트너 앱이 사용할 안정된 API, 호출자 검증, 계약 변환과 결과 필터링이 필요하다. 이 문서에서 Gateway는 그 책임 묶음을 뜻한다. 1차 구현은 별도 서비스가 아니라 제품 Runtime Service 내부 모듈로 시작한다.

앱이 말하는 것: 어떤 기능을 어떤 조건으로 사용하고 싶은가
Gateway가 판단하는 것: 누가 어떤 API와 capability를 사용할 수 있는가
TaskManager가 관리하는 것: 허용된 실행을 언제, 어떤 순서로, 어떤 종료 상태까지 수행하는가
도메인이 수행하는 것: 이동, 청정, 화면, 측정과 같은 실제 기기 동작

이 설계에서 Gateway는 TaskManager를 우회하거나 대체하지 않는다. Gateway는 공개 API와 신뢰 경계, TaskManager는 실행 생명주기 경계다.

2. 현재 기반과 목표 상태

상태 표기 원칙은 다음과 같다.

현재 체크아웃과 TaskManager 구현 브랜치가 다르므로, 실제 리팩터링을 시작하기 전에 기준 브랜치를 하나로 정합하는 작업이 선행되어야 한다.

보안 기준선 주의: MR6의 task_manager 브랜치에는 DEVICE_CONTROL signature permission과 service 보호가 들어가지만, 현재 speaker_identification 체크아웃의 DeviceAgent service에는 같은 manifest permission이 보이지 않는다. 어느 상태가 출시 기준인지 먼저 정합하고, 별도 인증서 파트너에게는 두 경우 모두 기존 IDeviceControl Binder를 직접 공개하지 않는다.

3. 왜 Gateway와 TaskManager를 분리하는가

두 계층을 합치면 TaskManager가 앱 인증, API 버전, UI surface, 파트너 계약까지 소유하게 된다. 그러면 실행 Core가 제품 배포와 파트너 정책에 종속된다. 반대로 Gateway가 queue와 Workflow 실행을 다시 구현하면 실행 상태의 소유자가 두 곳이 되어 취소, timeout, 완료 판정이 갈라진다.

3.1 실행 API 관계

SkixFrameworkClient.submit(ActionRequest)
  -> Gateway: caller identity + capability grant + API version
  -> GatewayTaskAdapter: public capability/operation을 TaskSubmitRequest로 변환
  -> TaskManagerClient: submitTask 또는 submitWorkflow
  -> TaskManager: admission, queue, execution, completion
  -> GatewayResultMapper: 내부 reason/event를 public result/event로 정규화
  -> Partner app: TaskHandle, progress, terminal result

TaskManagerClient.sendRaw(Bundle)와 임의 taskMethod는 내부 호환용으로 남기고 파트너 SDK에는 노출하지 않는다. 파트너는 Gateway가 공개한 capability와 operation만 조합할 수 있다.

3.2 조회와 UI는 Task로 강제하지 않는다

모든 API를 TaskManager에 넣는 것은 과설계다.

4. 권장 계층

4.1 Consumer Layer

시스템 앱도 장기적으로 Public SDK를 우선 사용해야 파트너 경로와 동일한 API가 실제 제품에서 검증된다. 단, 공장 검사, 복구, emergency처럼 외부에 공개할 수 없는 기능은 Internal SDK로 분리한다.

4.2 SDK Layer

UI AAR와 실행 AAR를 분리한다. 테마 변경 때문에 기기 실행 SDK가 재배포되거나, Device API 변경 때문에 모든 UI 리소스를 다시 검증하는 결합을 피하기 위해서다.

4.3 공개 API와 신뢰 경계

1차 구현은 DeviceAgent 프로세스의 제품 Runtime Binder 진입점 안에 아래 책임을 둔다. 동일 프로세스라도 호출자 UID·인증서 검증과 공개 계약 변환은 기존 raw command 처리보다 앞에서 수행한다. 별도 인증서 파트너가 늘어나거나 독립 배포·장애 격리가 필요해지면 이 책임 묶음을 별도 privileged service로 옮길 수 있다.

Gateway는 요청마다 호출자 UID를 다시 검증한다. 연결 시 한 번 확인한 package 문자열이나 앱이 요청에 넣은 source 값은 신뢰하지 않는다.

4.4 Execution and Domain Layer

TaskManager는 공개 앱 API를 알 필요가 없다. Gateway가 보낸 내부 계약을 기존 방식으로 처리한다.

TaskManager Core
  -> admission / policy / resource
  -> queue / priority / workflow / scheduler
  -> lifecycle / timeout / cancel / compensation
  -> executor registry
  -> completion watcher / event / reason

Executor는 도메인 Facade를 호출하고 Facade가 현재 DeviceAgent 구현과 peer agent를 감싼다.

Facade는 기존 기능을 복사하지 않는다. 입력 정규화, 정책 전처리, 실행 호출, 완료 증거 변환만 소유한다.

5. 파트너 공개 API 초안

아래 이름은 계약 검토를 위한 후보이며 구현 완료 API가 아니다.

SkixFrameworkClient client = SkixFramework.connect(context);

FrameworkInfo info = client.getFrameworkInfo();
List<CapabilityDescriptor> capabilities = client.getCapabilities();
DeviceSnapshot snapshot = client.getDeviceSnapshot(StateQuery.basic());

TaskHandle handle = client.submitAction(
        ActionRequest.builder("mobility.move")
                .requestId("partner-req-001")
                .put("targetRoom", "안방")
                .build()
);

TaskSubscription subscription = client.observeTask(
        handle.getTaskId(),
        event -> renderProgress(event)
);

Workflow는 raw taskMethod 배열이 아니라 공개 capability operation의 조합으로 받는다.

WorkflowRequest workflow = WorkflowRequest.builder("inspect-and-clean")
        .addStep(ActionStep.of("mobility.move").put("targetRoom", "거실"))
        .addStep(ActionStep.of("cleaning.startBasic").afterPrevious())
        .addStep(ActionStep.of("mobility.returnToStation").afterPrevious())
        .failurePolicy(FailurePolicy.STOP_AND_REPORT)
        .build();

TaskHandle handle = client.submitWorkflow(workflow);

5.1 파트너가 설정할 수 없는 값

파트너 앱이 다음 값을 직접 결정하게 하면 내부 안전 정책을 우회할 수 있다.

5.2 Public 결과 모델

내부 클래스명, exception stack, MCU code, raw Bundle은 partner result에 그대로 노출하지 않는다. 운영 추적용 traceId는 허용된 범위에서만 반환한다.

6. 인증서가 다른 승인 파트너의 접근 모델

기존 signature permission 하나만으로는 별도 인증서 파트너를 안전하게 지원할 수 없다. 파트너 Gateway는 Android permission 선언만 믿지 않고 service 내부에서 호출자 신원을 검증해야 한다.

6.1 권장 검증 순서

1. Binder.getCallingUid()로 실제 호출 UID를 얻는다.
2. PackageManager.getPackagesForUid()로 UID에 연결된 package를 확인한다.
3. 설치된 package의 signing certificate digest를 읽는다.
4. 읽기 전용 Framework policy에 등록된 package와 certificate 조합을 비교한다.
5. API version, capability grant, risk tier, 사용자 동의 조건을 검증한다.
6. 검증된 principal 정보를 Gateway 내부에서 생성하고 Task 요청에 주입한다.
7. 모든 API 호출과 Task event 구독에서 소유권을 다시 확인한다.

파트너가 전송한 package name, source, certificate 문자열은 신원 증거로 사용하지 않는다. shared UID가 있는 경우 연결된 모든 package와 signing lineage를 검증하거나 v1에서 거절한다.

6.2 권한 단계

인증서 교체는 signing lineage와 정책 version을 가진 별도 승인 절차로 관리한다. OTA로 policy를 갱신할 때는 rollback과 이전 SDK 호환성을 함께 검증한다.

7. SKLauncher2 UI Foundation 분리안

현재 SKLauncher2에는 공용 후보인 RoundedConstraintLayout, AirBotSwitch, AirBotSideBar, AirBotToastView, AirClearProgressBar, AlertView, typography style, color, font, animation resource가 있다. 그대로 복사해 공개하는 것이 아니라 재사용 가능성 기준으로 분류한다.

UI component는 Device API를 직접 호출하지 않는다. 사용자 action을 callback으로 올리고 앱이 Framework Client를 호출한다. Task 진행 UI는 TaskEvent를 입력받아 표현만 담당한다.

7.1 UI API 예시

<com.skix.ui.components.TaskProgressView
    android:layout_width="match_parent"
    android:layout_height="wrap_content"
    app:statusStyle="compact" />

taskProgressView.render(TaskUiModel.from(taskEvent));
surfaceClient.open(SkixSurface.VITAL_SIGN, SurfaceArgs.empty());

파트너 앱은 SKLauncher2의 Activity나 Fragment 클래스명을 직접 알지 않는다. surfaceId, arguments schema, result contract만 사용한다.

8. 기존 경로와 호환 운영

초기 전환에서 기존 MQTT, PUI, SKLauncher2, IoT, 내부 앱 호출을 일괄 변경하지 않는다.

같은 물리 자원을 사용하는 legacy 실행과 managed Task가 동시에 들어오면 TaskManager의 ingress와 자원 정책으로 단계적으로 편입한다. Legacy를 즉시 Task로 강제하지 않되, 이동, 청정, 카메라처럼 충돌 비용이 큰 도메인부터 managed concurrency로 전환한다.

9. 단계별 리팩터링 운영안

Phase 0. 기준선과 카탈로그

• 기준 MR6 브랜치와 TaskManager 구현을 정합한다.
• DeviceAgent public method, domain owner, caller, callback, 완료 증거를 inventory로 고정한다.
• SKLauncher2 resource를 token, component, surface, internal로 분류한다.
• 파트너 API에서 제외할 privileged 기능과 개인정보 기능을 명시한다.

완료 기준은 호출·상태·이벤트·보안 owner가 없는 기능이 inventory에 남지 않는 것이다.

Phase 1. Read-only 공개 API

• DeviceAgent 제품 Runtime Binder 안에 공개 Facade와 skix-framework-contract/client 초안을 만든다.
• identity, certificate allowlist, API version, capability discovery만 제공한다.
• state snapshot은 read-only capability부터 공개한다.
• 기존 DeviceAgent 실행 경로는 변경하지 않는다.

이 단계에서 보안 경계와 SDK 연결을 검증하고 물리 동작 회귀 위험을 분리한다.

Phase 2. 저위험 Action과 TaskManager 연결

• 화면 전환, TTS, 상태성 설정처럼 복구 가능한 기능부터 Action API를 연결한다.
• Gateway Task Adapter가 TaskSubmitRequest를 생성한다.
• Task event ownership과 public reason mapping을 검증한다.
• raw Task 필드를 파트너가 주입할 수 없는지 부정 시험을 수행한다.

Phase 3. UI Foundation

• semantic token과 primitive component를 별도 namespaced AAR로 추출한다.
• SKLauncher2와 partner sample app이 같은 UI AAR를 사용한다.
• screenshot, locale, accessibility, resource collision 회귀 시험을 추가한다.

Phase 4. 이동·청정과 제한 Workflow

• 이동과 청정 Facade를 Gateway capability로 공개한다.
• partner-composable로 승인된 operation만 Workflow 단계에 사용할 수 있게 한다.
• 최대 단계 수, timeout, 위험도, 동의, foreground 조건을 정책화한다.
• PUI 취소와 물리 완료 증거까지 terminal event로 검증한다.

Phase 5. 파트너 Pilot과 운영

• partner certificate 등록, 회전, 폐기 절차를 검증한다.
• Test Kit과 sample app, API 문서, 호환성 matrix를 배포한다.
• API 사용량, 거절 reason, task terminal coverage, binder death를 관측한다.
• 안정화된 API만 v1으로 고정하고 raw API deprecation을 시작한다.

10. 검증 항목

11. 1차 의사결정

12. 다음 검토 항목

1. 승인 파트너 범위와 장애 격리 요구가 별도 process 비용을 정당화하는지 측정한다.
2. v1 파트너에게 공개할 capability 범위를 read-only, UI, TTS, 이동, 청정 중에서 선정한다.
3. 파트너 인증서 allowlist를 system image, signed policy package, 관리 서버 중 어디서 갱신할지 결정한다.
4. SKLauncher2에서 가장 먼저 추출할 token과 component 10개를 선정한다.
5. 기존 TaskManagerClient의 sendRaw와 전체 constants를 Internal API로 분류할 방식을 결정한다.

연결 문서

• SKIX 리팩터링 프레임워크 설계안
• Framework and SDK Hub
• Framework SDK System Design
• SDK Contract
• SoC TaskManager Framework
• TaskManager 기준 사양서
• TaskManager 외부 연동과 호환