flutter架构项目基础

2026-09-04 15:22:20 +08:00
parent 70967229d0
commit 0c5aee59c0
265 changed files with 35484 additions and 0 deletions
@@ -0,0 +1,605 @@
+# 试卷练习功能架构设计
+
+> 本文档是 `features/exam/` 试卷练习功能（PageView.builder 大数据滑动 + 题型分发 + 续答持久化）的架构说明。
+> 面向 Flutter 初学者，重点解释"每一层为什么这么设计"。
+> **没学过 Riverpod / Isar 的，先读「零、新手前置」教程，再看架构；**
+> 阅读前提：了解本项目技术栈（Riverpod / Isar / go_router，见 pubspec.yaml 注释）。
+
+---
+
+## 零、新手前置：Riverpod 与 Isar 使用教程
+
+> 本章是**工具用法入门**（面向 Flutter 新手），看完能读懂本项目所有 provider 和 store 代码；
+> 后面一~九章是架构设计。建议阅读顺序：先学本章 → 再看架构 → 最后动手改代码。
+> 所有示例都是本项目真实代码，可以直接打开对应文件对照。
+
+### 0.1 Riverpod 状态管理怎么用
+
+#### 0.1.1 它解决什么问题
+
+Flutter 的界面是 `Widget` 树。数据如果存在组件内部，组件一销毁数据就没了。
+Riverpod（本项目 3.3.2，flutter_riverpod 包）把"数据"提升到组件树之外的全局容器（provider）里，
+界面通过"订阅"拿到数据，**数据一变界面自动重建**——这就是响应式。
+
+对标 Vue3：`provider ≈ Pinia store`，`ref.watch ≈ storeToRefs / computed`，`ref.read(provider.notifier).方法() ≈ store action`。
+
+#### 0.1.2 上手第一步：包根（main.dart 已写好）
+
+```dart
+// main.dart（本项目实际代码，最后一行）
+runApp(const ProviderScope(child: TabApp()));
+```
+
+`ProviderScope` 是所有 provider 的容器，必须包在最外层。**新建项目时这一步不能忘**，
+否则任何页面 `ref.watch` 都会报 "ProviderScope is missing"。
+
+#### 0.1.3 上手第二步：定义一个"同步状态"（答案数据，最小完整示例）
+
+```dart
+// answer_provider.dart（本项目实际代码）
+// ① 声明 provider：<Notifier类, 状态类型>，构造函数引用传入
+final answerProvider =
+    NotifierProvider<AnswerNotifier, Map<int, String>>(AnswerNotifier.new);
+
+// ② 写 Notifier 类：状态在这里定义、修改
+class AnswerNotifier extends Notifier<Map<int, String>> {
+  @override
+  Map<int, String> build() => {};          // 初始状态：空 Map
+
+  void answer(int questionId, String value) {
+    state = {...state, questionId: value}; // ③ 修改：必须整体赋新值！
+  }
+
+  void clear() => state = {};              // 重置
+}
+```
+
+新手必须记住的规则：
+- `build()` 返回初始状态；
+- **修改状态永远用 `state = 新值`**，不能 `state.xxx = ...`。Dart 的 Map 是引用类型，
+  直接改内部元素不会触发通知——所以要 `{...state, ...}` 展开成新 Map 再整体赋值；
+- Notifier 是 Riverpod 3.x 的**推荐写法**（状态 + 操作方法封装在一个类里）。
+  老教程里的 `StateProvider` 已移入 legacy，不要学。
+
+#### 0.1.4 上手第三步：定义一个"异步状态"（题目数据，接口加载场景）
+
+```dart
+// paper_provider.dart（本项目实际代码，mock 分支）
+final paperProvider =
+    AsyncNotifierProvider<PaperNotifier, List<ExamQuestion>>(PaperNotifier.new);
+
+class PaperNotifier extends AsyncNotifier<List<ExamQuestion>> {
+  @override
+  Future<List<ExamQuestion>> build() async {
+    await Future.delayed(const Duration(milliseconds: 600)); // 模拟接口延迟
+    return MockExamData.generate(100);
+  }
+}
+```
+
+和同步版本的区别只有一个：`build()` 返回 `Future`。Riverpod 会自动把过程包装成 `AsyncValue`——
+它自带三态：`loading`（加载中）/ `error`（失败）/ `data`（成功）。页面这样消费：
+
+```dart
+// exam_page.dart（本项目实际代码，简化）
+final paperAsync = ref.watch(paperProvider);       // AsyncValue<List<...>>
+return paperAsync.when(
+  loading: () => const CircularProgressIndicator(), // ① 加载中 → 转圈
+  error: (e, _) => Text('试卷加载失败：$e'),          // ② 失败 → 报错文案
+  data: (questions) => PageView.builder(...),       // ③ 成功 → 出卷
+);
+```
+
+**怎么选 Async 还是普通 Notifier**：初始化需要"等一下"（接口 / 数据库查询）→ 用 Async；纯同步内存状态 → 用 Notifier。
+
+#### 0.1.5 页面怎么读：watch / read 区别（最高频考点）
+
+```dart
+class _ExamPageState extends ConsumerState<ExamPage> {
+  @override
+  Widget build(BuildContext context) {
+    final answers = ref.watch(answerProvider); // ① watch：订阅，变化就重建
+    // ...
+    onAnswer: (v) => ref.read(answerProvider.notifier) // ② read：只调方法，不订阅
+        .answer(q.questionId, v),
+  }
+}
+```
+
+- `ref.watch(provider)`：**订阅**。状态一变，build 重新执行（界面自动更新）。**只能写在 build 方法里**。
+- `ref.read(provider)`：**一次性读取**，不订阅。适合事件回调、initState。
+- 改状态：`ref.read(provider.notifier).方法()`（见上）。
+
+回调里写 `ref.watch` 会直接报错（"watch 不能在 build 之外使用"）——新手最常见的报错之一。
+
+#### 0.1.6 本项目 provider 一览（学完自检清单）
+
+| provider | 类型 | 状态 | 用途 |
+|---|---|---|---|
+| `paperProvider` | AsyncNotifierProvider | `List<ExamQuestion>` | 题目（异步加载） |
+| `answerProvider` | NotifierProvider | `Map<int, String>` | 答案（同步读写） |
+| `paperSizeProvider` | NotifierProvider | `int` | 生成题数（50/100/200） |
+| `privacyAcceptedNotifier` | NotifierProvider（core/providers/） | `bool` | 隐私同意状态 |
+
+#### 0.1.7 新手四个高频误区
+
+1. **别用 setState 存全局数据**：PageView 会回收滑出的页面，组件销毁数据就丢 → 数据上 provider（答案放 provider 就是这个原因）
+2. **watch 别用在回调里**：`onTap: () => ref.watch(x)` 编译报错 → 用 read
+3. **state 要整体替换**：`state['k'] = v` 不会刷新界面 → 用 `state = {...state, 'k': v}`
+4. **别让组件到处 watch**：组件里 watch 越多越难复用。本项目约定：只在 ExamPage 连接 provider，QuestionCard 收 props / 抛回调（受控组件模式）
+
+---
+
+### 0.2 Isar 本地数据库怎么用
+
+#### 0.2.1 它解决什么问题
+
+Isar 是 Dart 原生的本地 NoSQL 数据库（对标 Vue 的 localStorage，但强类型、毫秒级查询、支持索引和事务）。
+存"**跨会话**"的数据——进程杀掉后还要用的：题库、错题、播放记录、答题进度。
+
+本项目存储分三层（各管各的）：
+
+| 层 | 工具 | 存什么 |
+|---|---|---|
+| ① | flutter_secure_storage | Token 等敏感凭据（加密） |
+| ② | shared_preferences | 用户信息 / 开关等小配置（明文快读） |
+| ③ | **Isar（AppDatabase）** | 题库 / 错题 / 播放记录 / 答题进度（大批量结构化数据） |
+
+**为什么用 isar_community 而不是 isar**：官方 isar 3.1.8 只发在已宕机的私有源（pub.isar-community.dev），装不上；
+`isar_community`（本项目 3.3.2）是社区在 pub.dev 的维护版，API 与 isar 完全一致。
+
+#### 0.2.2 四个固定步骤：建一个 Isar 功能
+
+以本项目 AnswerRecord（答题进度）为例，完整走一遍：
+
+**第 1 步：建模型**（core/storage/models/answer_record.dart）
+
+```dart
+import 'package:isar_community/isar.dart';
+part 'answer_record.g.dart';       // 代码生成文件（第 2 步跑出来）
+
+@collection                        // 注解：告诉生成器"这是个集合"
+class AnswerRecord {
+  Id id = Isar.autoIncrement;      // ⚠ 必须有主键（自动递增）
+  @Index()                         // 索引：按 paperId 查走索引（毫秒级）
+  int? paperId;
+  int? questionId;
+  String? answer;
+  DateTime? updatedAt;
+}
+```
+
+三个规则：必须有 `@collection` 注解、必须有 `Id` 主键、必须 `part 'xxx.g.dart'`。
+
+**第 2 步：跑代码生成**（每改一次模型字段都要重跑）
+
+```bash
+dart run build_runner build
+```
+
+生成 `answer_record.g.dart`（里面是 `XxxSchema`——数据库的"表结构定义"）。改字段后不重跑，编译直接报错。
+
+**第 3 步：注册集合**（core/storage/database/app_database_io.dart 的 Isar.open）
+
+```dart
+isar = await Isar.open(
+  [
+    QuestionSchema,
+    WrongQuestionSchema,
+    PlayRecordSchema,
+    RemoteVersionEntitySchema,
+    AnswerRecordSchema,          // ← 新集合加到这里
+  ],
+  directory: dir.path,
+  name: 'app_db',
+  inspector: true,               // debug 模式启用 Isar Inspector 调试页面（见 0.2.5）
+);
+```
+
+**第 4 步：写读写代码**（core/storage/stores/answer_record_store_io.dart）
+
+```dart
+// 写：必须包在 writeTxn 事务里（Isar 约束）
+await db.isar.writeTxn(() async {
+  await db.answerRecords.put(AnswerRecord()..paperId = 1001);
+});
+
+// 查：where() 走索引，xxxEqualTo 由 @Index() 字段自动生成
+final list = await db.answerRecords
+    .where()
+    .paperIdEqualTo(1001)
+    .findAll();
+
+// 删：条件批量删
+await db.answerRecords.where().paperIdEqualTo(1001).deleteAll();
+```
+
+**核心 API 速查**：
+
+| 操作 | 代码 |
+|---|---|
+| 增 / 改（同 id 自动覆盖） | `writeTxn(() => collection.put(record))` |
+| 按 id 查 | `collection.get(id)` |
+| 条件查（走索引） | `collection.where().paperIdEqualTo(x).findAll()` |
+| 查全部 | `collection.where().findAll()` |
+| 数量 | `collection.count()` |
+| 条件批量删 | `collection.where().xxxEqualTo(x).deleteAll()` |
+
+#### 0.2.3 web 兼容：为什么必须"条件导出"三件套（本项目最大坑）
+
+Isar 生成的 `*.g.dart` 里有一个 64 位 schema 哈希常量（如 -6819722535046815095），
+JavaScript 最多只能精确表示 2^53 的整数 → **只要业务代码 import 了模型，web 编译必挂**
+（报 "The integer literal ... can't be represented exactly in JavaScript"）。
+即使运行时用 kIsWeb 跳过，**编译期**也过不了——因为静态 import 链已经把 .g.dart 拉进编译图了。
+
+解法（本项目约定）：
+- 模型 / 真数据库 → 只被 `*_io.dart` import（仅 native 编译）
+- 页面层 → 只 import 条件导出入口（如 answer_record_store.dart），这是页面唯一面对的接口
+- web 端 → `*_web.dart` 空实现（写入打印跳过、读取返回空），web 调试自动降级为纯内存
+
+```dart
+// answer_record_store.dart —— 页面的唯一入口
+// if (dart.library.io) 是【编译期】分发：native 编 io 版，web 编 web 版，运行期零开销
+export 'answer_record_store_web.dart'      // web 端：空实现
+    if (dart.library.io) 'answer_record_store_io.dart';  // 真机：真 Isar
+```
+
+#### 0.2.4 高频坑清单
+
+1. **init 必须在 runApp 前 await**（main.dart 已写好）：否则页面访问集合报 "Missing XxxSchema in Isar.open"
+2. **写操作必须包 writeTxn**：Isar 的事务约束，忘包会抛错
+3. **改模型字段后必须重跑 build_runner**：`dart run build_runner build`
+4. **业务页面永远不要 import 模型**：web 编译约束（见 0.2.3）
+5. **io 实现里 import app_database_io.dart**（具体实现），不要 import app_database.dart（条件导出入口）——
+   分析器会检查所有条件分支，web 分支下入口解析成空实现，io 文件里调 db.isar 会报 undefined getter
+
+#### 0.2.5 调试利器：Isar Inspector
+
+`app_database_io.dart` 已开启 `inspector: true`。debug 模式跑真机 / 模拟器时，
+浏览器打开 `http://localhost:8080` 就能可视化浏览、编辑数据库里的所有集合——
+查"答案到底存没存进去"用它最快，不用打日志。
+
+---
+
+## 一、概述
+
+### 1.1 功能背景
+
+原 Vue3 + uniapp 版 App 用 swiper 组件实现"左右滑动切换题目"，题目数量大时出现性能瓶颈（swiper 会一次性把所有题目挂载到 DOM）。Flutter 版需要：
+
+- 大数组（100+ 题）滑动不卡
+- 支持单选 / 多选 / 判断 / 解答四种题型
+- 答题中途退出，下次进来能续答（答案持久化）
+- 交卷后自动判分（客观题）
+
+### 1.2 核心思想
+
+**四层架构 + 单向数据流**：UI 层永远不直接碰数据库，数据永远单向流动。
+
+```
+数据库(Isar) → store → provider(状态) → UI(组件) → 用户操作 → provider → store → 数据库
+```
+
+这条规则是整个架构的命脉，理解它就能理解所有文件的分工。
+
+---
+
+## 二、架构总览
+
+```
+┌──────────────────────────────────────────────────────────┐
+│ ① Demo 层  pages/demo/exam_demo.dart                     │
+│    入口：选择题目数量(50/100/200) → 跳转试卷页             │
+├──────────────────────────────────────────────────────────┤
+│ ② UI 层  features/exam/（只管"怎么显示"）                 │
+│    exam_page.dart          试卷页：唯一连接状态的地方      │
+│    question_card.dart      题目卡片：纯展示组件            │
+│    answer_sheet_dialog.dart 答题卡：题号网格 + 跳题        │
+├──────────────────────────────────────────────────────────┤
+│ ③ 状态层  features/exam/（只管"状态放哪、怎么变"）         │
+│    exam_question.dart      题目接口模型（纯 Dart）         │
+│    question_type.dart      题型枚举                       │
+│    paper_provider.dart     题目数据（异步加载）            │
+│    answer_provider.dart    答案数据（同步读写）            │
+├──────────────────────────────────────────────────────────┤
+│ ④ 数据层  core/storage/（只管"怎么存"）                   │
+│    models/answer_record.dart  Isar 模型（续答持久化）      │
+│    answer_record_store*.dart  三件套（条件导出）           │
+└──────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 三、逐层详解
+
+### 3.1 数据层（core/storage/）——"数据怎么存"
+
+#### models/answer_record.dart
+
+```dart
+@collection
+class AnswerRecord {
+  Id id = Isar.autoIncrement;
+  @Index()
+  int? paperId;        // 试卷 id（续答恢复/交卷清理的维度）
+  int? questionId;     // 题目 id（对应题目模型的 questionId）
+  String? answer;      // 用户答案（统一 String，见 5.1）
+  DateTime? updatedAt; // 作答时间（用于定位"最后作答的题"）
+}
+```
+
+**为什么需要它**：答案的主状态在 Riverpod 内存里，进程一杀就丢。本模型按"试卷"维度把每题答案落盘，实现续答。
+
+**为什么 paperId 加 @Index()**：进卷恢复（`where(paperId).equalTo()`）和交卷清理都按它查，走索引毫秒级。
+
+#### answer_record_store.dart 三件套（条件导出）
+
+| 文件 | 作用 |
+|---|---|
+| `answer_record_store.dart` | 条件导出入口，页面唯一面对的接口 |
+| `answer_record_store_io.dart` | 真机实现：真 Isar 读写 |
+| `answer_record_store_web.dart` | web 空实现：打印跳过，不碰 isar |
+
+```dart
+// answer_record_store.dart —— 页面的唯一入口
+export 'answer_record_store_web.dart'      // web 端：空实现
+    if (dart.library.io) 'answer_record_store_io.dart';  // 真机：真 Isar
+```
+
+**为什么必须条件导出（本项目踩过的坑）**：
+Isar 模型生成的 `*.g.dart` 含 64 位 schema 哈希常量，JavaScript 无法精确表示 → **业务代码只要 import Isar 模型，web 编译必挂**。web 版空实现不 import isar，编译通过；真机编译 io 版，功能完整。
+
+**为什么接口用 dynamic 而不是模型类型**：模型 import 了 isar，web 端无法 import 模型，接口层返回 `List<dynamic>` 才能双端编译。
+
+**为什么选 Isar 而不是 shared_preferences**：
+- 项目存储分层约定（见 app_database_io.dart 注释）：secure_storage 存凭据 / shared_preferences 存小配置 / Isar 存业务数据
+- 答案记录按 paperId 增删查的结构化需求，shared_preferences 全量重写 JSON 会越写越卡
+- 交卷批量清理：`where(paperId).deleteAll()` 一句话搞定
+
+### 3.2 状态层（features/exam/）——"状态放哪、怎么变"
+
+#### exam_question.dart（纯 Dart 接口模型）
+
+**为什么不能用 Isar 的 Question 模型**：web 编译约束（见 3.1）。页面层需要强类型题目对象，但 Isar 模型进不了 web 编译图，所以定义纯 Dart 模型，字段与 Isar Question 对应（options 直接存 `List<String>`，接口 JSON 本来就是数组）。
+
+#### question_type.dart（题型枚举）
+
+```dart
+enum QuestionType { single(1, '单选题'), multi(2, '多选题'), judge(3, '判断题'), essay(4, '解答题') }
+```
+
+**为什么用枚举不用裸 int**：枚举自带 label（UI 标签）和 code（存储值），页面不用散落魔法数字；加新题型只改这一个文件。
+
+#### paper_provider.dart（题目数据）
+
+```dart
+final paperProvider = AsyncNotifierProvider<PaperNotifier, List<ExamQuestion>>(...);
+
+class PaperNotifier extends AsyncNotifier<List<ExamQuestion>> {
+  static const bool mock = true;   // 接口 mock 开关
+  Future<List<ExamQuestion>> build() async { ... }
+}
+```
+
+- **为什么 AsyncNotifierProvider**：题目从接口加载是异步的，AsyncValue 自带 loading / error / data 三态，页面 `when()` 分支渲染
+- **为什么 mock 用 const bool**：对标 Vue3 内联 mock 体验，一行开关切换本地生成 / 真实接口，热重启即生效
+- **为什么题目只放内存不落 Isar**：题目是"会话数据"不是"资产"，每次进卷拉最新（可能有勘误）；100 题 ≈ 1MB，内存无压力
+
+#### answer_provider.dart（答案数据）
+
+```dart
+final answerProvider = NotifierProvider<AnswerNotifier, Map<int, String>>(...);
+
+class AnswerNotifier extends Notifier<Map<int, String>> {
+  void answer(int questionId, String value) {
+    state = {...state, questionId: value};        // ① 内存主状态
+    unawaited(AnswerRecordStore.instance.put(...)); // ② 异步落盘（fire-and-forget）
+  }
+  void restore(Map<int, String> saved) { ... }    // 续答恢复
+  void clear() => state = {};                     // 交卷清理
+}
+```
+
+**为什么答案必须放 provider 而不是组件 setState**：PageView.builder 懒加载，滑出的页面 Element 会被回收，答案存在组件里滑回来就丢了。provider 全局存活。
+
+**为什么题目和答案分开两个 provider**：生命周期不同（题目只读一次 / 答案高频可写）。状态粒度越细，`ref.watch` 重建范围越小。
+
+**为什么 key 用 questionId 而不是本地自增 id**：续答恢复时题目重新拉取也能对上。
+
+### 3.3 UI 层（features/exam/）——"怎么显示"
+
+#### exam_page.dart（试卷页，唯一桥接层）
+
+整个功能只有这一个文件连接 Riverpod：
+
+```dart
+final paperAsync = ref.watch(paperProvider);   // 读题目（三态）
+final answers = ref.watch(answerProvider);     // 读答案（响应式）
+...
+QuestionCard(
+  key: ValueKey(q.questionId),   // 按题号隔离，防页面复用串题
+  question: q,                   // props 向下
+  answer: answers[q.questionId],
+  onAnswer: (v) => ref.read(answerProvider.notifier).answer(q.questionId, v), // 事件向上
+)
+```
+
+职责清单：
+- PageView.builder 组装（大数据滑动，见 5.2）
+- 续答恢复：`_restoreProgress()` 读 Isar → `restore()` 注入 → `_tryJumpAfterRestore()` 定位到最后作答的题
+- 交卷：确认弹窗 → `deleteByPaper` 清理 → `clear()` 清内存 → 判分
+- 顶部进度条、底部导航（上一题/答题卡/下一题）
+
+**为什么设计成唯一桥接层**：状态流单一，出 bug 只检查一个文件；QuestionCard 不依赖 provider，可复用、可单测。
+
+#### question_card.dart（纯展示组件）
+
+```dart
+class QuestionCard extends StatelessWidget {
+  const QuestionCard({
+    required this.question,   // 数据来自父级
+    required this.answer,     // 数据来自父级
+    required this.onAnswer,   // 事件抛给父级
+  });
+  // 内部按 question.type switch 分发：
+  //   single/multi → ChoiceQuestionView（共用选项布局，toggle 逻辑区分）
+  //   judge        → JudgeQuestionView（对/错两按钮）
+  //   essay        → EssayQuestionView（TextField + 300ms 防抖）
+}
+```
+
+对应 Vue3 的 **props 向下 + emit 向上**（受控组件）。好处：可复用（错题重做、试卷回顾）、可单测、状态流单一。
+
+**为什么解答题要 300ms 防抖**：onChanged 每敲一个字都会触发 provider 更新 + Isar 写库，防抖把高频输入合并为一次提交，减少写盘。
+
+#### answer_sheet_dialog.dart（答题卡）
+
+题号网格（5 列）+ 状态色（已答蓝 / 当前绿 / 未答灰）+ 点击跳题（onJump 回调上抛，由 ExamPage 执行 jumpToPage）。
+
+**为什么不直接碰 PageController**：跳转动作通过回调上抛，保持组件解耦，可复用于错题重做等场景。
+
+### 3.4 Demo 层（pages/demo/）
+
+- `exam_demo.dart`：说明卡 + SegmentedButton 选题目数量（50/100/200）+ 开始按钮
+- 注册入口在 `features/task/task_page.dart` 的 demo 列表末尾（项目组件封装与 Demo 验证模式）
+
+---
+
+## 四、核心数据流
+
+### 4.1 进卷（两个异步并行，互不依赖）
+
+```
+用户点"开始练习"
+  ├─ paperProvider.build() 加载题目（mock 600ms 延迟）→ UI 显示 loading
+  └─ ExamPage.initState → _restoreProgress()
+        └─ AnswerRecordStore.findByPaper(1001)   ← 查 Isar
+              └─ 有记录？
+                    ├─ answerProvider.restore(saved)      ← 注入内存
+                    └─ _tryJumpAfterRestore()             ← 定位到最后作答的题
+                          └─ jumpToPage(index)  （首帧后执行，等 PageView attach）
+```
+
+**为什么恢复和加载分开**：两个独立数据源（Isar / 接口），互不阻塞。题目加载失败也能恢复答案，反之也能做题。
+
+**为什么定位要处理"谁先完成"**：restore（Isar 查询）和题目加载（600ms）完成顺序不定。双保险：restore 完成后立即尝试（`_tryJumpAfterRestore`），build 的 data 分支再兜底触发一次，`_jumpToQuestion` 置 null 保证只定位一次。
+
+**为什么用 updatedAt 最新的一条定位**：重复作答会覆盖更新时间，天然表示"最后操作位置"（若希望始终定位最大题号，改为取 questionId 最大即可）。
+
+### 4.2 答题（一次点击，内存和磁盘各走一条路）
+
+```
+用户点选项 "B"
+  → ChoiceQuestionView._onTap → onAnswer("B")    ← 组件抛事件
+    → ExamPage 回调
+      → answerProvider.answer(1001, "B")
+        ① 内存：state = {...state, 1001: "B"}
+              → ref.watch 的页面自动重建（答题卡变蓝、进度条 +1）
+        ② 磁盘：AnswerRecordStore.put(...)  ← unawaited，不阻塞 UI
+```
+
+### 4.3 退出
+
+什么都不用做。答案在第 4.2 步已实时落盘（增量写），这就是"每次作答落盘"相对"交卷时统一保存"的优势：杀进程也不丢。
+
+### 4.4 交卷（清理 + 判分）
+
+```
+点"交卷" → 确认弹窗（已答/未答统计）
+  → deleteByPaper(1001)         ← 按 paperId 批量删 Isar 记录（防下次恢复旧答案）
+  → answerProvider.clear()      ← 清内存
+  → 判分：客观题比对 user == answer；解答题跳过（需人工批改）
+```
+
+**为什么交卷必须删记录**：否则下次进卷会恢复已交卷的答案。
+
+---
+
+## 五、关键设计决策（为什么这么弄）
+
+### 5.1 答案统一 String 格式
+
+| 题型 | 存储格式 |
+|---|---|
+| 单选 | `"A"`（一个字母） |
+| 多选 | `"A,C"`（字母升序逗号拼接） |
+| 判断 | `"对"` / `"错"` |
+| 解答 | 纯文本 |
+
+**为什么统一**：`Map<questionId, String>` 一个结构通吃所有题型，provider / Isar / 交卷序列化不分叉；判分一行比对；加新题型不改上层。编码/解码工作收敛在 QuestionCard 内部。
+
+### 5.2 PageView.builder 大数据性能
+
+```dart
+PageView.builder(
+  controller: _pageController,
+  itemCount: questions.length,       // 100 / 1000 都没关系
+  allowImplicitScrolling: true,      // 预构建相邻页 → 滑动不掉帧
+  itemBuilder: (context, i) => QuestionCard(key: ValueKey(q.questionId), ...),
+)
+```
+
+1. **builder 惰性构建**：只构建视口内 ±1 页，滑出即回收（Vue swiper 需要虚拟列表插件才能做到，Flutter 天生自带）
+2. **allowImplicitScrolling**：滑动动画开始前目标页已渲染，快速连滑无白屏
+3. **ValueKey(questionId)**：PageView 复用同一位置 Element，不带 key 换题时会显示旧内容
+
+### 5.3 内存 vs 磁盘的分工
+
+| 数据 | 位置 | 生命周期 |
+|---|---|---|
+| 题目列表 | Riverpod 内存 | 进卷拉取，退出即弃 |
+| 答案主状态 | Riverpod 内存 | 进卷注入，交卷清空 |
+| 答案持久化 | Isar AnswerRecord | 作答即写，交卷即删 |
+| 题库/错题本 | Isar（既有集合） | 跨会话资产 |
+
+---
+
+## 六、Vue3 → Flutter 概念对照
+
+| Vue3 | Flutter | 本项目体现 |
+|---|---|---|
+| swiper 组件 | `PageView.builder` | 左右滑题，懒加载 |
+| Pinia store | Riverpod provider | paperProvider / answerProvider |
+| storeToRefs / computed | `ref.watch(provider)` | 页面响应式读取 |
+| store action | `ref.read(provider.notifier).方法()` | answer() / restore() / clear() |
+| 组件 props / emit | 构造参数 / 回调 | QuestionCard 的 answer / onAnswer |
+| localStorage | Isar（或 shared_preferences） | AnswerRecord 续答落盘 |
+| Promise + setTimeout mock | `const bool mock` + Future.delayed | PaperNotifier 的 mock 开关 |
+| 组件内部 data | 不放组件，放 provider | PageView 会销毁页面 |
+
+---
+
+## 七、踩坑记录（血泪教训）
+
+1. **业务代码别 import Isar 模型**：`*.g.dart` 的 64 位 schema 哈希让 dart2js 编译失败。页面只能通过 store 接口（dynamic）拿数据
+2. **状态别放组件里**：页面销毁就丢。判断标准：数据在页面滑走/关掉后还需要吗？需要就放 provider
+3. **改 Isar 模型后必须重跑 build_runner**：`dart run build_runner build`（新版已移除 `--delete-conflicting-outputs` 参数）
+4. **Riverpod 3.x 的 StateProvider 已移入 legacy**：用现代 `Notifier` / `NotifierProvider` 写法（本项目 PaperSizeNotifier 即范例）
+5. **build_runner 重跑后 schema 哈希会变**：模型加字段后哈希变化是正常的，不要手改生成代码
+
+---
+
+## 八、扩展指南
+
+### 加一种新题型（如"填空"）
+
+1. `question_type.dart`：枚举加一项 `blank(5, '填空题')`
+2. `question_card.dart`：switch 加一个 case，写 BlankQuestionView
+3. `paper_provider.dart`：MockExamData 的循环里加一种分布
+4. 答案格式遵循 String 约定（填空存答案文本）
+
+上层（provider / store / 交卷）**一行不用改**——这就是统一 String 格式 + 纯展示组件设计带来的扩展性。
+
+### 接入真实接口
+
+1. `paper_provider.dart`：`mock = false`，build 里调 DioClient 拉题，`ExamQuestion.fromJson` 解析
+2. `answer_provider.dart`：`demoPaperId` 换成试卷对象传入的 paperId
+3. 交卷处替换模拟提交为真实接口（注意：接口失败不要删本地记录）
+
+---
+
+## 九、一句话总结
+
+> **数据存 Isar（store 收口）、状态住 Riverpod（provider 分层）、组件纯展示（props 进回调出）、页面只桥接（ExamPage 唯一连接点）** —— 每一层只做一件事，数据永远单向流动。
+
+这套四层模式是 Flutter 中型应用的通用骨架，后续任何新功能（错题本、收藏、播放记录）都按这个骨架填：建模型 → 写 store → 建 provider → 写组件 → 页面桥接。