[Developer] #215 AI frame-suggest vertical slice (mock LlmService)

설계서대로 구현. flutter_gemma 실제 통합은 OQ-1 (모델 URL+SHA) 확정 후.
v1은 LlmService 추상 + ModelLifecycle (다운로드/SHA/purge) + Riverpod
providers + 다이얼로그 + Settings 화면까지. main.dart 가 MockLlmService 를
override 해 모든 경로가 graceful (suggest 결과는 빈 리스트).

추가:
- lib/data/ai/{llm_service,gemma_llm_service,model_lifecycle}.dart
- lib/domain/ai/{frame_candidate,few_shot_builder,parse_response,suggest_frame}.dart
- lib/state/ai_providers.dart (aiSettings + modelAvailability + frameSuggestions)
- lib/ui/screens/settings_screen.dart (opt-in 토글 + 모델 상태 표시)
- lib/ui/widgets/frame_suggestion_dialog.dart (후보 3개 카드 + 다시 시도)
- HabitCreateScreen: "AI 제안" 버튼 (opt-in + ready 일 때만 노출)
- MetaDao.remove(key) 추가 (purge 용)

테스트 31개 신규 추가 (총 62개 통과):
- test/domain/ai/{suggest_frame, few_shot_builder, parse_response}_test.dart
- test/data/ai/model_lifecycle_test.dart (download/SHA/purge/availability)

flutter analyze 0 issue, flutter build apk --debug 통과.

Refs #215

app/lib/ui/screens/habit_create_screen.dart

@@ -3,10 +3,14 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 
 import '../../core/constants.dart';
 import '../../core/time.dart';
+import '../../data/ai/model_lifecycle.dart';
 import '../../data/db/daos/habit_dao.dart';
+import '../../domain/ai/frame_candidate.dart';
 import '../../domain/models/habit.dart';
 import '../../domain/rules/active_habit_quota.dart';
+import '../../state/ai_providers.dart';
 import '../../state/providers.dart';
