docs: 复习流程设计文档（DESIGN_REVIEW.md）

完整描述复习功能的核心概念、流程设计、三个入口、
API 清单、组件结构、数据流图和文件索引。

DESIGN_REVIEW.md

@@ -0,0 +1,413 @@
+# LPT 复习流程设计文档
+
+> 本文档描述 LPT 系统中「回忆复习」（Recall Review）功能的完整设计，包括数据模型、API、前端交互流程和三种入口的处理方式。
+
+---
+
+## 1. 核心概念
+
+### 1.1 标准思维导图（Standard Mind Map）
+
+- **任务级单一知识树**：每个学习任务有且仅有一棵标准思维导图，存储在 `review_standard_mind_maps` 表
+- **生成方式**：
+  - `BUILTIN`：内置规则引擎，按 session 分组、去重、合并
+  - `AI`：调用 lpt-ai 服务生成缩进大纲后解析
+  - `USER`：用户手动编辑
+  - `USER_MERGE`：增量合并后（保留用户编辑 + 追加 AI 新节点）
+- **数据结构**：`content` 字段存储 JSON 树（递归 `MindMapNode`），`outline` 字段存储缩进大纲文本
+- **节点模型**：
+  ```
+  MindMapNode {
+    title: string        // 节点标题
+    notes?: string       // 备注 / 对比标记（MATCHED| / MISSED|）
+    sourceType?: string  // REPORT | FRAGMENT | APPLICATION
+    sourceId?: number    // 对应源数据主键
+    children?: MindMapNode[]
+  }
+  ```
+- **节点标记约定**（用于对比着色）：
+  - `notes` 以 `MATCHED|` 开头 → 绿色（回忆命中）
+  - `notes` 以 `MISSED|` 开头 → 红色（回忆遗漏）
+  - 无标记 → 默认色（未参与对比）
+
+### 1.2 回忆对比记录（Recall Record）
+
+- 每次用户提交回忆 → 生成一条 `review_recall_records` 记录
+- 核心字段：
+  - `task_num`：关联任务
+  - `standard_map_id`：对比时使用的标准导图版本
+  - `focus_path`：复习起点节点路径（`"根 / 分支A / 子节点B"`），null 为全量
+  - `recall_content`：用户回忆大纲文本
+  - `compare_result`：对比结果 JSON（含 `matchedTree`、`extraNodes`、覆盖率等）
+  - `recall_ratio` / `matched_count` / `missed_count` / `extra_count`：统计摘要
+
+---
+
+## 2. 复习流程
+
+### 2.1 核心逻辑
+
+```
+1. 确定复习起点（节点路径）
+2. 获取标准导图
+3. 按起点提取子树作为对比基准
+4. 用户在大纲编辑器中回忆填充
+5. 提交对比（AI 语义匹配 或 BUILTIN 字符串匹配）
+6. 展示对比结果（着色 + 统计）
+```
+
+### 2.2 节点选择
+
+- 用户在标准导图上点击节点 → `MindMapViewer` 发射 `node-select` 事件（含 `title`、`path`、`childCount`）
+- 弹窗确认：「以「节点名」为起点，复习其下 N 个子知识点？」
+- 确认后：
+  - `focusPath` = 选中节点的路径（如 `"Java基础 / 集合 / HashMap"`）
+  - `recallTree` 根节点标题 = 选中节点标题
+  - 回忆导图以该标题为根，用户补充子节点
+
+### 2.3 对比范围
+
+- **有 `focusPath`**：`MindMapTreeTool.extractSubtree(root, focusPath)` 提取子树，对比基准 = 子树
+- **无 `focusPath`**：对比基准 = 整棵标准导图
+- AI 对比：发给 lpt-ai 的 outline 只包含子树范围
+- BUILTIN 对比：`compareTrees()` 在子树范围内做标题匹配
+
+### 2.4 对比算法
+
+**AI 语义匹配（优先）：**
+```
+POST /ai/tasks → type: "compare-recall"
+→ 异步轮询结果
+→ 返回 { matches: [{standardTitle, recallTitle}], missedTitles, extraNodes, evaluation }
+→ Java 端 buildCompareResultFromAI() 标注标准树
+```
+
+**BUILTIN 字符串匹配（降级）：**
+- 展平标准树和回忆树
+- 标题标准化（去标点、去空格、转小写）
+- 精确匹配 → 模糊匹配（bigram Jaccard ≥ 0.6）
+- 标记 MATCHED / MISSED / 额外
+
+### 2.5 结果展示
+
+- 标准导图面板直接显示着色对比结果（不再有独立对比面板）
+- 绿色（`#c8e6c9`）= 命中，红色（`#ffcdd2`）= 遗漏
+- 统计卡片：覆盖率、命中/遗漏/额外计数
+- 遗漏项列表 + 额外项列表（可点击回看原文）
+
+---
+
+## 3. 三个复习入口
+
+### 入口 A：复习总览 → "回忆复习"
+
+**路径：** `Welcome.vue` → "复习回看" → `Review.vue`（任务列表）→ 每行"回忆复习"按钮
+
+**前端代码：** `Review.vue:110`
+```typescript
+router.push(`/review/recall/${row.taskNum}`)
+```
+
+**流程：**
+1. 跳转到 `ReviewRecall.vue`，URL 为 `/review/recall/:taskNum`
+2. 页面加载 → `loadData()` 获取标准导图
+3. 标准导图 `selectable=true`，显示提示「点击导图节点选择复习起点」
+4. 用户点击节点 → 弹窗确认 → 进入回忆模式
+5. 回忆填充 → 提交对比 → 展示结果
+
+**相关文件：**
+- `lpt-fe/src/components/Review.vue`
+- `lpt-fe/src/components/ReviewRecall.vue`
+
+### 入口 B：从某个残片/报告详情 → "回忆复习"
+
+**路径：** `Welcome.vue` 滚动回顾 → 点击卡片 → `ReviewDetail.vue` → "回忆复习"按钮
+
+**前端代码：** `ReviewDetail.vue` 的 `goToRecall()`
+```typescript
+const res = await findNode(taskNum, content.substring(0, 500));
+if (res?.data?.path) {
+  router.push(`/review/recall/${taskNum}?focusPath=${encodeURIComponent(res.data.path)}`);
+}
+```
+
+**流程：**
+1. 用户在详情页查看某个残片/报告的内容
+2. 点击"回忆复习" → 前端调 `POST /review/standard-mind-map/{taskNum}/find-node`
+3. 后端 `findClosestNode()` 用 bigram Jaccard 匹配最接近的节点
+4. 返回 `{ path, nodeTitle, score }`
+5. 跳转到 `/review/recall/:taskNum?focusPath=...`
+6. `ReviewRecall.vue` 检测到 URL 参数 → 跳过节点选择，直接进入回忆模式
+
+**后端 API：**
+```http
+POST /review/standard-mind-map/{taskNum}/find-node
+Content-Type: application/json
+
+{ "content": "用户查看的残片/报告文本" }
+
+→ 200 OK
+{ "code": 200, "data": { "path": "根 / 分支A / 子节点B", "nodeTitle": "子节点B", "score": 0.85 } }
+```
+
+**匹配算法（`MindMapTreeTool.findClosestNode`）：**
+1. 展平标准导图所有节点
+2. 对每个节点，计算其 `title` 与输入文本的 bigram Jaccard 相似度
+3. `notes` 字段也参与匹配（权重 0.5）
+4. 返回得分最高（>0.1）的节点
+
+**相关文件：**
+- `lpt-fe/src/components/ReviewDetail.vue`
+- `learning-progress-tracker/.../utils/MindMapTreeTool.java`（`findClosestNode`、`similarityScore`）
+
+### 入口 C：首页欢迎页 → 回忆卡片 → "前往回忆复习"
+
+**路径：** `Welcome.vue` → 滚动回顾标签 → 点击弹出回忆对话框 → "前往回忆复习"按钮
+
+**前端代码：** `Welcome.vue` 的 `goToRecallFromCard()`
+```typescript
+const tn = group.taskNum;
+const res = await findNode(tn, content.substring(0, 500));
+if (res?.data?.path) {
+  router.push(`/review/recall/${tn}?focusPath=${encodeURIComponent(res.data.path)}`);
+}
+```
+
+**流程：**
+1. Welcome 页加载 `GET /review/feed` 获取复习 feed
+2. 按 session 分组为标签卡片
+3. 用户点击某个标签 → 弹出回忆对话框（先回忆→展开对照）
+4. 点击"前往回忆复习" → 同入口 B，先调 findNode 再跳转
+
+**相关文件：**
+- `lpt-fe/src/components/Welcome.vue`
+
+---
+
+## 4. 关键 API 清单
+
+### 4.1 标准思维导图
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| `GET` | `/review/standard-mind-map/{taskNum}` | 获取/自动生成标准导图 |
+| `POST` | `/review/standard-mind-map/{taskNum}/regenerate?mode=full\|incremental` | 重新生成 |
+| `PUT` | `/review/standard-mind-map/{taskNum}` | 用户编辑（大纲文本） |
+| `POST` | `/review/standard-mind-map/{taskNum}/recall` | 提交回忆对比 |
+| `POST` | `/review/standard-mind-map/{taskNum}/find-node` | 匹配最近节点 |
+| `GET` | `/review/standard-mind-map/{taskNum}/recall-records` | 历史回忆记录 |
+
+### 4.2 回忆对比请求体
+
+```json
+{
+  "recallOutline": "用户回忆的缩进大纲文本\n  - 子节点1\n  - 子节点2",
+  "focusPath": "根标题 / 分支A / 子节点B"
+}
+```
+
+- `recallOutline`：必填，用户回忆的缩进大纲
+- `focusPath`：可选，复习起点节点路径。null = 全量，提供时对比范围为该子树
+
+### 4.3 对比结果结构（CompareResult）
+
+```json
+{
+  "matchedTree": {
+    "title": "根节点",
+    "notes": "",
+    "children": [
+      {
+        "title": "命中的知识点",
+        "notes": "MATCHED|完整原文内容",
+        "sourceType": "REPORT",
+        "sourceId": 1,
+        "children": []
+      },
+      {
+        "title": "遗漏的知识点",
+        "notes": "MISSED|完整原文内容",
+        "sourceType": "FRAGMENT",
+        "sourceId": 2,
+        "children": []
+      }
+    ]
+  },
+  "extraNodes": [
+    { "title": "用户额外回忆的知识", "path": "/额外/..." }
+  ],
+  "recallRatio": 0.75,
+  "matchedCount": 3,
+  "missedCount": 1,
+  "extraCount": 1,
+  "evaluation": "AI 评价文本（仅 AI 对比时有值）"
+}
+```
+
+---
+
+## 5. 前端组件结构
+
+```
+ReviewRecall.vue（主页面）
+├── Page header（返回、标题、历史记录按钮）
+├── 复习起点指示（focusPath 显示 + 重选按钮）
+├── 节点选择确认弹窗（el-dialog）
+├── 统计卡片（覆盖率/命中/遗漏/额外）
+├── 回忆历史列表
+├── 回忆输入（editable MindMapViewer）
+├── 标准导图 + 对比结果（color-by-compare MindMapViewer）
+│   ├── 未选择起点时 → selectable 模式
+│   ├── 已选择起点/已对比 → 着色展示
+│   └── 编辑模式 → editable 模式
+└── 遗漏项 + 额外项详情列表
+```
+
+### 5.1 MindMapViewer 组件 Props
+
+| 属性 | 类型 | 默认 | 说明 |
+|------|------|------|------|
+| `tree` | `MindMapTreeNode \| null` | — | 树数据 |
+| `editable` | `boolean` | `false` | 是否可编辑 |
+| `colorByCompare` | `boolean` | `false` | 按 MATCHED/MISSED 着色 |
+| `height` | `string` | `'480px'` | 画布高度 |
+| `selectable` | `boolean` | `false` | 节点单击可选择 |
+| `selectedPath` | `string` | `''` | 当前选中节点路径 |
+
+### 5.2 MindMapViewer 事件
+
+| 事件 | 载荷 | 触发时机 |
+|------|------|----------|
+| `change` | `outline: string` | 编辑模式下结构变化 |
+| `node-click` | `{ sourceType, sourceId }` | 点击带溯源标签的节点 |
+| `node-select` | `{ title, path, childCount }` | selectable 模式下点击节点 |
+
+### 5.3 MindMapViewer 暴露方法
+
+```typescript
+defineExpose({ toOutline })
+// toOutline() → 缩进大纲文本
+```
+
+---
+
+## 6. 后端核心工具方法
+
+### `MindMapTreeTool.java`
+
+| 方法 | 说明 |
+|------|------|
+| `extractSubtree(root, path)` | 按 "/" 分隔路径提取子树，返回深拷贝 |
+| `findClosestNode(root, content)` | bigram Jaccard 匹配最近节点 |
+| `getPath(root, targetTitle)` | 获取节点到根的路径字符串 |
+| `similarityScore(a, b)` | 两段文本的 bigram Jaccard 相似度 |
+| `mergeTrees(oldRoot, newRoot)` | 按标准化标题合并新旧树 |
+| `toJson(root, mapper)` | 序列化为 JSON |
+| `fromJson(json, mapper)` | 从 JSON 反序列化 |
+| `toOutline(root)` | 树 → 缩进大纲 |
+| `toFullOutline(root)` | 树 → 完整大纲（含根标题） |
+| `parseOutline(text)` | 缩进大纲 → 树 |
+| `flatten(root)` | 前序遍历展平 |
+| `countNodes(root)` | 节点总数 |
+| `maxDepth(root)` | 最大深度 |
+
+### `StandardMindMapServiceImpl.java`
+
+| 方法 | 说明 |
+|------|------|
+| `getOrGenerate(taskNum)` | 获取/自动生成标准导图 |
+| `regenerate(taskNum)` | 全量重新生成（防并发） |
+| `incrementalGenerate(taskNum)` | 增量合并（保留用户编辑） |
+| `updateByOutline(taskNum, outline)` | 用户编辑 |
+| `recallCompare(taskNum, outline, focusPath)` | 回忆对比 |
+| `findNode(taskNum, content)` | 查找最近节点 |
+| `listRecallRecords(taskNum)` | 历史记录 |
+| `getRecallRecord(id)` | 单条记录详情 |
+
+---
+
+## 7. 关键文件索引
+
+### 前端（`lpt-fe/src/`）
+
+| 文件 | 说明 |
+|------|------|
+| `components/ReviewRecall.vue` | 回忆复习主页面 |
+| `components/Review.vue` | 复习总览（任务列表+入口） |
+| `components/ReviewDetail.vue` | 残片/报告详情页 |
+| `components/Welcome.vue` | 首页（内含回忆卡片入口） |
+| `components/MindMapViewer.vue` | 思维导图渲染/编辑/选择组件 |
+| `api/standardMindMap.ts` | 标准导图 API 封装 |
+| `api/review.ts` | 复习 feed API |
+| `api/studySessions.ts` | 学习会话 API |
+
+### 后端（`learning-progress-tracker/src/main/java/.../`）
+
+| 文件 | 说明 |
+|------|------|
+| `controller/ReviewController.java` | 复习相关端点 |
+| `service/StandardMindMapService.java` | 标准导图服务接口 |
+| `service/impl/StandardMindMapServiceImpl.java` | 服务实现 |
+| `service/impl/BuiltinMindMapGenerator.java` | 内置规则生成器 |
+| `service/impl/RemoteAiMindMapClient.java` | AI 导图客户端 |
+| `service/impl/AiServiceClient.java` | lpt-ai 通用客户端 |
+| `utils/MindMapNode.java` | 树节点 DTO |
+| `utils/MindMapTreeTool.java` | 树操作工具类 |
+| `utils/CompareResult.java` | 对比结果 DTO |
+| `entity/ReviewStandardMindMapEntity.java` | 标准导图实体 |
+| `entity/ReviewRecallRecordEntity.java` | 回忆记录实体 |
+| `db/migration/V20260706_1__add_focus_path_to_recall_records.sql` | focus_path 迁移 |
+
+### AI 服务（`lpt-ai/src/`）
+
+| 文件 | 说明 |
+|------|------|
+| `routes/ai.ts` | AI 任务提交/轮询/抓取标题 |
+| `task-queue.ts` | 异步任务队列 |
+| `llm/prompts.ts` | prompt 模板（generate-mind-map / compare-recall / aggregate-report） |
+| `llm/client.ts` | LLM API 客户端 |
+| `admin/routes.ts` | 管理面板 |
+
+---
+
+## 8. 数据流图
+
+```
+学习碎片/报告
+    ↓ (按 session 分组)
+BuiltinMindMapGenerator / RemoteAiMindMapClient
+    ↓
+标准思维导图（review_standard_mind_maps）
+    ↓ (用户选择节点)
+extractSubtree(root, focusPath)
+    ↓
+子树（对比基准）
+    ↓ AI / BUILTIN 对比 ← 用户回忆大纲
+    ↓
+CompareResult
+    ↓ (序列化存储 + 前端渲染)
+review_recall_records + 着色 MindMapViewer
+```
+
+---
+
+## 9. 历史版本记录
+
+| Commit | 说明 |
+|--------|------|
+| `a636e51` | 新增 sessionNum 追踪 + 维度选择（已回退） |
+| `e5adb40` | 前端会话选择器（已回退） |
+| `3c3f682` | 防并发生成 + `mergeTrees` + 增量合 |
+| `5a5a294` | 前端防抖/生成提示/移除冗余面板 |
+| `84fe452` | **节点选择交互 + focusPath + findNode（当前）** |
+| `b18f8b4` | **后端 focusPath + extractSubtree + 回退 session（当前）** |
+| `ebbbeb4` | fix: Array.map 多参数 bug |
+
+---
+
+## 10. 待办/已知问题
+
+- [ ] AI 生成的导图（`RemoteAiMindMapClient`）因为没有 `sourceId`/`sourceType`，`node-click` 溯源不可用
+- [ ] `selectable` 模式下，点击无子节点的叶子节点，`childCount` = 0 的确认弹窗体验略奇怪
+- [ ] `findClosestNode` 的 bigram 相似度对短文本效果有限，可能需要 `notes` 加权优化
+- [ ] 欢迎页（Welcome.vue）的回忆卡片入口「前往回忆复习」按钮文字和位置可以优化