세부 개발 지도
9개 기능을 45개 구현 작업으로 나눴습니다. 한 행을 개발 티켓의 시작점으로 사용하고, 바뀌는 계약과 아래쪽 소비자까지 따라갑니다. 기준은 quber/mr7 @ 7695c9a8이며 아래 검증은 개발 시 수행할 항목입니다.
DA/는 apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/입니다. 같은 셀에서 디렉터리를 생략한 파일은 앞 파일과 같은 디렉터리입니다. 메서드 이름과 자세한 설명은 기능별 수정표, 기존 구조·연결 번호는 Atlas를 함께 보세요.
기존 도메인 확장과 신규 실행 객체의 구분
입력 계약, 정책 소유자, 실행 수명, 상태·결과 소비자를 먼저 정합니다. 기존 도메인의 옵션이면 기존 실행 경로를 확장하고, 독립 상태·취소·자원 수명이 필요할 때 새 실행 객체를 검토합니다. 이 기준은 개발 제안이며 현재 구현을 변경했다는 뜻이 아닙니다.
새 기능 추가 순서와 예제 4개 →기능별 작업 목록
청정 | 이동·복귀 | 설정·영속 데이터 | 예약 | 보안·WSS | 클라우드 명령·상태 | 센서·장치 | OTA·업데이트 | 공통 API·큐·callback
청정 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 새 입력 옵션 | DA/main/api/MainApi.java:523 · DA/data/AirCleaningParameter.java:23 |
action / mode / speed / position → 내부 파라미터. 외부 mode와 내부 mRange 명칭을 구분 | Launcher·IoT producer와 예약 payload | 필드 누락 시 기존 동작; 범위 밖 값·잘못된 타입 |
| 새 청정 방식 | DA/cleaning/BaseCleaningManager.java:213 · BasicCleaningManager.java:49 · MovingCleaningManager.java:31 |
상위 선택 → 기존 Basic/Moving 실행. 독립 실행 객체 추가 여부는 상태·수명 차이로 판단 | 공통 Handler·fan·이동·STOP 경로 | START/STOP/PAUSE/RESUME과 실행 중 옵션 변경 |
| 시작 허용·선행 중단 | DA/policy/CmdPolicyManager.java:471 · DA/cleaning/AirCleaningPolicy.java:60 |
새 시작과 기존 청정 갱신의 적용 조건을 구분 | 예약·WSS·복귀의 충돌 | station·lock·S02/S03·현재 실행 기능 조합 |
| 상태·조회·알림 | DA/cleaning/CleaningTransaction.java:68 · DA/cleaning/BaseCleaningManager.java:596 |
param/action 상태와 startAirClear callback의 action·mode | UI·정책 getter·클라우드 표시 | 수락 직후와 장치 완료 후의 상태; 늦은 callback |
| 완료 보고 | DA/report/CleaningReportManager.java · DA/cleaning/BaseCleaningManager.java:666 |
영역별 결과·시간·보고서 저장/전달 | 보고 DB·IoT·Launcher 이력 | 완료·중단·오류의 보고 중복/누락 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
이동·복귀 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 목적지 해석 | DA/moving/MovingLocationManager.java:34 |
area/position을 기존 이동 요청으로 연결 | 지도 변경·삭제된 목적지·청정/WSS 경유 | 유효·미등록·삭제된 area |
| 일반 이동 정책 | DA/policy/CmdPolicyManager.java:530 |
setMoveTo 허용과 실행 중 기능 정리 | 수동 이동·보안 순찰·이동 청정 | privacy/lock·현재 이동/청정·재요청 |
| 복귀 정책 | DA/policy/CmdPolicyManager.java:716 · :841 · DA/data/ErrorHandler.java:721 |
사용자 복귀와 오류 지연 복귀를 구분 | 배터리·충전·S02/S03·예약 | 저전력 전환·도킹 실패·중복 복귀 |
| 정지·재개 | DA/moving/RobotMovementController.java:737 · :777 · :808 |
pauseCurrentMove / resumeCurrentMove / stopCurrentMove | 선점된 기능의 transaction·완료 callback | 취소 후 도착 callback·정지 뒤 재개·새 요청 |
| 장치 명령·결과 | DA/device/item/amr/AMRMotor.java · DA/main/MainService.java:79 |
장치 명령과 report 수신은 서로 다른 방향 | AMRAgent·vendor 프로토콜·CurrentPosition 소비자 | 명령 거절·연결 단절·도착 결과와 위치 일치 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
설정·영속 데이터 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 설정 입력·조회 | DA/main/api/MainApi.java:1431 · :1499 · :2637 |
API 이름·문자열 값·GET/SET 의미 | Launcher·IoT·SDK | 잘못된 값·동일 값 반복·GET 일관성 |
| 저장 key·기본값 | DA/data/pref/SettingPreferences.java |
영속 key와 기존 기기의 key 미존재 의미 | 재부팅·reset·기존 설치 데이터 | 구버전 저장소·누락 key·재부팅 |
| 즉시 적용 | DA/settings/Settings.java:329 · :433 · :913 |
Privacy / Night / Lock의 저장과 부수 동작 | Vision·tilt·화면·음량·SoundFlow·LLM | 실행 중 변경·부분 적용 실패·원복 |
| 정책 읽기 | DA/schedule/ScheduleAlarmReceiver.java:193 · DA/wss/policy/WssPolicyChecker.java:48 · DA/policy/CmdPolicyManager.java:432 |
같은 설정도 일반·예약·WSS 판단은 별도 | 보안 재허용·LLM trigger 예외 | 입구별 allowed/reason 기대표 |
| 화면 노출 | apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/repository/AirBotSettingRepository.java:426 · apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/ui/settings/SettingsViewModel.java:318 |
repository 송수신 → ViewModel → 표시 | 외부 변경 시 화면 갱신·재진입 | UI 변경/원격 변경/재부팅 후 같은 값 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
예약 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 타입·직렬화 | DA/schedule/Schedule.java:38 · DA/schedule/db/ScheduleDao.java |
type와 payload의 DB/Bundle 표현 | Launcher 타입·cloud payload | 새/기존 type 왕복·알 수 없는 type |
| 저장·스키마 | DA/schedule/db/ScheduleDbHelper.java · DA/schedule/ScheduleManager.java |
기존 컬럼으로 충분한지 먼저 판정; 컬럼 변경 때 migration | 기존 예약·편집·삭제 | 기존 DB 업그레이드·오래된 예약 보존 |
| 알람 수명 | DA/schedule/ScheduleInitRunner.java · DA/schedule/ScheduleAlarmReceiver.java:134 |
재부팅 복원·다음 알람·수신 후 재조회 | 비활성/삭제·요일·중복 수신 | 재부팅·시간 변경·삭제 후 남은 알람 |
| 실행 허용 | DA/schedule/ScheduleAlarmReceiver.java:256 · :291 |
일반 차단과 Security 재판정·UPGRADE 우선 | Night·Lock·Privacy·배터리·WSS | 일반/보안 예약별 허용표; Streaming 로그 전용 경로 |
| Launcher 실행 등록 | apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/ui/SKMLauncherApp.java:1138 · apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/model/executableSchedule/ExecutableScheduleManager.java:17 |
setSchedule → ReceivedScheduleInfo → 실행 객체 조회 | Activity 존재·보안 편집 상태·최종 기능 API | 저장은 성공하지만 미실행되는 경우; 실제 기능 정책 재판정 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
보안·WSS · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 전용 호출 계약 | DA/ipc/WssControlStub.java:90 · DA/wss/policy/WssPackageValidator.java |
caller 역할과 전용 IPC; 일반 MainApi와 구분 | FRONT/REMOTE·SDK·client | 허용/미허용 caller·동시 호출 |
| 가용성 이유 | DA/wss/policy/WssPolicyChecker.java:48 · :171 · :180 |
allowed와 reason bit를 함께 해석 | UI 버튼/사유 문구·원격 호출 | basic/patrol·battery/station·privacy/lock |
| 트리거 예외 | DA/wss/WssManager.java:520 |
LLM trigger에서 reason 제거 후 재판정 | 수동·예약·LLM 동작 차이 | 같은 기기 상태에 대해 trigger만 변경 |
| 세션·순찰 | DA/wss/data/WssTransaction.java · DA/wss/moving/MovingWssManager.java |
현재 세션과 이동 실행의 소유권 | 청정/복귀 선점·중단·장치 callback | start-stop 반복·취소 후 이전 결과 |
| 영상·이벤트 | DA/wss/eventasset/WssEventAssetManager.java |
보안 이벤트와 별도 EventAsset 처리 연결 | Vision·clip·업로드·IoT | 촬영/업로드 실패·세션 종료 뒤 callback |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
클라우드 명령·상태 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| topic 분기 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/mqtt/topic/CmdTopic.java:359 |
topic/payload → 기존 handler 또는 새 분기 | backend schema·subscription | 누락 필드·미지원 명령·중복 수신 |
| Bundle 매핑 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/mqtt/topic/CmdTopic.java:460 · DA/main/api/MainApi.java:150 |
외부 payload와 제품 method/파라미터 변환 | 같은 API를 쓰는 앱·정책 | cloud/app 입력의 동등성 |
| 실행 허용 | DA/event/StateManager.java:149 · 해당 도메인 정책 |
제품 모드와 기능 정책을 거쳐 실행 | OTA·wizard·잠금·다른 기능 | 수신 성공/거절/실행 실패 구분 |
| 응답·이벤트 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/IotAgent.java:741 |
callback method와 응답 payload 소비 | backend·UI 상태·지연 완료 | 수락/진행/완료 시점·중복 callback |
| 재접속·배포 선택 | apps/IotAgent/Android.mk |
소스 변경과 제품에서 선택되는 APK 확인 | prebuilt IotAgent.apk·backend 배포 | 수정 APK가 실제 제품에 들어갔는지 hash·동작 확인 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
센서·장치 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 수신 필드 | DA/main/MainService.java:79 |
reportCmd → battery/position/map 상태 | 장치 firmware·도메인 getter | 누락·미수신·순서 역전 |
| 상태 계산 | DA/device/manager/BatteryManager.java:195 |
단위·범위·충전/이동 가능성 | 정책·복귀·UI·IoT | 경계값·초기값·invalid |
| fan 제어 | DA/device/item/mcu/MCUFanBLDC.java:283 · :305 |
mode/speed → vendor 장치 명령 | 청정·열·tilt 사용처 | 명령 값과 실제 RPM·정지 |
| AMR 전송 | DA/device/item/amr/AMRMotor.java · apps/AMRAgent/java/com/sk/airbot/amragent/AMRCmdDispatcher.java |
wrapper / typed Binder / 장치 전송 | 외부 AMR 구현·프로토콜 | 지원 명령·timeout·연결 복구 |
| 오류 처리 | DA/data/ErrorHandler.java:721 |
오류 상태와 후속 복귀 | 기능 중단·오류 이력·알림 | 발생/해제·중복·복귀 중 재오류 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
OTA·업데이트 · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 원격 admission | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/IotAgent.java:1748 |
jobid 유무에 따른 검증 차이 | local 업데이트·cloud job | jobid 있음/없음 × battery/station |
| 제품 동작 제한 | DA/ota/OTAManager.java:8 · DA/event/StateManager.java:149 |
OTA 상태와 LLM/SoundFlow 제어 | 일반 API·예약·WSS | 업데이트 중 요청·실패 후 정상 복귀 |
| OS 업데이트 엔진 | apps/UpdateAgent/java/com/sk/airbot/updateagent/UpdateAgent.java:71 · apps/UpdateAgent/java/com/sk/airbot/updateagent/UpdateManager.java:43 |
OTAUpdate → UpdateEngine callback | 진행률·재부팅·cloud 상태 | 다운로드/검증/적용 실패·완료 |
| 부품 버전 갱신 | DA/update/UpdateManager.java |
AMR·MCU 후속 요청과 timeout | firmware 호환·버전 조회 | 부분 실패·지연 응답·재시도 |
| 제품 검증 | packages.mk · apps/UpdateAgent/Android.mk |
제품 선택 및 실제 설치물 확인 | 서명·시스템 앱·부팅 | MR6 산출물·인증서·백업·설치 hash |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
공통 API·큐·callback · 세부 작업
| 바꾸려는 부분 | 첫 수정·분석 파일 | 전달 계약 / 소유 책임 | 함께 분석할 영향 | 완료 판단용 검증 |
|---|---|---|---|---|
| 일반 명령 입구 | DA/DeviceAgent.java:264 · DA/main/api/MainApi.java:150 |
Bundle method를 기존 입구에 연결 | 모든 producer·제품 모드 | 알 수 없는 method·누락 키·동시 요청 |
| AIDL 변경 판단 | apps/DeviceAgent/app/src/main/aidl/com/sk/airbot/devicecontrol/IDeviceControl.aidl |
Bundle 내용 확장과 typed signature 변경 분리 | 서비스·SDK·모든 실제 client | 구/신 클라이언트 호환 |
| 전용 큐 | DA/ipc/TaskExecutor.java:38 · DA/ipc/WssControlStub.java:90 |
메시지 ID·큐 순서·handler 실행 수명 | WSS/Streaming 충돌·정리 | 대기 취소/실행 중 취소·예외 뒤 후속 실행 |
| 공유 상태 소유 | DA/event/StateManager.java · DA/cleaning/CleaningTransaction.java |
제품 상태와 도메인 상태를 구분 | getter 소비자·thread·초기화 | 소유자별 상태 전이·중복/지연 callback |
| 결과 전달 | DA/app/AppCmd.java · DA/cleaning/BaseCleaningManager.java:596 |
callback route별 수신자와 payload | Launcher·IoT·SDK·client death | 구독/해제·수신자 종료·재등록·최종 상태 조회 |
상위 기능 흐름·정책 근거 · 교차 시나리오와 회귀 범위
변경 규모에 따라 선택할 범위
| 변경 규모 | 필요한 구현 | 조건부로 늘어나는 범위 |
|---|---|---|
| 기존 계산·조건만 변경 | 해당 도메인과 그 값을 읽는 정책 검토 | 입력/저장/IPC 형식이 그대로라면 계약 변경은 불필요 |
| 기존 명령에 옵션 추가 | producer → parser → 내부 파라미터 → executor → 결과 검토 | 재부팅 유지가 요구될 때 저장; 예약에서도 쓸 때 예약 payload |
| 새 사용자 기능 | 계약·정책·실행·상태·결과·실패/취소의 전체 세로 경로 | 노출 채널에 따라 Launcher·IoT·SDK를 선택 |
| 새 장치 기능 | 제품 기능 + wrapper/프로토콜 + 결과 수신 | 실제 호출하는 HAL/firmware·권한·제품 탑재 경계 |
| 새 앱/서비스 | Manifest·권한·빌드 편입·연결/해제·버전 계약 | 별도 process가 필요할 때 IPC, 시스템 권한이 필요할 때 플랫폼 협의 |
Connections
개발 지도 · 새 기능 구현 가이드 · 수정 위치 · 정책 · 영향 범위