add commit

2026-02-28 12:45:29 +09:00
parent 392640a686
commit d9a6b6d02b
400 changed files with 52300 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,216 @@
+# VasCURA589 코드 분석 (com/laseroptek/raman)
+
+이 문서는 `app/src/main/java/com/laseroptek/raman` 폴더를 기준으로 구조와 동작을 요약한 분석 문서입니다.  
+요청 경로의 `com/leaseroptek/raman`는 오타로 보이며, 실제 패키지는 `com/laseroptek/raman`입니다.
+
+## 1) 폴더 개요
+
+- 분석 대상 파일 수: **246개**
+- 상위 패키지 구성
+  - `const` (12): 프로토콜/테이블/상수
+  - `data` (57): 모델, DB/Serial/Preference 데이터 소스
+  - `di` (4): Hilt DI 모듈
+  - `navigation` (5): 라우트/네비게이션 그래프
+  - `repository` (3): 데이터 접근 추상화 계층
+  - `ui` (123): Compose UI + ViewModel
+  - `utils` (40): 확장 함수, 보조 유틸, 커스텀 컴포넌트
+
+## 2) 아키텍처 요약
+
+전체적으로 **Compose + Hilt + Room + DataStore + Serial(NDK)** 구조입니다.
+
+- Application
+  - `VasCURA589App`: Hilt 진입점, Timber 로그 트리 설정
+- Activity
+  - `ui/MainActivity`: 전체 초기화 오케스트레이션, 풀스크린/시스템바 제어, APK 선택 이벤트 처리
+- Presentation
+  - `ui/screens/...`: Home, Info, Config, Lock, Engineer 화면
+  - 공용 상태는 `MainViewModel`이 중심으로 보유
+- Domain/Data Access
+  - `repository/*Repository`: Serial/Preference/DB 접근 래퍼
+- Data Source
+  - `data/source/serial/SerialPort`: native `serial_port` 라이브러리 로딩 + FD 기반 통신
+  - `data/source/db/*`: Room DB(`SerialLog`) 접근
+  - `PreferenceRepository`: DataStore 기반 앱 설정/테이블/카운트 저장
+
+## 3) 실행 흐름 (부팅~운영)
+
+1. `MainActivity.onCreate()`
+2. `initialize()`에서 `MainViewModel.performFullInitialization()` 실행
+3. 초기화 완료 후 UI 활성화(`setInitialized(true)`)
+4. 시리얼 시작
+   - `txPacketOnce()`: 초기 설정 패킷 송신
+   - `rxPacketLoop()`: 수신 루프 + 패킷 파싱/상태 반영
+   - `txPacketLoop()`: 주기적 heartbeat 성격 송신
+
+핵심 포인트:
+- 초기화는 IO 스레드에서 병렬 로딩(`launch + joinAll`)로 처리
+- `MainScreen`은 `isInitialized`를 기준으로 로딩 화면 -> 본 화면 전환
+- 통신 타임아웃 감시(`monitorConnectionTimeout`)로 안정성 상태 추적
+
+## 4) 주요 패키지별 역할
+
+### `ui/screens/main`
+- `MainViewModel`: 앱의 사실상 중앙 상태 저장소
+  - 레이저 파라미터(펄스/플루언스/반복률), 카운터, 경고/에러, 온도, DCD, 에너지 디텍터 상태 관리
+  - 시리얼 TX/RX 패킷 생성/파싱
+  - Preference 로드/저장, DB 로그 적재/트리밍
+  - 핸드피스 타입 변경 시 에너지/Hz 테이블 재적용
+
+### `ui/screens/home` (30개)
+- 실제 시술/운영 메인 UI
+- 슬라이더 기반 파라미터 조절, 스탠바이/발진, 카운트/프리셋/DCD 제어
+
+### `ui/screens/info` (6개)
+- 모니터링/차트 화면
+- `InfoViewModel`은 차트 라인 표시 상태(체크박스)만 관리
+- 실데이터(온도, 램프카운트 등)는 `MainViewModel`에서 수신
+
+### `ui/screens/config` (7개)
+- 볼륨, 가이드빔, 언어/시간 설정, 엔지니어 모드 진입 지점
+
+### `ui/screens/engineer` (38개)
+- 서비스/캘리브레이션/로그/버전/임계치/시리얼번호 등 유지보수 기능
+- Voltage Table/수명/온도 한계/Energy detect 기준값 조정
+
+### `ui/screens/lock` (3개)
+- PIN 기반 잠금/해제 플로우
+
+## 5) 시리얼 통신 구조
+
+- 송신: `MainViewModel.txPacket()`
+  - `READ_WRITE` + `CMD`로 패킷 조합
+  - WRITE 시 CS(checksum) 포함
+- 수신: `rxPacketLoop()`
+  - 버퍼 누적 후 `findCompletePackets()`로 STX(0x21)~ETX(0x0d) 패킷 분리
+  - `procRxPacket()`에서 CMD별 모델 변환 및 상태 업데이트
+
+처리 예:
+- `CMD.LASER_STATUS`: 발진 상태 반영, 카운트 증가, 알림음
+- `CMD.HAND_PIECE`: 타입 변경 감지 후 테이블/각도/상태 재초기화
+- `CMD.TEMPERATURE`: 차트 큐 갱신 + 임계값 비교
+- `CMD.ENERGY_DETECT`: 버전/마운트/측정 상태 처리 및 Good/Not Good 응답
+
+## 6) 저장 전략
+
+- **DataStore (`PreferenceRepository`)**
+  - 카운트, 볼륨, 가이드빔, 프리셋, Spray DCD, Voltage Table, 임계값, 시리얼 번호 리스트 등
+- **Room (`RamanDatabase`, `SerialLogDao`)**
+  - 주요 시리얼 패킷 로그 저장
+  - `trimLogs(limit)`로 로그 최대 개수 유지
+
+## 7) 눈에 띄는 구현 특성
+
+- `MainViewModel`에 상태/로직이 집중된 구조(단일 허브)
+- 디버그 로그(Timber)와 패킷 헥사 덤프 활용
+- 미리보기/테스트를 위한 fake serial repository 제공
+- 패키지 네이밍이 일부 혼재:
+  - 예: 파일 경로는 `data/source/db`인데 패키지 선언은 `data.datasource.db`인 클래스가 존재
+
+## 8) 빠른 참고 파일
+
+- 앱 진입: `VasCURA589App.kt`, `ui/MainActivity.kt`
+- 내비게이션: `navigation/Routes.kt`, `navigation/graphs/MainNavGraph.kt`
+- 핵심 로직: `ui/screens/main/MainViewModel.kt`
+- 시리얼: `data/source/serial/SerialPort.kt`, `repository/SerialPortRepository.kt`
+- 설정 저장: `repository/PreferenceRepository.kt`
+- 로그 DB: `data/source/db/*`, `repository/DatabaseRepository.kt`
+
+## 9) MainViewModel.kt 별도 분석
+
+### 개요
+
+- 파일: `app/src/main/java/com/laseroptek/raman/ui/screens/main/MainViewModel.kt`
+- 규모: 약 **2,288 라인**
+- 역할: 앱 전체의 공용 상태 + 시리얼 프로토콜 처리 + 로컬 저장소 동기화를 한곳에서 담당하는 **중앙 오케스트레이터**
+
+### 의존성 주입 구조
+
+- `PreferenceRepository`: DataStore 기반 영속값 로드/저장
+- `SerialPortRepository`: 시리얼 포트 open/write/close
+- `DatabaseRepository`: 시리얼 로그 조회/저장/트리밍
+- `DispatcherProvider`: 코루틴 디스패처 추상화
+- `Context`: 알림음 재생 및 시스템 리소스 접근
+
+### 상태(State) 도메인 분류
+
+- UI/초기화 제어
+  - `isInitialized`, 팝업 노출 플래그, `apkUpdateEvent`
+- 레이저 파라미터
+  - `pulseAngle`, `fluenceAngle`, `repetitionAngle`
+  - `energyTable`, `hzTable`, `voltageTable`, `fluenceList`, `repetitionList`
+- 프리셋/옵션
+  - `presetList`, `selectedPresetIndex`
+  - `sprayDcdList`, `selectedSprayDcdIndex`
+- 카운터/수명
+  - `laserCount`, `lampCount`, `dcdCount`, `hpCount`, `lifeTime`, `opTimeHour`
+- 장비 상태 패킷
+  - `laserStatus`, `handPiece`, `warning`, `error`, `version`
+  - `temperature`, `temperature_write`, `qSwitch`, `dcdGas`, `sprayDcd`, `oven`, `purgeBubble`
+- 에너지 디텍션
+  - `energyVersion`, `energyHandpiece`, `energyControl`, `energyMeasured`, `energyMeasuredWrite`, `energyDetectRefer2`
+- 모니터링/로그
+  - `chartDataQueue`, `serialLogList`, `isCommunicationStable`
+
+### 핵심 메서드 흐름
+
+- 초기화
+  - `performFullInitialization()`
+  - DB 정리/온도 이력 로딩 후, 다수의 preference 로딩을 `launch + joinAll`로 병렬 수행
+- 시리얼 송신
+  - `txPacketOnce()`: 버전/QSwitch/GuideBeam/DCD/Spray 기본값 송신
+  - `txPacketLoop()`: 주기적 명령(핸드피스, 샷카운트, 경고, 온도) 폴링
+  - `txPacket()`: CMD/READ_WRITE에 따라 실제 프로토콜 패킷 생성
+- 시리얼 수신
+  - `rxPacketLoop()`: 포트 수신 collect
+  - `findCompletePackets()`: 버퍼에서 STX~ETX 완성 패킷 분리
+  - `procRxPacket()`: CMD 별 디코딩/상태 반영/로그 저장
+  - `monitorConnectionTimeout()`: 응답 지연 watchdog
+
+### 비즈니스 로직 포인트
+
+- `CMD.HAND_PIECE` 수신 시
+  - 핸드피스 변경 여부 확인 후 레이저 상태/카운트/테이블/슬라이더 초기화
+  - handpiece type별 lifetime 카운트 누적
+- `CMD.LASER_STATUS` 수신 시
+  - 레이저 ON 상태에서 샷/램프/HP/DCD 카운트 갱신
+  - 조건에 따라 알림음 재생 및 스탠바이 전환 처리
+- `CMD.TEMPERATURE` 수신 시
+  - 차트 큐에 타임스탬프 데이터 적재
+  - 설정 임계값(`temperature_write`)과 비교해 경고/에러 조건 반영
+- `CMD.ENERGY_DETECT` 수신 시
+  - measured 값과 refer2 기준 비교 후 Good(0x47)/Not Good(0x4E) 응답 송신
+
+### 파라미터 계산 로직
+
+- `txLaserStatusEntry(laserStatus: Int)`
+  - 현재 각도 -> step 변환
+  - step -> pulse/fluence/repetition 매핑
+  - `(pulse, fluence)`로 energy 조회
+  - `calculateInterpolatedC()`로 목표 전압 계산(선형 보간)
+  - 최종 `LaserStatus` 패킷 송신
+
+### 저장소 동기화 패턴
+
+- 상태 변경 직후 `save*ToPreference()` 호출하는 즉시 반영형 패턴
+- 앱 시작 시 `load*FromPreference()`로 메모리 상태 복원
+- 시리얼 로그는 특정 CMD만 DB에 적재하고, `trimSerialLog()`로 최대 개수 유지
+
+### 설계 관점 평가
+
+- 장점
+  - 장비 프로토콜 처리, UI 상태, 저장소 동기화가 한 ViewModel에서 일관되게 연결됨
+  - 초기화 병렬화로 부팅 지연 완화
+  - 통신 watchdog/버퍼 파싱 등 실장비 대응 로직이 명확함
+- 트레이드오프
+  - 단일 ViewModel 책임이 매우 큼(상태/함수 밀집)
+  - 기능 분리(예: SerialHandler, PreferenceSync, LaserDomain) 여지가 큼
+
+### 유지보수 시 우선 확인 포인트
+
+- 신규 CMD 추가 시
+  - `txPacket()` 인코딩 + `procRxPacket()` 디코딩을 함께 확장
+- 파라미터 표 변경 시
+  - `loadFluenceTable()`, `loadHzTable()`, `calculateInterpolatedC()` 영향 확인
+- 성능/안정성 이슈 시
+  - `txPacketLoop()` 주기, `RX_TIMEOUT_THRESHOLD`, DB 로그 적재량 점검