DeviceAgent 기능 이관 — AMR·Cleaning·Vision의 실제 연결과 폴더
개요: 이름만 나누지 않고 기존 호출을 옮긴다
기존 DeviceAgent 명령이 프레임워크의 정본 실행·정책 코드를 호출하도록 바꾸는 단계다. ManagerService 클래스가 있는 것, 실행 로직이 정본 폴더로 옮겨진 것, 새 서비스 프로세스에서 실제 동작하는 것은 서로 다르다. 이번 변경은 두 번째를 기존 제품 경로에 연결한다. Android Runtime 프로세스 이관 완료가 아니다.
전체 지도는 프레임워크 구조 Atlas를 유지한다. 이 페이지는 그 지도 중 DeviceAgent → 도메인 실행·정책 부분을 상세히 확대한 것이다. 진행 현황으로 돌아가기.
1. 실제 호출 구조
위에서 아래로 읽는다. 흰색은 기존 호스트, 녹색은 프레임워크 정본 코드다. AMR은 실행 코드를 통해 어댑터로 내려간다. Cleaning은 조건의 판정만 돌려받아 기존 실행을 이어간다. Vision은 정본 정책을 사용하되 기존 handler의 상태 인스턴스를 하나로 유지한다. 아래 주황 상자는 후속 연결이며 현재 요청이 새 Runtime이나 Task Binder를 통과한다는 뜻이 아니다.
2. 폴더 중심으로 읽는 책임
아래 base/는 저장소 루트의 skix-framework/base/다. apps/ 아래 새 프레임워크 복사본을 만들지 않는다.
skix-framework/base/
├── core/java/…/framework/manager/ 앱에 공개하는 Manager
├── compatibility/java/…/legacy/bundle/ 기존 통신 키·명령 호환 계약
└── services/core/java/…/server/domain/
├── amr/
│ ├── AmrManagerService.java 서비스 준비 상태 검사·선택적 실행 구성
│ ├── execution/
│ │ ├── AmrOperations.java 복귀·정지·이동 실행 분기
│ │ └── AmrMoveTarget.java 좌표와 목적지 원문 입력
│ └── port/AmrExecutionPort.java 실제 구동부와의 경계
├── cleaning/
│ ├── CleaningManagerService.java 서비스 수명주기 골격
│ └── policy/CleaningOperationPolicy.java
│ 잠금·건너뛰기·시작 전 정지 조건
└── vision/
├── VisionManagerService.java 서비스 수명주기 골격
└── policy/CameraAccessPolicy.java
공유·독점 접근과 오류 상태
apps/DeviceAgent/app/src/main/java/…/domain/
├── movement/MovementCommandHandler.java
├── movement/LegacyAmrExecutionAdapter.java
├── cleaning/CleaningLifecycleCommandHandler.java
└── camera/CameraCommandHandler.java
서버 패키지의 정확한 접두사는 com/sk/airbot/frameworkservice/server/domain/이다.
기존 앱 패키지는 com/sk/airbot/deviceagent/domain/이다.
DeviceAgent 빌드는 amr/execution, amr/port, cleaning/policy, vision/policy만 좁게 포함한다.
서버 전체나 공개 SDK 전용 어댑터를 앱으로 끌어오지 않도록 검사한다.
| 폴더 | 담당하는 것 | 넣지 않는 것 |
|---|---|---|
core/…/manager |
앱 요청·응답 API | 구동부 singleton, 서버 구현 타입 |
domain/…/execution |
기능별 실행 순서와 입력 | Android Bundle 파싱, HAL 세부 함수 |
domain/…/port |
실행 제공자의 인터페이스 | 특정 로봇 SDK에 고정된 구현 |
domain/…/policy |
해당 기능의 제품 조건·접근 판정 | 모든 도메인의 사양을 한 클래스에 집적 |
| 기존 앱의 어댑터 | 기존 엔진 호출·통신 변환 | 다른 도메인의 정책 재구현 |
state, observation 등 나머지 기존 타입의 하위 폴더 정리는 후속 이관과 함께 진행한다.
빈 디렉터리나 서비스 이름이 늘어난 수를 구현 완료율로 계산하지 않는다.
3. Manager와 ManagerService는 무엇이 다른가
| 구분 | 역할 | 이번 연결 상태 |
|---|---|---|
| 공개 Manager | 앱이 기능을 요청하는 입구 | 기존 API와 DeviceAgent 통신 유지 |
| ManagerService | 기능별 수명주기·요청 실행 권한·구성 책임 | AMR은 실행 제공자를 선택적으로 구성하고 요청 시 준비 상태 검사. Cleaning·Vision은 수명주기 골격 |
| 도메인 실행/정책 객체 | 실제 분기·조건 처리 | 기존 handler가 정본 객체를 호출 |
| 어댑터/Agent | 실제 엔진·구동부·별도 프로세스와 연결 | AMR은 기존 singleton 호출 어댑터. 카메라 엔진 및 AI Agent는 기존 위치 유지 |
서비스의 READY와 로봇의 주행·청소·카메라 상태는 다른 축이다.
준비된 서비스라도 구동부가 사용 중일 수 있다. 명령이 허용됐다는 응답도 물리 완료 근거가 아니다.
새 AMR 서비스의 요청 시 준비 상태 검사는 기존 DeviceAgent 직접 경로를 새 서비스 경로로 바꾸지 않는다.
서비스 종료와 이미 시작된 물리 동작의 중단 확인도 별도 문제로 남는다.
4. 기존 동작을 어떻게 보존했나
| 영역 | 정본으로 옮긴 내용 | 보존한 기존 의미 |
|---|---|---|
| AMR | 스트리밍 중 복귀 분기, 일시정지·재개·정지 인자, 목적지 이동과 거부 처리 | 좌표·목적지 문자열 원문, mission의 정확한 false, 기존 무동작 명령, 실패 통지 500ms, 예외 전파 |
| Cleaning | 잠금, 단계 건너뛰기, 시작 전 복귀/도킹 정지 조건, 유휴 복귀 | IoT 통지 후 잠금 검사, 앱 명령에서 도킹 조건 제외, 기존 구동부 조회 순서·횟수 |
| Vision | 공유·독점 접근, 참조 수, 브로커 오류와 상태 | 동기화와 단일 인스턴스, 기존 오류 우선순위. 새 권한/자원 임대 체계로 간주하지 않음 |
청소 정책은 조건만 판정하고 Android나 구동부를 직접 호출하지 않는다.
카메라 정책은 상태를 저장하므로 코드 파일을 옮겼다고 상태 소유자까지 새 Runtime으로 바꾸면 안 된다.
현재 정본 정책의 인스턴스는 기존 CameraCommandHandler의 static final POLICY 하나만 존재한다.
5. MR6 TaskManager 이식과 남은 작업
MR6 원본은 a1-packages-mr6의 task_manager 브랜치다.
이번 이관은 기존 명령의 실행 책임 분리이며 MR6 관리형 이동 실행기 전체 이식 완료가 아니다.
- AMR·Cleaning 협력: 청소 중단 확인 → 이동 → 도착 확인 → 구동부 정지 확인을 작업 식별자와 연결한다.
- 취소·시간 제한: 취소 요청과 실제 중단을 구분하고, 예외나 연결 종료만으로 완료를 합성하지 않는다.
- 다른 도메인 이관: AirQuality 관측·청소 협력 조건, IoT·UI·Schedule·Update 등 남은 기존 실행 책임을 같은 기준으로 옮긴다.
- 제품 호스트 연결: 권한 검증된 Binder, Android Runtime 시작·종료, AOSP 제품 빌드·부팅 경로를 실제로 연결한다.
기능별 분리는 다른 로봇 제어 SDK를 붙일 때도 같은 공개 계약을 유지하고 어댑터를 바꾸기 위한 기반이다. 특정 로봇 SDK와 이미 호환된다고 주장하지 않는다.
6. 검증 범위
구현 커밋은 5fd2370이며 refactor/blueprint-foundation에 유지한다.
| 확인 범위 | 결과 | 해석의 한계 |
|---|---|---|
| 커밋된 서버 소스만 분리 검증 | JVM 339개 통과, release Java 컴파일 성공 | 보류 TTS 코드에 의존하지 않음을 확인. Android 호스트 기동 시험은 아님 |
| 작업 트리 전체 서버 | JVM 354개 통과 | 보류 TTS 테스트 15개가 포함됨. TTS 제품 연결 완료의 근거가 아님 |
| 공개 SDK | JVM 46개 통과 | 실제 Binder 왕복이 아닌 계약·단위 검증 |
| DeviceAgent | JVM 22개 통과, release APK 빌드 성공 | 실제 기기 설치·주행·청소 수행 전 |
| 정본 폴더·레이어·API·Bundle·Gradle 소스 경계 | 통과 | 런타임 통신 권한 검증을 대신하지 않음 |
| Cleaning 정적 연결 검사 | 3개 통과 | 실제 Android handler 통합 테스트와 구분 |
| 독립 검토 | 세 도메인의 사양·품질 및 통합 품질 검토 승인 | 물리 동작 증거는 아님 |
JVM 결과의 실패·오류·건너뜀은 모두 0이다. 기존 R8 라이브러리/annotation 및 Gradle·Build Tools 경고는 남아 있다. AMR 서비스는 요청 직전에 READY를 검사한다. 제공자 호출 도중 수명주기 전환과 물리 중단을 원자적으로 묶은 구현은 아니다. 실기기 설치·부팅·물리 구동·ROS 2 통신 검증은 이 문서의 코드 이관 증거에 포함하지 않는다. LLM/TTS Dispatcher의 보류 변경은 이관 커밋에 포함하지 않는다.