# 复习模块设计说明

本文档是对复习功能当前实现边界的工程说明，不修改原始需求文档。

## 核心理解

复习模块包含两类不同层级的体验：碎片化提醒和围绕思维导图的主动回忆。二者都属于复习模块，但不是同一个业务流程。

## 碎片化提醒

碎片化提醒展示用户自己在学习过程中写下的学习报告和学习残片。

这些内容不是完整复习记录，而是日常滚动出现的记忆触发物。用户看到一段自己写过的内容时，如果能立刻回想起上下文，说明相关知识暂时不需要深入复习；如果想不起来，可以点击进入详情页回看，形成一次轻量提醒。

当前对应能力：

- `GET /review/feed`
- `GET /review/task/{taskNum}`
- `GET /review/report/{id}`
- `GET /review/fragment/{id}`
- 前端 `Review.vue`
- 前端 `ReviewDetail.vue`

## 当前阶段边界

当前阶段暂不追求完整的自动化复习分析，因为项目尚未引入 AI 来处理学习碎片和导图数据。

当前阶段复习模块只需要保留思维导图的基本结构能力：

- 保存任务对应的思维导图
- 支持用户上传外部导图文件
- 解析导图的基础节点结构
- 允许用户在碎片化提醒中回看学习报告和学习残片

这个阶段不应该强制用户逐条处理大量学习碎片。学习碎片很多时，逐条关联和对照会让复习过程变得漫长、枯燥，并违背复习模块“简单、不抵触、可随意围绕某个知识点复习”的初衷。

## 思维导图的意义

思维导图不是普通附件，也不是单纯的存储对象。它是复习模块的主要交互形式。

用户复习时，主要动作应该是围绕某个知识点进行回忆，并编写或重绘思维导图。导图的意义在于降低复习阻力：用户不需要按顺序处理所有碎片，而是可以从任意知识点出发，自由地把自己能想起来的内容组织成结构。

初版设计中已经提到：

- 后续复习时可以在脑子里重绘那张图
- 没有想起来的部分就是需要重新看的地方
- 如果顺利绘制出了好的思维导图，就替换原来的思维导图
- 如果能顺利用思维导图描述所学内容，复习效果就能体现在这个过程中

因此，导图应该是复习效果的表达方式，而不仅是文件存储。

## 应用场景的位置

应用场景不应归属复习模块。

应用场景更接近学习任务的最终目标：完成整个学习任务后，用户希望能做什么、产出什么、应用到哪里。它应该挂在学习任务模块下，而不是挂在复习流程或某条学习碎片下。

当前实现已将其迁移为任务级能力，由任务页面维护，并使用 `task_applications` 存储。

## 模块边界

学习执行模块产生学习报告和学习残片。

复习模块使用这些产物做两件事：

- 在碎片化提醒中滚动展示它们
- 在引入 AI 后，把它们整理进程序生成的知识网络

复习模块不要求用户手动逐条整理学习报告和学习残片。学习报告/残片是后续自动整理和对照分析的数据来源。

## 下一阶段设计：AI 生成导图与用户导图对比

下一阶段引入 AI 后，复习模块的目标应升级为：

1. 程序读取学习报告、学习残片、已有导图等数据。
2. 程序自动将碎片整理成一个具有关联关系的巨大思维导图。
3. 用户围绕某个知识点进行回忆，并绘制自己的导图。
4. 系统将用户导图与程序生成导图进行结构对比。
5. 系统定位用户忽略、遗漏、误解或尚未建立关联的内容。
6. 用户根据差异回看必要的学习报告或残片，而不是从头处理所有碎片。

这个设计可以解决当前手动复习流程的两个问题：

- 学习碎片很多时，不需要用户逐条筛选，避免复习过程漫长且枯燥。
- 思维导图不再只是存储对象，而是成为用户回忆结果和程序知识网络之间的对照媒介。

## 对初版设计的补充判断

初版设计没有忽略“思维导图用于复习”的方向，反而已经明确指出导图应承担脑内重绘、发现遗漏、体现复习效果的作用。

初版设计没有具体描述“AI 自动整理碎片为巨大导图，并与用户导图进行对比”的实现逻辑。这是当前讨论对初版设计的重要补充，适合放入下一阶段实现。

初版中提到”复习内容可以应用到什么地方”，但结合当前理解，应用场景应从复习模块中移出，归入学习任务的最终目标或验收目标。

