기능별 수정 위치와 개발 순서
이 문서는 현재 코드에서 출발한 변경 가이드다. 아래 수정 지점과 검증 항목은 기능 개발 시 적용할 제안이며 이미 변경·검증했다는 뜻은 아니다. 기준은 quber/mr7 @ 7695c9a8. 책임은 코드 모듈 기준이며 실제 조직 담당자를 지정하지 않는다.
요구사항이 바꾸는 판단·동작의 소유자부터 수정한다. 이어서 같은 데이터와 메서드를 쓰는 소비자를 검토한다. 표에 등장하는 모든 파일을 일괄 수정하는 것은 아니다.
DA/ = apps/DeviceAgent/app/src/main/java/com/sk/airbot/deviceagent/. 나머지는 저장소 루트 기준 경로다. AIDL은 Bundle method 하나 추가한다고 항상 바꾸지 않는다. 메서드 시그니처·타입·callback 계약이 바뀔 때 양쪽 구현을 함께 변경한다.
더 세부적으로 개발하려면: 45개 구현 작업에서 작업 단위를 고르고, 새 기능 추가 4개 예제로 입력부터 완료 전달까지 연결하세요.
빠른 선택
| 요청된 변경 | 개발 시작점 | 함께 볼 정책·시나리오 |
|---|---|---|
| 청정 모드·팬 동작 | MainApi / BaseCleaningManager | 새 START와 기존 동작 변경 구분 |
| 이동·복귀·우선순위 | CmdPolicy / RobotMovementController | S02·S03·예약·WSS·청정 |
| 프라이버시·야간·잠금 설정 | Settings / SettingPreferences | 저장·즉시 부수 동작·다음 요청 판단 |
| 예약 유형·허용 조건 | Schedule / Receiver / Launcher | 시간 판정과 실제 실행 분리 |
| WSS 보안 동작 | WssPolicyChecker / WssManager | 권한·reason mask·트리거 |
| 클라우드 명령·상태 | IotAgent / MainApi | MQTT 계약·Bundle·결과 callback |
| 센서·장치 제어 | MainService / 장치 wrapper | 제품 상태 소비자·HAL 경계 |
| OTA 조건·진행 | IotAgent / UpdateAgent | jobid·업데이트 중 일반 동작 |
| 공통 API·큐 | DeviceAgent / Stub / TaskExecutor | 여러 호출자의 호환성과 취소 |
01 · 청정 기능을 추가하거나 변경한다
현재 경로: MainApi.setAirCleanerOperation 분기 → newClean → BaseCleaningManager.set → Basic/Moving → fan·AMR → 상태·보고. 새 START와 기존 청정의 STOP·PAUSE·속도 변경은 같은 조건으로 처리되지 않는다.
| 구분 | 파일·분석 지점 | 무엇을 결정하는가 |
|---|---|---|
| 입력 의미가 바뀔 때 수정 | DA/main/api/MainApi.java:523, DA/data/AirCleaningParameter.java |
Bundle action/range/position을 내부 파라미터로 해석 |
| 시작 허용 조건을 바꿀 때 수정 | DA/policy/CmdPolicyManager.java:471, DA/cleaning/AirCleaningPolicy.java:60 |
새 청정 허용·기존 동작 충돌. AirCleaningPolicy 최종 반환값 문제는 정책 확인 |
| 실제 기능을 바꿀 때 수정 | DA/cleaning/BaseCleaningManager.java:213, DA/cleaning/BasicCleaningManager.java:49, DA/cleaning/MovingCleaningManager.java:31 |
기능 선택, fan 동작, area 이동 반복 |
| 상태·결과가 바뀌면 연관 검토 | DA/cleaning/CleaningTransaction.java, DA/report/CleaningReportManager.java |
상태 조회·종료 시각·보고서와 UI/IoT 계약 |
영향 범위: 수동 청정 외에 예약 청정, 야간 모드 적용, 복귀에 따른 선행 중단, 이동형 청정 보고가 영향을 받을 수 있다. 팬 속도 계층을 바꾸면 기본/이동/Follow-me의 공통 사용 여부를 검색한다.
권장 검증: station 안/밖 × BASIC/이동형 × 새 START/실행 중 변경; 잠금·S02·S03 거절; STOP 뒤 재시작; 정상 완료·중단 보고서; callback과 실제 fan/주행 결과 일치.
02 · 이동·복귀·우선순위를 변경한다
현재 경로: API의 setMoveTo는 CmdPolicy를 거쳐 이동하고, 오류 복귀는 ErrorHandler에서 별도 진입한다. 청정·WSS·인터랙션도 이동 기능을 사용하므로 공통 이동 코드는 파급 범위가 넓다.
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 이동 허용 조건 | DA/policy/CmdPolicyManager.java:530, :716, :841 |
setMoveTo / returnToStation / handleReturningByError; 일반 이동과 오류 복귀 예외 분리 |
| 이동 수행·중단·재개 | DA/moving/RobotMovementController.java:255, :300, :737, :777, :808 |
move / moveToStation / pauseCurrentMove / resumeCurrentMove / stopCurrentMove |
| 목적지·장치 연결 | DA/moving/MovingLocationManager.java:34, DA/device/item/amr/AMRMotor.java |
area/position, AMR command, 도착 callback |
| 외부 상태·오류 | DA/main/MainService.java:79, DA/data/ErrorHandler.java:721 |
CurrentPosition·battery callback 및 지연 복귀 요청 |
영향 범위: 이동 청정·보안 순찰·인터랙션·일반 목적지 이동·저전력 복귀. 우선순위/중단 의미를 바꾸면 선점당한 기능의 상태와 callback까지 검토한다.
권장 검증: 일반 이동 중 예약 도착, WSS 중 저전력, stop 후 늦게 온 도착 callback, pause/resume, 도킹 실패 후 상태, S02 뒤 S03. 큐 제거와 실제 주행 정지는 각각 확인한다.
03 · 기기 설정을 추가하거나 변경한다
현재 경로: API 입력 → Settings → 영속 값 저장과 즉시 동작 → 이후 정책 소비. 값 저장만으로 설정 적용이 끝나지 않는다.
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 입력 계약 | DA/main/api/MainApi.java:1431, :1499, :2637 |
잠금·Privacy·야간 시간 API 분기, 값 정규화 |
| 설정 소유자 | DA/settings/Settings.java:329, :433, :913 |
Privacy / applyNightMode / home lock의 저장과 side effect |
| 영속 데이터 | DA/data/pref/SettingPreferences.java |
key·기본값·이전 값 호환·재부팅 복원 |
| 적용 대상 | DA/schedule/ScheduleAlarmReceiver.java:193, DA/wss/policy/WssPolicyChecker.java:48, DA/policy/CmdPolicyManager.java:432 |
같은 설정을 각 정책이 다르게 소비 |
Launcher2 UI에서 설정을 노출할 때: apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/repository/AirBotSettingRepository.java:426의 setNightModeTimeMode와 apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/ui/settings/SettingsViewModel.java:318의 호출을 기준으로 GET/SET·화면 상태를 연결한다. 설정 복원·reset·cloud config 출력도 Settings.java에서 함께 검색한다.
영향 범위: Privacy는 Vision·tilt·SoundFlow·LLM 및 이동/예약/WSS, Night는 화면·LED·음량·청정·보정·IoT/PUI, Lock은 SoundFlow·LLM 및 청정/예약/WSS. 영향표에서 개별 소비자를 확인한다.
권장 검증: 켜기/끄기·반복 설정·재부팅 복원, 기능 실행 중 설정 변경, 다른 입구로 요청했을 때 허용 결과, UI와 IoT 표시 동기화. 새 기본값은 기존 기기에서 key가 없는 경우도 검사한다.
04 · 예약 유형 또는 예약 정책을 변경한다
현재 경로: 예약 데이터 저장 → 알람 → Receiver 재조회 → 조건 검사 → setSchedule callback → Launcher 소비 → 기능 요청. 알람을 받았다는 사실과 기능이 시작됐다는 사실은 별도다.
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 새 타입·필드 | DA/schedule/Schedule.java, DA/schedule/db/ScheduleDao.java, DA/schedule/db/ScheduleDbHelper.java |
타입 값·Bundle/JSON·DB 직렬화. 저장 스키마 변경 시에만 migration 추가 |
| 등록·복원 | DA/schedule/ScheduleManager.java, DA/schedule/ScheduleInitRunner.java |
등록/변경/삭제, 다음 알람, 재부팅 초기화 |
| 실행 허용 | DA/schedule/ScheduleAlarmReceiver.java:134, :256, :291 |
일반 조건·Security 재판정·UPGRADE 우선 차단 |
| 기능 전달 | DA/schedule/ScheduleAlarmReceiver.java:334 |
setSchedule payload와 Launcher 소비 분기, 실제 기능 API까지 추적 |
Launcher2의 저장과 실행은 다른 경로다. apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/repository/ScheduleRepository.java:357은 목록의 type별 모델 구성, :666은 editSchedule 송신이다. 실제 setSchedule callback은 apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/ui/SKMLauncherApp.java:1138에서 Bundle/현재 Activity를 확인한 뒤 ReceivedScheduleInfo와 ExecutableScheduleManager로 연결한다. 새 타입은 apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/model/executableSchedule/ExecutableScheduleManager.java:17의 실행 객체 등록과 :48의 getExecutableSchedule 조회과 apps/SKMLauncher2/app/src/main/java/com/sk/airbot/skmlauncher/data/model/executableSchedule/ExecutableSchedule.java:105의 실행도 검토한다. 타입 값은 DA Schedule.java:38과 Launcher ScheduleActivity.java:30 사이에 맞춰야 한다.
영향 범위: 청정·보안·인터랙션 예약과 UI 편집·클라우드 직렬화·재부팅 복원. 일반 허용 조건 변경은 Security 재허용 경로와 함께 검토한다. Streaming 검사가 로그만 남기는 현재 동작도 보존/변경 여부를 결정한다.
권장 검증: 삭제/비활성·요일/휴일·GPS 시간 예외·중복 알람, night/lock/privacy, 일반 예약과 Security 예외, 반환/도킹 중 예약, 저장된 구버전 데이터, 알람 다음 등록과 실제 동작 성공을 별도로 확인.
05 · WSS 보안 기능 또는 허용 조건을 변경한다
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 호출 계약·역할 | DA/ipc/WssControlStub.java:90, DA/wss/policy/WssPackageValidator.java |
전용 Binder와 FRONT/REMOTE, UID·package 역할 검증 |
| 기본 정책 | DA/wss/policy/WssPolicyChecker.java:48, :171, :180 |
reason bit와 allowed를 함께 평가; basic/patrol 차이 |
| 호출자별 예외 | DA/wss/WssManager.java:520 |
LLM trigger reason 제거 후 재판정 |
| 실행·상태·이벤트 | DA/wss/WssManager.java, DA/wss/data/WssTransaction.java, DA/wss/moving/MovingWssManager.java, DA/wss/eventasset/WssEventAssetManager.java |
시작/정지·순찰·세션·영상 자산 요청. 개별 책임 확인 |
영향 범위: Launcher/Remote의 가용성 표시, 보안 예약, LLM trigger, 이동, Vision/EventAsset, IoT 이벤트. reason bit 의미를 바꾸면 SDK/표시 소비자도 검토한다. 패키지명 해시를 서명 인증서 검증으로 해석하지 않는다.
권장 검증: FRONT/REMOTE × basic/patrol × UI/LLM/예약 trigger, privacy/lock/network/subscription, station 안/밖 battery mask, start-stop 반복, 녹화 실패와 세션 종료. 정책 상세의 실제 예외를 기준으로 기대값 작성.
06 · 클라우드 명령·상태 항목을 추가한다
현재 경로: MQTT topic/payload 해석 → DeviceAgent Bundle 명령 → 제품 정책·실행 → DeviceAgent callback → IotAgent 응답/이벤트. ACK·명령 수락·물리 완료의 의미를 먼저 구분한다.
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 클라우드 입력 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/mqtt/topic/CmdTopic.java:359 |
setCmdTopic의 topic switch와 handler. :460의 subscribeSetBackground는 Bundle 구성·전달의 기존 예시 |
| 제품 동작 | DA/main/api/MainApi.java:150 및 해당 도메인 |
새 Bundle method 또는 기존 파라미터 확장, 정책 입구 연결 |
| 결과·상태 송신 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/IotAgent.java:741 |
callback method별 처리와 cloud response/event |
| 통신 계약이 바뀔 때만 | apps/DeviceAgent/app/src/main/aidl/com/sk/airbot/devicecontrol/IDeviceControl.aidl |
AIDL signature/type 변경 시 SDK·양쪽 구현 함께 반영 |
영향 범위: 앱이 같은 DeviceAgent API를 쓰면 UI 동작도 영향. callback 이름/값 변경은 기존 클라우드 소비자, 상태 조회, OTA job 경로와 충돌 여부를 검토한다. backend의 실제 schema와 배포는 이 저장소 밖의 협의 항목이다.
권장 검증: 누락/잘못된 필드·구버전 payload·중복 수신·연결 끊김/재접속, 정책 거절 응답, 지연 완료·실패 callback, 앱에서 같은 API 호출. MQTT 송신 성공을 장치 완료로 표시하지 않는다.
07 · 센서 상태 또는 장치 제어를 변경한다
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 상태 수신 | DA/main/MainService.java:79 |
AMR reportCmd를 battery/position/map 등 도메인 상태로 분기 |
| 도메인 상태 | DA/device/manager/BatteryManager.java:195, DA/data/ErrorHandler.java:721 |
배터리 측정·오류 분류·복귀 판단은 분리되어 있음 |
| fan 출력 | DA/device/item/mcu/MCUFanBLDC.java:283, :305 |
setBLDCControl overload와 호출자별 mode/speed |
| AMR 출력 | DA/device/item/amr/AMRMotor.java, apps/AMRAgent/java/com/sk/airbot/amragent/AMRCmdDispatcher.java |
wrapper → Binder/전송 계층. 실제 변경 대상 경로인지 호출 추적 |
영향 범위: 상태 값 하나가 정책·화면·IoT·보고서로 전파될 수 있다. 센서 단위/범위/미수신 의미 변경은 모든 getter 소비자를 검색한다. MCUAgent serial 경로와 DeviceAgent vendor HAL 경로는 실제 호출 관계를 확인한 뒤 선택하며 무조건 양쪽 수정하지 않는다.
권장 검증: 정상/경계값/invalid/미수신·재연결, 중복/순서 뒤바뀐 callback, 상태 초기값, 장치 없는 단위 검증과 실제 HAL/firmware 검증 분리. vendor 구현·프로토콜 변경은 외부 담당과 계약 대조.
08 · OTA 허용 조건 또는 진행을 변경한다
| 구분 | 파일·분석 지점 | 변경 시 확인 |
|---|---|---|
| 원격 요청 입장 조건 | apps/IotAgent/app/src/main/java/com/sk/airbot/iotagent/IotAgent.java:1748 |
onDownloadUpdateAgent, jobid 유무로 battery/station/실행상태 검사 적용이 다름 |
| 제품 업데이트 모드 | DA/ota/OTAManager.java:8, DA/event/StateManager.java:149 |
SoundFlow/LLM 동작과 업데이트 중 API 차단 |
| 업데이트 요청·엔진 | apps/UpdateAgent/java/com/sk/airbot/updateagent/UpdateAgent.java:71, apps/UpdateAgent/java/com/sk/airbot/updateagent/UpdateManager.java:43 |
OTAUpdate 처리와 UpdateEngine callback |
| AMR·MCU 후속 갱신 | DA/update/UpdateManager.java |
구성요소 버전 확인·timeout·후속 요청 |
영향 범위: 클라우드 job 상태·StartupService·재부팅, 진행 중 일반 API/예약/WSS, local 업데이트 경로. 정책 완화가 물리 업데이트 안전 조건까지 충족한다는 뜻은 아니다.
권장 검증: jobid 있음/없음 × station/battery × 보안/Live View/vital, UpdateEngine 실패/완료·재부팅·버전 확인·timeout. 실제 설치 검증은 MR6 빌드/인증서/백업 절차로 별도 수행.
09 · 공통 API 또는 실행 큐를 변경한다
시작점: DA/DeviceAgent.java:264의 sendModuleCommand, DA/ipc/TaskExecutor.java:38의 큐, DA/ipc/WssControlStub.java:90의 WSS 입구. 실행 경계에서 thread/상태 소유권을 먼저 확인한다.
직접 변경과 영향: Bundle key만 확장하면 parser·producer·consumer를 맞춘다. AIDL의 signature·callback 구조를 바꾸면 DeviceAgent, SDK, Launcher/IotAgent 등 실제 클라이언트를 함께 검토한다. 큐의 message ID·취소를 바꾸면 같은 큐를 쓰는 WSS/Streaming과 기존 예약 runnable을 검사한다. MainApi 전체를 우회하는 새 입구는 정책 적용 책임을 명시한다.
현재 주의점: Binder 반환 0은 작업 완료 증거가 아니고, removeMessages는 실행 중 장치 정지를 보장하지 않는다. WSS/Streaming ID 영역의 충돌 가능성은 검토 쟁점에 기록되어 있다.
권장 검증: 구/신 클라이언트 호환, callback 해제/프로세스 사망, 동시 요청, 대기 중 취소/실행 중 취소, 중복 message ID, 예외 뒤 다음 작업 실행, late callback의 이전 세션 오염.
개발자가 남길 변경 기록
작업 티켓에는 변경한 요구사항 → 기준 시나리오 → 직접 수정 파일/메서드 → 연관 검토 결과 → 영향받는 계약/상태 → 회귀 검증 결과를 기록한다. “해당 없음”도 이유를 적는다. 도메인 내부 계산만 바뀌는 작업과 API/저장 스키마가 바뀌는 작업의 검증 범위는 다르다.