docs: v6 전체 업데이트 (1.0.0-design, VBTFW0116 짝, 2026-05-26 기준)

a1042b8(v5) 이후 13개 커밋을 반영해 세 문서 일괄 갱신. USER_GUIDE.md: - 헤더: VBTAND0101 → 1.0.0-design (versionCode 24), 권장 펌웨어 VBTFW0116 - PIN DEMO 자동통과 안내 (배포 전 정리 필요) - Personalization 평행 2-카드 (Maximum Bladder Capacity + Catheter Threshold) - Sensor Alignment 리디자인 (38sp 큰 타이틀, pubic bone 빨강, 3-stop gradient, Canvas 화살표/아치 제거) - Measurement Screen top bar에 Home 아이콘 + Voiding/ 텍스트 + 48sp Recorded Dialog - Auto Scan 600ms로 단축 + 측정 사이클 ~330ms 실측 안내 - 설정 패널 폰/태블릿 자동 폰트 분기 (fontScale 표 추가) - Dev Mode 추가 기능 (DeviceScan 측정 직진입 버튼, Status 더미 주입) - Navigation에 placementFromMonitoring 라우팅 분기 설명 + startFromHome fix VesiScan_Android_Pipeline_Summary.md: - v6 주요 변경 요약 (헤더에 한눈 보기) - §5.1 BLE 통신: Connection Parameter 협상 (MTU 247, CONN_PRIORITY HIGH), maa throttle state-based gate, 측정 사이클 실측 표 - 측정 흐름: Auto/Single Scan 600ms 동기화 + Voiding 시 자동 stop - 연속 스캔 동작: Placement loop 1000 → 600ms + v6 화면 디자인 변경 박스 - §14 BLE 명령어 포맷: VBTFW0116 신규 사항 (pending slot 1→8, 안드로이드 짝꿍 변경) - §22 향후 과제: v6 완료 항목 12개 추가 docs/ALGORITHM_COMPARISON.md: - Placement loop 1s → 600ms, canSendMaa 게이트 단계 명시 - v6 BLE 사이클 실측 (330ms 평균) - Measurement Modes: 800 → 600ms, Voiding 자동 stop - 신규 섹션: BLE maa Throttle — State-Based Gate (배경/구현/효과/logcat 키워드) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 10:26:00 +09:00
parent 31e9b8acbb
commit 4252464ef6
3 changed files with 296 additions and 32 deletions
@@ -1,7 +1,8 @@
 # VesiScan-Basic User Guide

-## App Version: VBTAND0101
-## Last Updated: 2026-05-11
+## App Version: 1.0.0-design (versionCode 24)
+## Last Updated: 2026-05-26
+## Recommended Firmware: **VBTFW0116** (pending slot 1→8 확장, ADC drop 안정)

 ---

@@ -11,10 +12,13 @@
 1. Install the app and open it
 2. Complete the onboarding screens
 3. Register your information (name, age, height, weight)
-4. Set a 4-digit PIN
+4. ~~Set a 4-digit PIN~~ — **현재 빌드는 PIN 데모 자동통과**: PinView 진입 시 즉시 verified 처리 (시연용)
 5. You will arrive at the **Home** screen