## 第二阶段实现：标准思维导图与回忆对比（2026-07-03）

第二阶段将 AI 生成导图与用户导图对比的设计落地，引入以下能力：

### 核心概念

- **标准思维导图（Standard Mind Map）**：每个学习任务对应一份”标准”导图，由系统从该任务的已有学习报告、学习残片、应用场景中提取整理而成。它是用户回忆的对照基准，也可由用户手动编辑修正。
- **回忆对比（Recall Review）**：用户凭记忆以缩进大纲格式写下对该任务知识点的回忆，系统将其与标准导图进行树结构对比，定位已掌握、遗漏和额外回忆的内容。

### 内置生成器（BuiltinMindMapGenerator）

当前阶段未接入外部 AI，由内置规则引擎生成标准导图：

- **根节点**：任务名称
- **一级分支**：按学习会话分组，以”日期 + 报告前60字摘要”为标题
- **子分支**：该会话下的每条报告、每条残片成为一个子节点
- **应用场景分支**：如有已创建的应用场景，附加为独立的”应用场景”分支
- **去重**：同级节点按标准化标题对比并合并
- **追溯**：每个节点携带 `sourceType`（REPORT/FRAGMENT/APPLICATION）和 `sourceId`，前端可点击回看原文

### AI 客户端抽象（MindMapAiClient）

预留了远程 AI 调用接口，供后续接入真实 AI 使用：

- 配置项 `lpt.ai.endpoint` / `lpt.ai.api-key`（当前均未配置）
- 未配置时自动回退到内置生成器
- 接口返回 `MindMapNode` 树结构，与内置生成器输出格式一致

### 回忆对比算法（StandardMindMapServiceImpl.compareTrees）

对比标准导图与用户回忆大纲的树结构：

1. **展平**：前序遍历将两颗树分别展开为节点列表
2. **精确匹配**：对每个标准节点标题做归一化（去空格标点 + 小写），在回忆节点中查找完全匹配
3. **模糊匹配**：未精确匹配时，计算字符 Bigram Jaccard 相似度（阈值 0.6），容忍中文同义表达
4. **标注**：匹配的节点标注 `MATCHED`，遗漏的节点标注 `MISSED`，用户多写的内容归为 `EXTRA`
5. **统计**：计算回忆覆盖率 `recall_ratio = matched / (matched + missed)`

### 用户交互

- **回忆复习页**（`/review/recall/:taskNum`）：双栏布局。左栏为回忆大纲输入区（缩进文本）+ 对比结果展示，右栏为标准导图区（默认折叠防剧透）
- **标准导图编辑**：用户可展开查看、编辑大纲文本并保存，编辑后来源标记为 `USER`
- **重新生成**：如需从头生成新版本，可一键重新生成
- **遗漏项回溯**：对比后定位到的遗漏知识点自动列出，点击”查看原文”可直接跳转到对应的报告/残片详情页
- **回忆历史**：查阅历次回忆对比记录，查看覆盖率变化趋势

### 新增数据库表

- `review_standard_mind_maps`：每任务一行，存储标准导图的 JSON 树结构、大纲文本、生成元信息
- `review_recall_records`：存储用户每次回忆对比的原始大纲、对比结果 JSON、覆盖率等统计

未改动既有表的 schema，与原有 `review_mind_maps`（用户手动上传的导图文件）并存。

### 新增端点

| 方法 | 端点 | 说明 |
|------|------|------|
| GET | `/review/standard-mind-map/{taskNum}` | 获取或自动生成标准导图 |
| POST | `/review/standard-mind-map/{taskNum}/regenerate` | 强制重新生成 |
| PUT | `/review/standard-mind-map/{taskNum}` | 用户编辑标准导图 |
| POST | `/review/standard-mind-map/{taskNum}/recall` | 用户提交回忆大纲，返回对比结果 |
| GET | `/review/standard-mind-map/{taskNum}/recall-records` | 回忆对比历史列表 |
| GET | `/review/standard-mind-map/recall-records/{recordId}` | 单条回忆记录详情 |

### 下一步展望

- 接入真实 AI API（配置 `lpt.ai.api-key` 后切换为 AI 生成器，内置生成器作为降级）
- 可视化思维导图渲染（而非纯缩进文本展示）
- 对比结果中显示更精确的路径定位
- AI 驱动的用户导图评分与改进建议