From 2853127ff595a96ac99e5601e98136196079eefd Mon Sep 17 00:00:00 2001 From: jjangddu Date: Wed, 9 Sep 2026 12:26:09 +0900 Subject: [PATCH] =?UTF-8?q?docs(clinical):=201=ED=9A=8C=20=EC=B8=A1?= =?UTF-8?q?=EC=A0=95=EC=9D=80=20=EB=A9=94=EC=9D=B8=EC=9D=98=20[=EB=8B=A8?= =?UTF-8?q?=EC=9D=BC=20=EC=B8=A1=EC=A0=95]=EA=B3=BC=20=EB=8B=A4=EB=A5=B4?= =?UTF-8?q?=EB=8B=A4=EA=B3=A0=20=EB=B6=84=EB=AA=85=ED=9E=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 앞 커밋에서 "메인 화면과 같은 방식"이라고 썼는데 절반만 맞았다. 메인의 [단일 측정]은 1 cycle 이 아니라 **5회를 모아 절사평균**한다 (PiezoMonitoringView: targetCount=5, maxAttempts=8, 3개 이상이면 값). 임상 화면은 1회만 잰다 — 의도한 차이지만, 주석과 화면 문구가 "같다"고 말하고 있었다. 연속 / 자동 cycle 마다 BV → 최근 10개 절사평균, 5개부터 표시 같음 1회 / 단일 메인 5회 절사평균 vs 여기 1 cycle 그대로 다름 1회로 두는 이유는 검증 항목 ③(위치 민감도)이다. 상·하·좌·우 1~2cm 씩 옮기며 값을 기록하는 작업인데 메인 방식은 한 번에 10초 가까이 걸려 그 시간이 그대로 쌓인다. **틀린 설명이 코드보다 위험하다.** 숫자가 다른 건 이유를 알면 해석할 수 있지만, "같은 방식"이라고 읽은 사람은 임상 1회 값과 메인 단일 값을 나란히 놓고 기기 차이로 결론낸다. 그래서 주석에 비교표와 "직접 비교하면 안 된다"를 넣고, 기존 초음파 측정기 대조(항목 ①) 에는 **연속 측정**을 쓰라고 못박았다. 버튼도 [단일 측정]→[1회 측정], [자동 측정]→[연속 측정]. 메인과 같은 이름이면 같은 동작으로 읽힌다. Co-Authored-By: Claude Opus 5 --- .../ui/views/clinical/BvMeasureSection.kt | 49 ++++++++++--------- 1 file changed, 27 insertions(+), 22 deletions(-) diff --git a/app/src/main/java/com/medithings/vesiscan/ui/views/clinical/BvMeasureSection.kt b/app/src/main/java/com/medithings/vesiscan/ui/views/clinical/BvMeasureSection.kt index f54e0bd..fb39d55 100644 --- a/app/src/main/java/com/medithings/vesiscan/ui/views/clinical/BvMeasureSection.kt +++ b/app/src/main/java/com/medithings/vesiscan/ui/views/clinical/BvMeasureSection.kt @@ -27,26 +27,30 @@ import kotlinx.coroutines.delay import kotlinx.coroutines.withTimeoutOrNull /** - * 한 번 재는 것(단일/Spot)과 계속 재는 것(자동/Continuous). + * 1회 측정(Spot)과 연속 측정(Continuous). * - * ## 메인 화면의 [단일 측정]·[자동 측정]과 **같은 방식**이다 - * 두 화면의 숫자가 비교 가능해야 한다. 방식이 다르면 같은 프로브·같은 자리에서도 값이 - * 갈려서, "임상 화면은 180 인데 메인은 195"가 기기 차이인지 계산 차이인지 알 수 없다. - * 검증의 첫 항목이 "기존 초음파 측정기와 비교"라 이 혼동은 치명적이다. - * - * 그래서 메인 화면([com.medithings.vesiscan.ui.views.monitoring.PiezoMonitoringView])의 - * 규약을 그대로 옮긴다: + * ## 메인 화면과 같은 것, 다른 것 + * 메인 화면([com.medithings.vesiscan.ui.views.monitoring.PiezoMonitoringView])과 나란히 + * 두고 비교한다: * * | | 메인 | 여기 | * |---|---|---| - * | 단일 | 1 cycle → BV 그대로 | 같음 | - * | 자동 | cycle 마다 BV → 최근 [WINDOW_SIZE]개 **절사평균** | 같음 | - * | 표시 시작 | 창에 [WINDOW_MIN]개 이상 쌓인 뒤 | 같음 | - * | 주기 | 완료 대기 + 남은 간격만 | 같음 | + * | 연속 / 자동 | cycle 마다 BV → 최근 10개 **절사평균**, 5개 이상부터 표시 | **같음** | + * | 1회 / 단일 | 5회 목표(최대 8회 시도) → 절사평균, 3개 이상이면 값 | **1 cycle → BV 그대로** | * - * **평균을 BV 뒤에 낸다**는 점이 핵심이다. 신호를 먼저 평균하면(mean-scan) 값이 더 - * 안정적이지만 메인 화면과 다른 수가 되고, 정렬 단계의 20-cycle mean-scan 과도 또 - * 다른 세 번째 방식이 된다. 여기서는 **비교 가능성이 안정성보다 우선**이라 이쪽을 택했다. + * **1회 측정만 일부러 다르다.** 메인의 [단일 측정]은 5회를 모아 절사평균하느라 한 번에 + * 10초 가까이 걸린다. 검증 항목 ③(위치 민감도)은 상·하·좌·우로 1~2cm 씩 옮기며 값을 + * 기록하는 작업이라 그 시간이 그대로 쌓인다. 여기서는 **한 자리에서 즉시 한 값**을 + * 보는 것이 목적이고, 안정된 대표값이 필요하면 연속 측정을 쓰면 된다. + * + * 그래서 **1회 측정 값을 메인의 [단일 측정] 값과 직접 비교하면 안 된다.** 저쪽은 + * 5회 절사평균이라 더 안정적이다. 기존 초음파 측정기와 대조할 때(검증 항목 ①)는 + * **연속 측정의 절사평균**을 쓰는 것이 맞다 — 그쪽이 메인과 같은 규약이다. + * + * ## 평균은 BV 뒤에 낸다 + * 신호를 먼저 평균하면(mean-scan) 값이 더 안정적이지만 메인 화면과 다른 수가 되고, + * 정렬 단계의 20-cycle mean-scan 과도 또 다른 세 번째 방식이 된다. 연속 측정이 + * 메인과 비교 가능해야 하므로 부피끼리 평균한다. * * ## 절사평균인 이유 * 최대·최소 하나씩 버리고 평균낸다. cycle 단위 BV 는 벽 오검출로 가끔 크게 튀는데, @@ -59,13 +63,13 @@ import kotlinx.coroutines.withTimeoutOrNull private val BV_FREQ = ProbeFrequency.F_2_3 private val BV_CYCLE = ProbeCycle.C3 -/** 자동 모드 표시 창 크기. 메인 화면 `autoWindowSize` 와 같은 값. */ +/** 연속 모드 표시 창 크기. 메인 화면 `autoWindowSize` 와 같은 값. */ private const val WINDOW_SIZE = 10 /** 이만큼 쌓여야 절사평균을 띄운다. 메인 화면과 같다. */ private const val WINDOW_MIN = 5 -/** 자동 모드 목표 주기. 메인 화면 `piezoSettings.autoScanIntervalMs` 기본값과 같다. */ +/** 연속 모드 목표 주기. 메인 화면 `piezoSettings.autoScanIntervalMs` 기본값과 같다. */ private const val INTERVAL_MS = 500L private const val MEASURE_TIMEOUT_MS = 3_000L @@ -132,7 +136,7 @@ fun BvMeasureSection( bleManager.sendMtb() val got = withTimeoutOrNull(MEASURE_TIMEOUT_MS) { inbox.receive() } if (got == null) { - // 한 회 놓쳤다고 멈추지 않는다 — 자동 모드는 계속 돌아야 한다. + // 한 회 놓쳤다고 멈추지 않는다 — 연속 모드는 계속 돌아야 한다. error = "응답 시간 초과 — 다시 시도합니다." } else { error = null @@ -172,7 +176,8 @@ fun BvMeasureSection( fontSize = 11.sp, color = MlSecondaryText) } Text( - "메인 화면의 [단일 측정] · [자동 측정]과 같은 방식입니다.", + "연속 측정은 메인 화면의 [자동 측정]과 같은 방식(10회 절사평균)입니다. " + + "1회 측정은 말 그대로 한 번만 잽니다 — 메인의 [단일 측정](5회 절사평균)과 다릅니다.", fontSize = 11.sp, color = MlSecondaryText, ) @@ -204,7 +209,7 @@ fun BvMeasureSection( enabled = isConnected && mode != Mode.CONTINUOUS, modifier = Modifier.weight(1f).height(46.dp), shape = RoundedCornerShape(12.dp), - ) { Text(if (mode == Mode.SPOT) "측정 중…" else "단일 측정", fontWeight = FontWeight.Bold) } + ) { Text(if (mode == Mode.SPOT) "측정 중…" else "1회 측정", fontWeight = FontWeight.Bold) } Spacer(Modifier.width(8.dp)) Button( onClick = { mode = if (mode == Mode.CONTINUOUS) null else Mode.CONTINUOUS }, @@ -214,7 +219,7 @@ fun BvMeasureSection( colors = ButtonDefaults.buttonColors( containerColor = if (mode == Mode.CONTINUOUS) MlCritical else MlSuccess), ) { - Text(if (mode == Mode.CONTINUOUS) "자동 측정 중지" else "자동 측정", + Text(if (mode == Mode.CONTINUOUS) "연속 측정 중지" else "연속 측정", color = Color.White, fontWeight = FontWeight.Bold) } } @@ -224,7 +229,7 @@ fun BvMeasureSection( Text(it, fontSize = 12.sp, color = MlCritical) } - // ── 자동 모드 대표값 ── + // ── 연속 모드 대표값 ── // 메인 화면과 같다: 최근 10개의 **절사평균**(최대·최소 하나씩 버림), 5개 이상 쌓여야 표시. if (mode == Mode.CONTINUOUS || window.isNotEmpty()) { Spacer(Modifier.height(10.dp))