Fix
- ChatScreen body 를 SafeArea(top: false) 로 감쌈. Android edge-to-edge
모드에서 시스템 nav bar 가 입력창을 덮던 문제 해결.
Dev (#342)
- userTurn catch 블록이 e.toString() + stack trace 를 error 상태에 저장.
- 빨간 에러 컨테이너를 SingleChildScrollView + SelectableText (monospace)
+ 최대 화면 1/3 높이 제약. 스크롤 + 복사 가능. release 빌드에서도
full stack 노출 (#342 종료 후 follow-up 으로 좁힘).
테스트: chat_session_controller_test 8/8 통과.
APK: app-release.apk 301.0MB SHA 02a5d1c8.
Refs #342
SettingsScreen pop 후 ChatScreen state 가 여전히 Failed(fileMissing)
인 회로 — 사용자가 다운로드를 끝내고 돌아와도 ChatScreen 전체를
pop & re-push 해야 회복되는 UX gap.
Navigator.push().then((_) => retry()) 로 SettingsScreen 닫힐 때
자동 retry. quickCheck 다시 → ready 면 load → Ready 회복.
다운로드 안 했으면 다시 Failed 로 떨어져 같은 배너 노출 (일관).
`context.mounted` 가드는 ChatScreen 이 dispose 된 race 대비.
Refs #311
UX-REVIEW.md §마이크로카피 사전에서 fileMissing 케이스에 [설정으로
가기] 를 명시했으나 Developer 구현은 모든 kind 가 [다시 시도] 였음.
fileMissing 에서 retry 해도 파일이 없어 같은 결과 → 사용자 막힘.
- ChatWarmupFailureKind.fileMissing → SettingsScreen push (다운로드
재시도 경로 노출)
- ChatWarmupFailureKind.runtime → 기존 retry() 유지 (일시적 회복 가능)
여전히 메시지 본문은 상태 기술만 (AC12), 행동은 버튼이 담당 (UX R5).
Refs #311
ChatScreen 마운트 시 백그라운드 native init 으로 첫 send 시점에 native
load 지연을 안 보이게 한다. 12개 AC + UX-Reviewer 의 6개 권고 모두 코드
반영.
핵심 변경:
- `chat_warmup_provider.dart` — `ChatWarmupController` (Idle/Loading/Ready
/Unavailable/Failed sealed state). fast path (`llm.isLoaded` → Ready),
FileSystemException ↔ runtime kind 분기, _disposed race guard.
- `model_lifecycle.dart` — `quickCheck()`: 2.4GB SHA-256 hashing 없이
meta_kv + 파일 존재만 보고 ready 추정 (R4 UX 권고).
- `gemma_llm_service.dart` + `llm_service.dart` — `_loadingFuture` 동시
호출 가드. 두 caller 가 동시에 load() 해도 native init 은 1 회만.
- `chat_screen.dart` — initState postFrameCallback 에서 warmup.start().
warmup 상태에 따라 hintText / spinner / 실패 banner 분기.
AC coverage (12개):
- AC1~AC8: ChatWarmupController unit (chat_warmup_test.dart 8 tests).
- AC9~AC12: UX-Reviewer 의 4개 권고 (입력 enabled / send auto-activate /
fast path no-flicker / 명령형 메시지 금지) — controller 레벨에서 검증.
테스트: 167 passed (1 pre-existing skip). `flutter analyze` clean.
Refs #311
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
코드 결함 1건 + 문서 정확성 nit 3건. 사용자 동작에 영향 있는 건 (1)
번만, 나머지는 문서 정정.
(1) _LazyLlmService._delegate sticky cache 수정 (main.dart)
- 기존: 첫 호출 시점에 잡힌 delegate (Mock vs Gemma) 가 앱 재시작까지
유지 — 옵트인 OFF 상태에서 첫 suggestFrame 호출 → Mock 잡힘 → 사용자
옵트인 ON + 다운로드 완료 후에도 같은 Mock 만 반환 (사용자는 AI 가
켜진 줄 알고 mock 응답 받음).
- 수정: 매 _resolve() 호출마다 checkAvailability 재평가. 캐시는
(Gemma↔Mock 종류) + (Gemma 의 modelPath) 모두 일치할 때만 재사용 →
state 변화 시 자동 교체. flutter_gemma installModel 자체가
idempotent 라 반복 resolve 비용 무시 가능.
(2) reference doc nit 3건 — 04-QA round 2 가 08-Documenter 로 인계한
nit 를 Reviewer 가 직접 정정:
- L184: "device_info_plus 로 systemFeatures / totalMem 조회" → 실
구현은 MethodChannel `life_helper/device_caps`. device_info_plus
는 deps 에 있지만 4GB 임계 측정엔 미사용 (isLowRamDevice 는 ~1GB).
- L186: F1 후속 이슈 번호 "#222 등" → "#219 별도 이슈".
- L191: follow-up 매핑 — 임의 "#219 ProGuard rules 정제" 항목 제거.
Planner OOS 기준 #219=F1 unload, #220=F2 purge, #221=AC10 corpus,
#222=production keystore 로 정정.
검증: flutter analyze 무이슈, flutter test 88/88 통과.
Refs #218
Round 2 QA PASS 후 user-facing 문구 3건 정리.
1) AC-6 RAM 게이트 안내: "이 단말의 RAM 이 부족합니다 (필요: 4GB 이상)"
→ "이 단말에서는 AI 도움을 사용할 수 없어요 (RAM 4GB 이상 필요)".
Planner spec 톤과 align. "부족합니다" (비난 어조) → "사용할 수 없어요"
(정보 제공 톤). 안내문 끝 마침표 제거.
2) ModelAvailability.missing 메시지가 RAM 게이트 active 상태에서 "위
토글을 켜면" 안내를 표시해 모순 발생. meetsRam=false 분기 추가 →
"이 단말은 모델을 받을 수 없어요 (RAM 4GB 이상 필요)" 노출.
3) _confirmOptOut 보조 텍스트 "다시 켜면 다시 다운로드해야 합니다"
→ "다시 켜면 처음부터 다운로드합니다". "다시" 중복 제거 + 호흡 정리.
기능 동작 변화 0. analyze clean, 88/88 통과.
Refs #218
QA round 1 (commit 9a9eb2a) FAIL 시 누락된 두 AC 보강.
AC-6: device_info_plus 만으론 4GB 임계 측정 불가 (isLowRamDevice 는
~1GB 기준). MethodChannel `life_helper/device_caps` 신설 + MainActivity.kt
에서 ActivityManager.MemoryInfo.totalMem 노출. data/ai/device_capabilities.dart
는 DeviceCapabilities abstract + PlatformDeviceCapabilities + 4 GiB
임계. deviceMeetsAiRamProvider (FutureProvider<bool>, fail-closed).
SettingsScreen 토글 disabled + "RAM 부족" 안내 (RAM < 4GB).
AC-10: docs/reference/215-ai-frame-suggest.md 의 OQ-1/placeholder
6곳을 실 구현 표현으로 갱신. §8 알려진 제약 = AC-6 device gate +
AC-7 실 단말 E2E + F1 unload + #221 corpus 평가. §9 다음 단계 =
#219~#222 follow-up 목록. 신규 테스트 합계 41 / 전체 88 통과.
테스트: device_capabilities_test.dart 7 신규 (kAiMinRamBytes 동등,
null/0/3.9GB/4GB-1/4GB/8GB 경계). flutter analyze 무이슈, 전체 88 통과
(71 기존 + 10 gemma + 7 RAM gate).
Architect 설계서 §4 의 "RAM 4GB 차단 = AC-9 재활용" 문구는 사실 #215
미구현 사항이라 본 라운드에서 신규 추가했음을 README 에 명기.
Refs #218
