dw.jang
1cf45df80c
- USER_GUIDE.md
* versionCode 24 → 26, App 1.0.0-design → 1.2.0-demo
* Last Updated 2026-05-26 → 2026-07-13
* Recommended FW VBTFW0116 → VBTFW0120+ (mim FIFO 필수)
* PinView.kt / AppState.kt link path com.example → com.medithings.vesiscan
- docs/BLE_PROTOCOL_REFERENCE.md
* 작성일 2026-06-05 → 2026-07-13, 검증 FW VBTFW0116 → VBTFW0120+
* package path 52건 com.example → com.medithings.vesiscan (모든 코드 링크 복구)
- docs/ALGORITHM_COMPARISON.md
* 3-Stage 를 "V1 (일반 진입)" 로 명시
* "V2 6-Stage Guide (AlignGuide4Stage)" 신규 섹션: phase 표 + CH3 flicker
3-Layer (majority / relaxed / soft-hint) + Python replay 검증 요약
* 헤더에 2026-07-13 update 표시
- docs/FLAVOR_DEMO_STABLE.md
* example source path 표기 com/example/... → com/medithings/vesiscan/...
- VesiScan_Android_Pipeline_Summary.md
* 남아있던 com/example/ 경로 1건 정리
기능 변화 없음. 문서-코드 일관성 확보 (기존 링크가 리네임 이후 broken 상태였음).
216 lines
8.0 KiB
Markdown
216 lines
8.0 KiB
Markdown
# Flavor 운영 정책 — demo (동결 안정판) vs dev (개발 진행)
|
|
|
|
방광 모형 테스트가 100% 통과하는 시점을 **demo flavor**로 동결하고, 모든 신규 작업은 **dev flavor**에서만 진행하기 위한 가이드.
|
|
|
|
---
|
|
|
|
## 1. 두 flavor의 정체성
|
|
|
|
| 항목 | demo | dev |
|
|
|---|---|---|
|
|
| 목적 | 시연/검증 — 결과 재현성 보장 | 개발 진행 — 모든 신규 기능/실험 |
|
|
| applicationId | `com.medithings.vesiscan.demo` | `com.medithings.vesiscan` |
|
|
| 표시명 | VesiScan Demo | VesiScan Dev |
|
|
| versionName suffix | `-demo` | (없음) |
|
|
| BuildConfig.IS_DEMO | `true` | `false` |
|
|
| BuildConfig.FLAVOR_LABEL | `"demo"` | `"dev"` |
|
|
| 동시 설치 | 가능 (applicationId 다름) | 가능 |
|
|
|
|
→ 한 단말에 두 빌드를 동시에 설치해서 같은 측정을 양쪽에서 돌려보고 결과 비교 가능.
|
|
|
|
---
|
|
|
|
## 2. 빌드 명령
|
|
|
|
```bash
|
|
# demo flavor
|
|
./gradlew assembleDemoDebug # debug APK
|
|
./gradlew assembleDemoRelease # release APK
|
|
|
|
# dev flavor
|
|
./gradlew assembleDevDebug # debug APK (일상 개발)
|
|
./gradlew assembleDevRelease
|
|
|
|
# 두 flavor 모두 빌드
|
|
./gradlew assembleDebug
|
|
```
|
|
|
|
Android Studio에서는 **Build Variants** 패널에서 `demoDebug` / `devDebug` / ... 중 선택.
|
|
|
|
---
|
|
|
|
## 3. 동결 메커니즘 — 두 가지 레벨
|
|
|
|
### Level 1: BuildConfig flag 분기 (가장 단순)
|
|
|
|
코드 안에서 분기:
|
|
```kotlin
|
|
if (BuildConfig.IS_DEMO) {
|
|
// demo 전용 동작 (예: 디버그 panel 숨김, 특정 알고리즘 강제)
|
|
} else {
|
|
// dev 전용
|
|
}
|
|
```
|
|
|
|
장점: 같은 파일에서 처리 가능.
|
|
단점: 시간이 지나면서 main 코드가 변경되면 demo 동작도 같이 영향받음. **진정한 동결은 안 됨.**
|
|
|
|
### Level 2: Source set 격리 (★ 진짜 동결)
|
|
|
|
`src/demo/java/` 또는 `src/demo/res/` 에 동결 시점의 클래스/리소스를 복사하면, **dev 작업 중 main이 바뀌어도 demo flavor 빌드는 이 격리본을 사용**합니다.
|
|
|
|
**Gradle 컴파일 우선순위:**
|
|
```
|
|
demo flavor 빌드 → src/main/* + src/demo/* (같은 클래스명이면 src/demo/가 우선)
|
|
dev flavor 빌드 → src/main/* + src/dev/*
|
|
```
|
|
|
|
**예시:** V4.1 wall detection 알고리즘을 2026-06-08 시점에 동결하려면:
|
|
```
|
|
src/main/java/com/medithings/vesiscan/.../walldetect/V41Detector.kt ← 계속 변경됨 (dev에서 사용)
|
|
src/demo/java/com/medithings/vesiscan/.../walldetect/V41Detector.kt ← 2026-06-08 시점 복사본 (demo에서 사용)
|
|
```
|
|
|
|
main의 V41Detector를 리팩토링/실험해도 demo 빌드는 항상 격리본을 컴파일.
|
|
|
|
⚠️ **주의:**
|
|
- 격리한 클래스의 시그니처가 main의 의존 코드와 호환되어야 함 (메서드 이름/파라미터 동일하게 유지)
|
|
- main에서 V41Detector 호출부의 시그니처가 바뀌면 demo flavor 빌드 깨짐 — 그땐 src/demo/도 같이 업데이트하거나, 인터페이스를 두고 그 구현만 분리
|
|
|
|
---
|
|
|
|
## 4. 권장 동결 운영 절차
|
|
|
|
### 4.1 새 안정판 동결 시
|
|
|
|
방광 모형 테스트가 100% 통과하는 시점을 확인하면:
|
|
|
|
```bash
|
|
# 1) 현재 상태에 tag 부여 (snapshot 보존)
|
|
git tag -a demo-stable-v1.0 -m "Demo stable: bladder phantom 100% pass — 2026-06-08"
|
|
git push origin demo-stable-v1.0
|
|
|
|
# 2) 동결할 핵심 클래스/리소스를 src/demo/로 복사
|
|
# 예: V4.1, PiezoSettings 기본값, GreenZoneConstants 등
|
|
cp app/src/main/java/.../walldetect/V41Detector.kt \
|
|
app/src/demo/java/.../walldetect/V41Detector.kt
|
|
|
|
# 3) demo flavor가 격리본을 잘 쓰는지 빌드 + 시연용 폰에 설치해 검증
|
|
./gradlew installDemoDebug
|
|
|
|
# 4) commit
|
|
git add app/src/demo/ && git commit -m "Demo flavor: freeze V4.1/PiezoSettings (v1.0)"
|
|
```
|
|
|
|
### 4.2 일상 개발 (dev)
|
|
|
|
- `src/main/` 만 변경 — `src/demo/`는 건드리지 않음
|
|
- `assembleDevDebug` 로만 작업
|
|
- demo 격리본의 시그니처를 깨뜨리는 API 변경은 피하거나, demo도 같이 업데이트
|
|
|
|
### 4.3 다음 안정판 갱신
|
|
|
|
새로운 안정판이 검증되면:
|
|
```bash
|
|
# 이전 격리본 백업 (옵션 — git history에 남아있음)
|
|
mv app/src/demo/java/.../V41Detector.kt /tmp/V41Detector.v1.0.kt
|
|
|
|
# 최신 main 코드를 다시 src/demo/로 복사
|
|
cp app/src/main/java/.../V41Detector.kt app/src/demo/java/.../V41Detector.kt
|
|
|
|
# 새 tag
|
|
git tag -a demo-stable-v1.1 -m "Demo stable v1.1: ..."
|
|
|
|
# commit
|
|
git add app/src/demo/ && git commit -m "Demo flavor: refresh freeze to v1.1"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 어떤 코드를 동결 후보로?
|
|
|
|
방광 모형 테스트 결과에 직접 영향을 주는 것들:
|
|
|
|
| 카테고리 | 후보 | 위치 |
|
|
|---|---|---|
|
|
| Wall detection | `V41Detector`, `PiezoEchoAnalyzer*` | `walldetect/`, `managers/PiezoEchoAnalyzer*.kt` |
|
|
| 측정 파라미터 | `PiezoSettings` 기본값, `GreenZoneConstants`, `PiezoHW` preset | `models/`, `managers/` |
|
|
| BLE 파싱 | `PiezoPacketCollector`, `ImuPacketCollector` | `ble/` |
|
|
| Volume 계산 | `PiezoConstants.volumeMl()` 식 | `managers/PiezoEchoAnalyzer.kt` |
|
|
|
|
⚠️ **BLE 통신 layer (BleManager, CRC16)는 펌웨어와 직결되므로 보통 같이 가야 함** — 동결하면 펌웨어 업데이트 대응 불가.
|
|
|
|
⚠️ **UI/저장/labdb는 동결할 필요 거의 없음** — 결과값 자체에는 영향 안 줌.
|
|
|
|
→ 처음엔 **알고리즘 + 측정 파라미터**만 동결, 나머지는 main 공유 권장.
|
|
|
|
---
|
|
|
|
## 6. BuildConfig 활용 예시
|
|
|
|
런타임 분기가 필요한 경우 (격리할 만큼 크지 않은 케이스):
|
|
|
|
```kotlin
|
|
// 예: dev에만 Clinical 메뉴 노출
|
|
if (com.medithings.vesiscan.BuildConfig.IS_DEMO.not()) {
|
|
Button(onClick = { goClinicalHome() }) { Text("Clinical R&D") }
|
|
}
|
|
|
|
// 예: demo에서는 항상 fixed parameter
|
|
val maxVolume = if (com.medithings.vesiscan.BuildConfig.IS_DEMO) {
|
|
500 // 동결 기본값
|
|
} else {
|
|
appState.piezoSettings.maxVolume // 사용자 조정 허용
|
|
}
|
|
|
|
// UI에서 flavor 표시 (디버그용)
|
|
Text("v${BuildConfig.VERSION_NAME} (${BuildConfig.FLAVOR_LABEL})",
|
|
fontSize = 10.sp, color = MlSecondaryText)
|
|
```
|
|
|
|
---
|
|
|
|
## 7. CI / 배포 시 주의
|
|
|
|
- **demo flavor APK는 출시/시연 전용** — Play Store 등 외부 배포는 dev flavor 사용
|
|
- demo flavor의 applicationId가 `.demo`로 끝나므로 ANR/crash 리포트도 자동 구분됨
|
|
- demo는 안정성 보장이 핵심 — 새 라이브러리/SDK 업데이트도 보수적으로
|
|
|
|
---
|
|
|
|
## 8. 트러블슈팅
|
|
|
|
### Q. demo flavor 빌드 시 main의 변경사항이 자꾸 반영됨
|
|
A. src/demo/ 에 격리본을 복사하지 않았기 때문. Level 2 동결을 적용해야 함. BuildConfig.IS_DEMO 분기만으로는 진짜 동결 안 됨.
|
|
|
|
### Q. 같은 클래스를 src/main/과 src/demo/에 둘 다 두면 어떻게 됨?
|
|
A. demo flavor 빌드에서는 src/demo/ 가 우선. dev flavor 빌드에서는 src/main/ 만 사용 (src/demo는 무시).
|
|
|
|
### Q. src/demo/와 src/dev/ 둘 다 같은 클래스가 있으면?
|
|
A. 각 flavor 빌드는 자기 flavor source set만 봄. demo 빌드 = main + demo, dev 빌드 = main + dev. 충돌 안 남.
|
|
|
|
### Q. Test (src/test/, src/androidTest/) 는 flavor 별로 분리되나?
|
|
A. 가능. `src/testDemo/`, `src/testDev/`로 분리. 다만 현재 프로젝트엔 테스트가 거의 없어 신경 안 써도 됨.
|
|
|
|
### Q. Gradle sync 후 Build Variants에 demo/dev가 안 보임
|
|
A. Android Studio 좌측 하단 **Build Variants** 패널을 켜고 Gradle sync 재실행. 처음 한 번은 sync에 30초~1분 걸림.
|
|
|
|
---
|
|
|
|
## 9. 첫 동결 시점 권장 절차 (지금 바로 할 일)
|
|
|
|
1. 현재 dev 빌드를 방광 모형으로 검증 — 결과값이 만족스러우면 진행
|
|
2. `git tag -a demo-stable-v1.0 -m "Demo baseline 2026-06-08"` + push
|
|
3. 검증된 알고리즘 클래스를 `src/demo/java/...` 로 복사
|
|
4. `./gradlew installDemoDebug` 로 시연 폰에 설치
|
|
5. 같은 모형으로 demo 빌드 한 번 더 측정 — 동일 결과 확인
|
|
6. 이후 dev에서 자유롭게 작업. demo는 건드리지 않음.
|
|
|
|
---
|
|
|
|
**관련 파일:**
|
|
- `app/build.gradle.kts` — productFlavors 정의
|
|
- `app/src/demo/`, `app/src/dev/` — flavor 전용 source set
|
|
- `app/src/demo/res/values/strings.xml` — app_name "VesiScan Demo"
|
|
- `app/src/dev/res/values/strings.xml` — app_name "VesiScan Dev"
|