raman/docs/change_summary_2026-03-04.md

변경 요약 (2026-03-04)

이 문서는 현재 git diff 기준으로 반영된 변경을 정리합니다.

1) 시리얼 초기 전송 누락(Startup race) 대응

변경 파일

• app/src/main/java/com/laseroptek/raman/ui/MainActivity.kt
• app/src/main/java/com/laseroptek/raman/ui/screens/main/MainViewModel.kt

변경 내용

• MainActivity.initialize()의 시리얼 시작 순서를 조정
  • 이전: txPacketOnce() -> rxPacketLoop() -> txPacketLoop()
  • 이후: rxPacketLoop() -> txPacketOnce() -> txPacketLoop()
• MainViewModel.txPacketOnce()를 코루틴(IO)에서 실행하도록 변경
• waitUntilSerialReady() 추가
  • 최대 2초 동안 20ms 간격으로 FD != -1 확인
  • 준비 실패 시 에러 로그 후 초기 TX 중단
• 관련 설명 주석 추가

의도/효과

• 앱 시작 직후 open() 완료 전 TX가 먼저 발생하는 레이스를 완화/방어
• 포트 미준비 상태(FD == -1)에서 write가 호출되어 초기 패킷이 누락되는 문제를 줄임

2) HandPiece 기본값 변경

변경 파일

• app/src/main/java/com/laseroptek/raman/data/model/serial/HandPiece.kt

변경 내용

• HandPiece.type 기본값 변경
  • 이전: 1
  • 이후: 0

영향 포인트

• 기본 인스턴스 생성 시 handpiece type의 초기 상태가 달라집니다.
• 초기 테이블 선택/상태 표시 로직에서 기본 타입 가정이 있다면 함께 점검 필요합니다.

3) 문서화

추가/수정 파일

• docs/serial_tx_startup_race.md (신규)
• README.md (Troubleshooting 링크 추가)

내용

• FD(File Descriptor) 개념
• startup race 원인 및 수정 내역
• 왜 TX에서 직접 open하지 않았는지
• 확인 포인트

4) 참고

• 현재 요약은 커밋 로그가 아닌 워크트리 git diff 기준입니다.
• 빌드 검증은 gradlew CRLF 문제로 로컬 셸에서 미실행 상태입니다.