M3-02 Review Engine Module #30

New Issue

wangdl · 2026-05-22T21:09:50+08:00

wangdl commented

2026-05-22 21:09:50 +08:00

目标

设计知习复习引擎模块，为 C 端用户提供基于 Anki 状态机的复习调度、ReviewCard 管理和掌握度追踪能力。

本 Issue 只做模块架构设计，不直接实现代码。

背景说明

用户完成学习后，AIAnalysisCompleted 事件触发 Review Engine 生成 ReviewCard。ReviewCard 进入复习队列，用户每天有今日复习任务，作答后系统根据 Anki 风格的状态机（learn/review/relearn）更新 ScheduleState 和下一次复习时间。MasterySnapshot 记录用户对每个知识点的掌握度变化。

关键约束：Review Engine 通过订阅 AIAnalysisCompleted 事件获得触发，不直接依赖 Learning Engine 的 Service。

模块职责

本模块负责：
- ReviewCard 管理（生成、状态、内容）
- ScheduleState 状态机（learn/review/relearn 三态，仿 Anki）
- DueQueue（今日到期复习队列）
- ReviewAttempt（用户作答记录）
- RetryTicket（错题返练）
- DailyTask（每日复习任务组织）
- MasterySnapshot（掌握度快照，随时间变化）
- 下次复习时间计算
- 订阅 AIAnalysisCompleted 事件生成 ReviewCard
本模块不负责：
- AI 分析和诊断（走 Learning Engine）
- 知识点管理（走 Artifact & KnowledgeItem）
- 学习统计和趋势（走 Growth & Retention）
- 每日目标设定（走 Growth & Retention）

候选数据对象

ReviewCard（复习卡片）
ScheduleState（调度状态：learn/review/relearn 状态机）
ReviewAttempt（作答记录）
RetryTicket（错题返练票据）
DailyTask（每日复习任务）
MasterySnapshot（掌握度快照）
ReviewSession（复习会话）

状态机设计

请设计 ReviewCard 的完整状态机：

New → Learning（首次复习中，按 Anki learn 步进）
→ Review（进入长期复习队列，按 Anki SM-2 或类似算法计算间隔）
→ Relearning（复习失败，重新学习）

每次 ReviewAttempt 更新 ScheduleState 和 MasterySnapshot。

基础设施依赖判断

MySQL：是
Redis：是（今日复习队列缓存、DueQueue 快速查询）
BullMQ：是（复习卡片批量生成、每日任务调度）
Qdrant：否
AI Gateway：否（复习卡片内容由 Learning Engine 的 AI 分析结果生成，本模块不直接调用 AI）
Content Safety：否（复习卡片内容来自已审核的 Learning 结果）

API 设计

CAPI：
- 获取今日复习任务（DailyTask + ReviewCard 列表）
- 提交复习作答
- 获取下一次复习时间预估
- 复习历史和统计
- 错题返练列表
AAPI：
- 复习数据查看（用户维度）
- 调度参数配置（复习间隔参数等，通过 Config 模块）

Domain Event 设计

ReviewCardGenerated（由 AIAnalysisCompleted 触发）
ReviewAttemptSubmitted
ScheduleStateUpdated
MasterySnapshotUpdated
DailyTaskCompleted
RetryTicketCreated

交付检查

是否需要 Prisma migration：是
是否需要 MySQL：是
是否需要 Redis：是
是否需要 BullMQ：是
是否需要 AI Gateway：否
是否需要 Content Safety：否
是否需要 Cost 记录：否
是否需要 Domain Event：是
是否需要 Admin 视图：是（用户复习数据查看）
是否需要 E2E/集成测试：是

验收标准

ReviewCard / ScheduleState / MasterySnapshot Prisma schema
复习状态机设计（learn/review/relearn）
复习间隔算法选型（Anki SM-2 简化版或自定义，请判断并说明理由）
AIAnalysisCompleted → ReviewCard 生成的事件订阅链路
DailyTask 今日复习组织方案
错题返练机制设计
Admin 复习数据视图设计
集成测试覆盖完整复习流程

禁止事项

禁止 Review Engine 直接调用 Learning Engine 的 Service（只能通过事件订阅）
禁止复习调度算法过于复杂导致计算瓶颈
禁止 ReviewCard 内容绕过 Learning Engine 的 AIAnalysis
禁止 ReviewAttempt 不更新 ScheduleState 和 MasterySnapshot

不建议当前阶段实现

Anki 完整 SM-2 算法的所有参数可配置（先简化版）
复习提醒的推送通知（Notification 模块在 M3-05 处理）
复习卡片的自定义模板
批量复习的间隔优化