+import '../widgets/frame_suggestion_dialog.dart';
 
 class HabitCreateScreen extends ConsumerStatefulWidget {
   const HabitCreateScreen({super.key});
@@ -118,7 +122,14 @@ class _HabitCreateScreenState extends ConsumerState<HabitCreateScreen> {
                 validator: (v) =>
                     (v == null || v.trim().isEmpty) ? '프레임 문구를 입력하세요' : null,
               ),
-              const SizedBox(height: 24),
+              const SizedBox(height: 8),
+              _AiSuggestButton(
+                titleCtrl: _titleCtrl,
+                framedCtrl: _framedCtrl,
+                habitType: _type,
+                onSelectLevel: (level) => setState(() => _level = level),
+              ),
+              const SizedBox(height: 16),
               FilledButton(
                 onPressed: _saving ? null : _save,
                 child: Text(_saving ? '저장 중...' : '저장'),
@@ -135,3 +146,63 @@ String _ymd(DateTime d) =>
     '${d.year.toString().padLeft(4, '0')}-'
     '${d.month.toString().padLeft(2, '0')}-'
     '${d.day.toString().padLeft(2, '0')}';
+
+/// "AI 제안" button — only visible when opt-in is ON and model is ready.
+/// Graceful: hidden otherwise (AC-5, AC-9).
+class _AiSuggestButton extends ConsumerWidget {
+  final TextEditingController titleCtrl;
+  final TextEditingController framedCtrl;
+  final HabitType habitType;
+  final ValueChanged<FrameLevel> onSelectLevel;
+  const _AiSuggestButton({
+    required this.titleCtrl,
+    required this.framedCtrl,
+    required this.habitType,
+    required this.onSelectLevel,
+  });
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final settings = ref.watch(aiSettingsProvider);
+    final availability = ref.watch(modelAvailabilityProvider);
+    final visible = settings.maybeWhen(
+          data: (v) => v,
+          orElse: () => false,
+        ) &&
+        availability.maybeWhen(
+          data: (a) => a == ModelAvailability.ready,
+          orElse: () => false,
+        );
+    if (!visible) return const SizedBox.shrink();
+    return Align(
+      alignment: Alignment.centerRight,
+      child: TextButton.icon(
+        icon: const Icon(Icons.auto_awesome),
+        label: const Text('AI 제안'),
+        onPressed: () async {
+          final raw = titleCtrl.text.trim();
+          if (raw.isEmpty) {
+            ScaffoldMessenger.of(context).showSnackBar(
+              const SnackBar(content: Text('먼저 제목을 입력해주세요')),
+            );
+            return;
+          }
+          final picked = await FrameSuggestionDialog.show(
+            context,
+            input: SuggestFrameInput(
+              rawText: raw,
+              habitType: habitType,
+            ),
+          );
+          if (picked != null) {
+            framedCtrl.text = picked;
+            // Heuristic: identity-style ("나는") → L3, else L2.
+            onSelectLevel(
+              picked.startsWith('나는') ? FrameLevel.l3 : FrameLevel.l2,
+            );
+          }
+        },
+      ),
+    );
+  }
+}

app/lib/ui/screens/habit_list_screen.dart

@@ -4,6 +4,7 @@ import 'package:flutter_riverpod/flutter_riverpod.dart';
 import '../../state/providers.dart';
 import 'check_in_screen.dart';
 import 'habit_create_screen.dart';
+import 'settings_screen.dart';
 import 'streak_screen.dart';
 
 class HabitListScreen extends ConsumerWidget {
@@ -15,7 +16,20 @@ class HabitListScreen extends ConsumerWidget {
     final habitsAsync = ref.watch(activeHabitsProvider);
 
     return Scaffold(
-      appBar: AppBar(title: const Text('습관')),
+      appBar: AppBar(
+        title: const Text('습관'),
+        actions: [
+          IconButton(
+            icon: const Icon(Icons.settings),
+            tooltip: '설정',
+            onPressed: () {
+              Navigator.of(context).push(MaterialPageRoute(
+                builder: (_) => const SettingsScreen(),
+              ));
+            },
+          ),
+        ],
+      ),
       body: boot.when(
         loading: () => const Center(child: CircularProgressIndicator()),
         error: (e, st) => Center(child: Text('초기화 실패: $e')),

app/lib/ui/screens/settings_screen.dart

@@ -0,0 +1,161 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../data/ai/model_lifecycle.dart';
+import '../../state/ai_providers.dart';
+
+class SettingsScreen extends ConsumerWidget {
+  const SettingsScreen({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    return Scaffold(
+      appBar: AppBar(title: const Text('설정')),
+      body: ListView(
+        children: const [
+          _SectionHeader('AI 도움'),
+          _AiSection(),
+        ],
+      ),
+    );
+  }
+}
+
+class _SectionHeader extends StatelessWidget {
+  final String title;
+  const _SectionHeader(this.title);
+  @override
+  Widget build(BuildContext context) {
+    return Padding(
+      padding: const EdgeInsets.fromLTRB(16, 16, 16, 4),
+      child: Text(
+        title,
+        style: Theme.of(context).textTheme.titleSmall,
+      ),
+    );
+  }
+}
+
+class _AiSection extends ConsumerWidget {
+  const _AiSection();
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final settings = ref.watch(aiSettingsProvider);
+    final availability = ref.watch(modelAvailabilityProvider);
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.stretch,
+      children: [
+        SwitchListTile(
+          title: const Text('AI 도움 켜기'),
+          subtitle: const Text(
+            'Gemma 4 E2B 모델 ≈ 1.5GB. 모든 처리는 단말에서 일어납니다.',
+          ),
+          value: settings.maybeWhen(
+            data: (v) => v,
+            orElse: () => false,
+          ),
+          onChanged: (v) async {
+            if (v) {
+              final ok = await _confirmOptIn(context);
+              if (ok != true) return;
+            } else {
+              final ok = await _confirmOptOut(context);
+              if (ok != true) return;
+            }
+            final freed =
+                await ref.read(aiSettingsControllerProvider).setOptIn(v);
+            if (!context.mounted) return;
+            if (!v && freed > 0) {
+              ScaffoldMessenger.of(context).showSnackBar(
+                SnackBar(content: Text('공간 확보됨 ${_fmtMB(freed)}')),
+              );
+            }
+          },
+        ),
+        availability.when(
+          loading: () => const ListTile(title: Text('상태 확인 중...')),
+          error: (e, _) => ListTile(title: Text('상태 오류: $e')),
+          data: (a) => ListTile(
+            title: const Text('모델 상태'),
+            subtitle: Text(_describe(a)),
+          ),
+        ),
+        const Padding(
+          padding: EdgeInsets.fromLTRB(16, 8, 16, 16),
+          child: Text(
+            'OQ-1 미해결: 정확한 모델 URL + SHA 가 픽스되기 전까지 '
+            '다운로드는 동작하지 않습니다. (Architect/Developer 인계 사항)',
+            style: TextStyle(fontSize: 12, color: Colors.grey),
+          ),
+        ),
+      ],
+    );
+  }
+
+  String _describe(ModelAvailability a) {
+    switch (a) {
+      case ModelAvailability.ready:
+        return '사용 가능';
+      case ModelAvailability.missing:
+        return '미설치 — 토글을 켜면 다운로드를 시작합니다';
+      case ModelAvailability.corrupt:
+        return '손상됨 — 토글을 끄고 다시 켜주세요';
+      case ModelAvailability.downloading:
+        return '다운로드 중 / 일시정지됨';
+    }
+  }
+
+  String _fmtMB(int bytes) {
+    final mb = bytes / (1024 * 1024);
+    return '${mb.toStringAsFixed(1)} MB';
+  }
+
+  Future<bool?> _confirmOptIn(BuildContext context) {
+    return showDialog<bool>(
+      context: context,
+      builder: (_) => AlertDialog(
+        title: const Text('AI 도움 켜기'),
+        content: const Text(
+          'Gemma 4 E2B 모델 ≈ 1.5GB 를 다운로드합니다.\n'
+          '- WiFi 권장\n'
+          '- 모든 처리는 단말에서만 일어나며, 입력 텍스트는 외부로 전송되지 않습니다.\n'
+          '- 끄면 즉시 삭제됩니다.',
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(context).pop(false),
+            child: const Text('취소'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.of(context).pop(true),
+            child: const Text('동의 후 다운로드'),
+          ),
+        ],
+      ),
+    );
+  }
+
+  Future<bool?> _confirmOptOut(BuildContext context) {
+    return showDialog<bool>(
+      context: context,
+      builder: (_) => AlertDialog(
+        title: const Text('AI 도움 끄기'),
+        content: const Text(
+          '모델 파일 ≈ 1.5GB 가 즉시 삭제됩니다. '
+          '다시 켜면 다시 다운로드해야 합니다.',
+        ),
+        actions: [
+          TextButton(
+            onPressed: () => Navigator.of(context).pop(false),
+            child: const Text('취소'),
+          ),
+          FilledButton(
+            onPressed: () => Navigator.of(context).pop(true),
+            child: const Text('끄고 삭제'),
+          ),
+        ],
+      ),
+    );
+  }
+}

app/lib/ui/widgets/frame_suggestion_dialog.dart

@@ -0,0 +1,102 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_riverpod/flutter_riverpod.dart';
+
+import '../../domain/ai/frame_candidate.dart';
+import '../../domain/models/habit.dart';
+import '../../state/ai_providers.dart';
+
+/// Shows L2/L3 suggestion cards from suggestFrame. Returns the selected
+/// framed_text via `Navigator.pop(context, candidate.framedText)`.
+class FrameSuggestionDialog extends ConsumerWidget {
+  final SuggestFrameInput input;
+  const FrameSuggestionDialog({super.key, required this.input});
+
+  static Future<String?> show(
+    BuildContext context, {
+    required SuggestFrameInput input,
+  }) {
+    return showDialog<String>(
+      context: context,
+      builder: (_) => FrameSuggestionDialog(input: input),
+    );
+  }
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final async = ref.watch(frameSuggestionsProvider(input));
+    return AlertDialog(
+      title: const Text('AI 제안'),
+      content: SizedBox(
+        width: 320,
+        child: async.when(
+          loading: () => const SizedBox(
+            height: 120,
+            child: Center(child: CircularProgressIndicator()),
+          ),
+          error: (e, _) => Padding(
+            padding: const EdgeInsets.all(8),
+            child: Text('AI 제안을 받지 못했습니다. 직접 입력해주세요.\n($e)'),
+          ),
+          data: (candidates) {
+            if (candidates.isEmpty) {
+              return Column(
+                mainAxisSize: MainAxisSize.min,
+                crossAxisAlignment: CrossAxisAlignment.stretch,
+                children: [
+                  const Padding(
+                    padding: EdgeInsets.all(8),
+                    child: Text(
+                      '더 구체적으로 입력해주시면 더 좋은 제안을 드릴 수 있어요.',
+                    ),
+                  ),
+                  TextButton(
+                    onPressed: () {
+                      ref.invalidate(frameSuggestionsProvider(input));
+                    },
+                    child: const Text('다시 시도'),
+                  ),
+                ],
+              );
+            }
+            return Column(
+              mainAxisSize: MainAxisSize.min,
+              children: [
+                for (final c in candidates)
+                  _CandidateCard(
+                    candidate: c,
+                    onTap: () => Navigator.of(context).pop(c.framedText),
+                  ),
+              ],
+            );
+          },
+        ),
+      ),
+      actions: [
+        TextButton(
+          onPressed: () => Navigator.of(context).pop(),
+          child: const Text('취소'),
+        ),
+      ],
+    );
+  }
+}
+
+class _CandidateCard extends StatelessWidget {
+  final FrameCandidate candidate;
+  final VoidCallback onTap;
+  const _CandidateCard({required this.candidate, required this.onTap});
+
+  @override
+  Widget build(BuildContext context) {
+    return Card(
+      child: ListTile(
+        title: Text(candidate.framedText),
+        subtitle: Text(
+          '${candidate.level == FrameLevel.l3 ? "L3 · 정체성" : "L2 · 조건부 긍정"} '
+          '· 신뢰도 ${(candidate.confidence * 100).toInt()}%',
+        ),
+        onTap: onTap,
+      ),
+    );
+  }
+}