# 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）的回忆卡片入口「前往回忆复习」按钮文字和位置可以优化