## 目标设计知习复习引擎模块，为 C 端用户提供基于 Anki 状态机的复习调度、ReviewCard 管理和掌握度追踪能力。本 Issue 只做模块架构设计，不直接实现代码。 ## 背景说明用户完成学习后，AIAnalysisCompleted 事件触发 Review Engine 生成 ReviewCard。ReviewCard 进入复习队列，用户每天有今日复习任务，作答后系统根据 Anki 风格的状态机（learn/review/relearn）更新 ScheduleState 和下一次复习时间。MasterySnapshot 记录用户对每个知识点的掌握度变化。关键约束：Review Engine 通过订阅 AIAnalysisCompleted 事件获得触发，不直接依赖 Learning Engine 的 Service。 ## 模块职责 1. 本模块负责： - ReviewCard 管理（生成、状态、内容） - ScheduleState 状态机（learn/review/relearn 三态，仿 Anki） - DueQueue（今日到期复习队列） - ReviewAttempt（用户作答记录） - RetryTicket（错题返练） - DailyTask（每日复习任务组织） - MasterySnapshot（掌握度快照，随时间变化） - 下次复习时间计算 - 订阅 AIAnalysisCompleted 事件生成 ReviewCard 2. 本模块不负责： - AI 分析和诊断（走 Learning Engine） - 知识点管理（走 Artifact & KnowledgeItem） - 学习统计和趋势（走 Growth & Retention） - 每日目标设定（走 Growth & Retention） ## 候选数据对象 - ReviewCard（复习卡片） - ScheduleState（调度状态：learn/review/relearn 状态机） - ReviewAttempt（作答记录） - RetryTicket（错题返练票据） - DailyTask（每日复习任务） - MasterySnapshot（掌握度快照） - ReviewSession（复习会话） ## 状态机设计请设计 ReviewCard 的完整状态机： New → Learning（首次复习中，按 Anki learn 步进） → Review（进入长期复习队列，按 Anki SM-2 或类似算法计算间隔） → Relearning（复习失败，重新学习）每次 ReviewAttempt 更新 ScheduleState 和 MasterySnapshot。 ## 基础设施依赖判断 - MySQL：是 - Redis：是（今日复习队列缓存、DueQueue 快速查询） - BullMQ：是（复习卡片批量生成、每日任务调度） - Qdrant：否 - AI Gateway：否（复习卡片内容由 Learning Engine 的 AI 分析结果生成，本模块不直接调用 AI） - Content Safety：否（复习卡片内容来自已审核的 Learning 结果） ## API 设计 1. CAPI： - 获取今日复习任务（DailyTask + ReviewCard 列表） - 提交复习作答 - 获取下一次复习时间预估 - 复习历史和统计 - 错题返练列表 2. AAPI： - 复习数据查看（用户维度） - 调度参数配置（复习间隔参数等，通过 Config 模块） ## Domain Event 设计 - ReviewCardGenerated（由 AIAnalysisCompleted 触发） - ReviewAttemptSubmitted - ScheduleStateUpdated - MasterySnapshotUpdated - DailyTaskCompleted - RetryTicketCreated ## 交付检查 - [x] 是否需要 Prisma migration：是 - [x] 是否需要 MySQL：是 - [x] 是否需要 Redis：是 - [x] 是否需要 BullMQ：是 - [x] 是否需要 AI Gateway：否 - [x] 是否需要 Content Safety：否 - [x] 是否需要 Cost 记录：否 - [x] 是否需要 Domain Event：是 - [x] 是否需要 Admin 视图：是（用户复习数据查看） - [x] 是否需要 E2E/集成测试：是 ## 验收标准 1. ReviewCard / ScheduleState / MasterySnapshot Prisma schema 2. 复习状态机设计（learn/review/relearn） 3. 复习间隔算法选型（Anki SM-2 简化版或自定义，请判断并说明理由） 4. AIAnalysisCompleted → ReviewCard 生成的事件订阅链路 5. DailyTask 今日复习组织方案 6. 错题返练机制设计 7. Admin 复习数据视图设计 8. 集成测试覆盖完整复习流程 ## 禁止事项 - 禁止 Review Engine 直接调用 Learning Engine 的 Service（只能通过事件订阅） - 禁止复习调度算法过于复杂导致计算瓶颈 - 禁止 ReviewCard 内容绕过 Learning Engine 的 AIAnalysis - 禁止 ReviewAttempt 不更新 ScheduleState 和 MasterySnapshot ## 不建议当前阶段实现 - Anki 完整 SM-2 算法的所有参数可配置（先简化版） - 复习提醒的推送通知（Notification 模块在 M3-05 处理） - 复习卡片的自定义模板 - 批量复习的间隔优化

wangdl added this to the M3：学习复习闭环（P2） milestone 2026-05-22 21:09:50 +08:00

wangdl self-assigned this 2026-05-22 21:09:50 +08:00

wangdl commented

2026-05-24 14:12:16 +08:00

✅ M3-02 实施完成

交付内容

模块	说明
Anki SM-2 算法	简化的间隔重复算法：评分≥3 延长间隔，<3 重置到 relearning
ScheduleState 状态机	new → learning → review ↔ relearning
间隔计算	8 级间隔 [1,1,3,7,14,30,60,120,240] 天
Ease Factor	默认 2.5，最低 1.3，按评分动态调整

SM-2 算法

正确（rating ≥ 3）：间隔 × easeFactor，easeFactor += 0.1
错误（rating < 3）：重置间隔为1天，easeFactor -= 0.2
ReviewCard 字段：intervalDays, easeFactor, repetitionCount, lapseCount, scheduleState

E2E

Route smoke tests for review endpoints.

npx jest --config ./test/jest-e2e.json

## ✅ M3-02 实施完成 ### 交付内容 | 模块 | 说明 | |------|------| | Anki SM-2 算法 | 简化的间隔重复算法：评分≥3 延长间隔，<3 重置到 relearning | | ScheduleState 状态机 | new → learning → review ↔ relearning | | 间隔计算 | 8 级间隔 [1,1,3,7,14,30,60,120,240] 天 | | Ease Factor | 默认 2.5，最低 1.3，按评分动态调整 | ### SM-2 算法 - 正确（rating ≥ 3）：间隔 × easeFactor，easeFactor += 0.1 - 错误（rating < 3）：重置间隔为1天，easeFactor -= 0.2 - ReviewCard 字段：intervalDays, easeFactor, repetitionCount, lapseCount, scheduleState ### E2E Route smoke tests for review endpoints. ```bash npx jest --config ./test/jest-e2e.json ```

wangdl closed this issue

2026-06-06 14:43:16 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/api-server#30