+> ⚠️ **DEMO 빌드 표시**: 현재 빌드는 PIN 잠금이 우회됩니다 ([PinView.kt:23-29](app/src/main/java/com/example/medilightv2android/ui/views/pin/PinView.kt#L23-L29)). 원본 UI는 `if (false) { ... }` 안에 보존되어 있어 배포 시 1줄 제거로 복구 가능. 배포 전 정리 체크리스트 참조.
+
 ### Home Screen
+- 큰 **Bladdy 캐릭터** (3× 확대, 최대 660dp, 작은 화면에선 90% 캡)
 - Tap **Start** to begin
 - The app version is displayed below "Smart Bladder Monitoring"
 - To enable Developer Mode: tap the Bladdy character **3 times quickly** (within 1.5 seconds)
@@ -32,9 +36,25 @@
   - The app waits up to 30 seconds for pairing to complete
 5. Once paired, you will move to the Personalization screen

-### Personalization
- Set your **Max Volume** (200-800 mL, default: 500 mL)
- Tap **Continue** to proceed to Sensor Alignment
+### Personalization (전면 리디자인 — 평행 2-카드)
+
+상하 정렬된 두 카드로 구성:
+
+**Card 1: Maximum Bladder Capacity**
+- 큰 숫자 표시 (예: `500` 64sp ExtraBold + `mL` 24sp)
+- 56dp 원형 솔리드 **StepperButton −/+** 좌우 배치
+- 슬라이더 (200~800 mL, 50 단위, `roundToInt()` 절삭 fix 적용)
+- 카드 헤더 34sp ExtraBold
+
+**Card 2: Catheter Threshold**
+- 3분할 텍스트: `Level` 24sp + `7` 64sp + `/10` 24sp (Card 1과 픽셀 매칭)
+- 56dp StepperButton −/+
+- 슬라이더 Level 1~10 (`roundToInt` 적용)
+- 카드 헤더 34sp ExtraBold
+
+두 카드는 64dp 간격으로 수직 중앙 정렬. Bladdy 히어로는 상단에 동적 사이징.
+
+Tap **Continue** to proceed to Sensor Alignment.

 ---

@@ -42,6 +62,13 @@

 This step ensures the sensor is positioned correctly over your bladder for accurate measurement.

+### 화면 디자인 (리디자인 적용)
+- **큰 타이틀 "Sensor Alignment"** 38sp ExtraBold 검정 (Maximum Bladder Capacity 톤 통일)
+- **3-stop vertical gradient 배경** (MlTeal 14% / 흰 / MlPrimary 10%) — GREEN 진입 시 단색 톤으로 덮임
+- **Hint 텍스트에서 "pubic bone" 인라인 빨강 ExtraBold 강조**
+- Canvas 방향 화살표 제거 — hint 텍스트만으로 방향 안내 (이전 4종 화살표 + 치골 아치 라인+halo+endpoint 모두 제거)
+- 토르소 실루엣 상단 16% UP shift (chestY 0.06 → 0.09)
+
 ### Before Starting
 - Place VesiScan above the pubic bone
 - Apply ultrasound gel between the sensor and your skin
@@ -102,23 +129,29 @@ After alignment, you will see the main measurement screen with a donut chart.
 ### Screen Layout

 ```
-  [Placement]  [Battery]  [Catheters]  [Settings]
+  [Home] [Placement]  [Battery]  [Catheters]  [Settings]    ← Home 아이콘 추가됨
  
            Enjoy your day!
            
         ┌─────────────────┐
-         │    Donut Chart   │
+         │    Donut Chart   │   ← 너비 × 0.85 적응형 (이전 0.75 + 360dp cap 제거)
         │                  │
-         │     [Bladdy]     │
-         │    325 mL        │
+         │     [Bladdy]     │   ← 0.483 비율 (이전 0.55에서 -15% 후 +15%)
+         │    325 mL        │   ← 72sp ExtraBold (이전 24sp의 3배), letterSpacing -1
         └─────────────────┘
         
   Current Measurement    |     65%
        280 mL            |   325/500 mL
        
-   [Void/Catheterization] [Auto Scan] [Single Scan]
+   [Voiding/             [Auto Scan] [Single Scan]
+    Catheterization]
 ```

+### Top Bar
+- **Home 아이콘** (좌측 추가) — `appState.goHome()` 호출, 즉시 홈으로
+- **Placement 아이콘** (Home 옆) — `enterPlacementFromMonitoring()` 호출 → Back 시 Monitoring으로 복귀
+- 배터리 / 카테터 카운트 / Settings 톱니바퀴는 기존과 동일
+
 ### Understanding the Display

 | Element | Description |
@@ -135,12 +168,15 @@ After alignment, you will see the main measurement screen with a donut chart.
 ## 5. Auto Scan

 1. Tap the **Auto Scan** button (orange)
-2. The device will measure continuously (minimum 800ms interval)
+2. The device will measure continuously (**minimum 600ms interval**, 이전 1500ms에서 단축)
 3. For the first 5 measurements, the display will show **"—"** (collecting data)
 4. After 5+ measurements, the **trimmed mean** value will be displayed (10-sample window, top/bottom excluded)
 5. The donut chart will update every 5 seconds
 6. Tap **Stop Scan** (red) to end Auto measurement

+> **속도 향상 배경 (2026-05-26)**: FW VBTFW0116 + MTU 247 + CONNECTION_PRIORITY_HIGH 조합으로
+> 한 측정 사이클이 ~330ms로 단축. 이전(~1.2초) 대비 **4배 향상**. 자세한 내용은 Pipeline Summary §5.1 참조.
+
 ### Auto Measurement Failure
 - If 2+ channels fail **5 times in a row** (sensor shifted or lost contact):
  - A dialog will appear: **"Position lost. Restart from alignment"**
@@ -161,13 +197,14 @@ After alignment, you will see the main measurement screen with a donut chart.

 ---

-## 7. Void / Catheterization
+## 7. Voiding / Catheterization (텍스트 변경)

-1. Tap the **Void / Catheterization** button
+1. Tap the **Voiding / Catheterization** button (이전 "Void/Catheterization" → **"Voiding/"** 로 첫 줄 갱신)
 2. The current measurement is recorded to the voiding diary
-3. The catheter count decreases by 1
-4. The bladder level resets to 0
-5. A toast message **"Recorded"** will appear
+3. **자동: Auto Scan 진행 중이면 stop** + 측정 상태 정규화 (`displayMaxVolumeMl`/window/timer 모두 0)
+4. The catheter count decreases by 1
+5. The bladder level resets to 0
+6. **큰 "Recorded" 다이얼로그** (48sp ExtraBold 흰색, MlPrimary 0.95 alpha 배경, 1.5초 자동 닫힘) — 이전 Toast 대체

 ### Managing Catheters
 - The catheter count is shown at the top of the screen (hospital icon + number)
@@ -183,8 +220,8 @@ Tap the **gear icon** at the top right to open settings.
 ### General Settings (always visible)
 | Setting | Description | Default |
 |---------|-------------|---------|
-| Max Volume | Maximum bladder volume for fill calculation | 500 mL |
-| Catheter Threshold | Alert level for catheterization | Level 7 |
+| Bladder Capacity | Maximum bladder volume for fill calculation | 500 mL |
+| Catheter Threshold | Alert level for catheterization | Level 8 |

 ### Developer Settings (Developer Mode only)
 | Setting | Description |
@@ -196,17 +233,58 @@ Tap the **gear icon** at the top right to open settings.
 | SG Filter | Savitzky-Golay noise filter on/off |
 | Post Max | Maximum sample index for wall detection (filters floor reflections) |

+### 폰/태블릿 자동 폰트 분기 (2026-05-26)
+
+설정 패널 라벨 크기는 화면 너비에 따라 자동 조절:
+```kotlin
+val fontScale = (screenWidth / 360f).coerceIn(1.0f, 1.8f)
+val isTablet = screenWidth >= 600
+labelSize    = (14 * fontScale).sp       // 폰 14sp, 태블릿 ~25sp
+rowSpacing   = (6  * fontScale).dp       // 폰 6dp, 태블릿 ~10dp
+dividerPadding = if (isTablet) 12.dp else 0.dp
+```
+
+| 기기 | screenWidth | labelSize |
+|---|---|---|
+| Galaxy S20 (폰) | 360dp | 14sp |
+| Pixel 7 (폰) | 412dp | 16sp |
+| 갤탭 S6 Lite | 600dp | 23sp |
+| 갤탭 S8 / iPad Pro | 800dp+ | 25sp (cap) |
+
+이전 시도(28sp 하드코딩)에서 폰 화면이 곱창나던 문제를 해결.
+
+### Dev Mode 추가 기능
+
+- **HomeView Bladdy 3탭** → Developer Mode 토글
+- **DeviceScanView "No devices found" 화면 + dev 모드** → "Enter Measurement Mode (Dev)" 버튼 (BLE 없이 측정 화면 진입)
+- **PiezoMonitoring Status 배지 dev 탭** → 60~maxVol-50 범위 더미 측정값 랜덤 주입 (BLE 없이 동작 검증용)
+- **dev 모드 한정 ChannelPanel / BleDebugPanel** 표시 (Developer Tools 버튼 토글)
+
 ---

 ## 9. Navigation

 | Action | Result |
 |--------|--------|
-| **Placement button** (top left) | Go to Sensor Alignment |
+| **Home button** (top left) | Go to Home screen (`appState.goHome()`) |
+| **Placement button** (Home 옆) | Re-enter Sensor Alignment (`enterPlacementFromMonitoring()`) |
 | **Settings button** (top right) | Open/close settings panel |
 | **Back button** (Android) | Go to previous screen |
 | **Back button on Home** | "Exit App?" confirmation dialog |

+### Placement 진입 경로 분기 (2026-05-12 신규)
+
+`placementFromMonitoring` 플래그로 Back 동작이 자동 분기:
+
+- **Personalization → Placement → Monitoring** (정방향): Placement에서 Back = Personalization으로 복귀
+- **Monitoring → Placement** (재정렬): Placement에서 Back = Monitoring으로 복귀
+
+코드: [AppState.kt](app/src/main/java/com/example/medilightv2android/AppState.kt) 의 `enterPlacementFromMonitoring()` / `backFromPlacementGuide()`.
+
+### startFromHome() 라우팅 fix
+
+페어링 완료 상태에서 Home → Start 시 Personalization부터 시작 (이전: Monitoring 직행 버그).
+
 ---

 ## 10. Troubleshooting