[03-Developer] #311 LLM warm-up + concurrent guard + quickCheck

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>
This commit is contained in:
2026-06-15 12:52:50 +09:00
parent 1fa4f24a8a
commit 5b4c05316a
8 changed files with 587 additions and 22 deletions

View File

@@ -37,13 +37,28 @@ class GemmaLlmService implements LlmService {
InferenceModel? _model;
bool _loaded = false;
Future<void>? _loadingFuture;
@override
bool get isLoaded => _loaded;
/// #311 AC7: concurrent-call guard. If a load is already in-flight (e.g.
/// `ChatScreen` warm-up + a racing `userTurn` lazy load), return the same
/// Future so native init runs at most once per process.
/// See `docs/design/311-llm-warmup/fn-concurrent_load_guard.md`.
@override
Future<void> load() async {
if (_loaded) return;
Future<void> load() {
if (_loaded) return Future.value();
final existing = _loadingFuture;
if (existing != null) return existing;
final future = _doLoad();
_loadingFuture = future;
return future.whenComplete(() {
_loadingFuture = null;
});
}
Future<void> _doLoad() async {
if (!await File(modelPath).exists()) {
throw FileSystemException('model file missing', modelPath);
}