# iOS 学习与复习流程

> 版本：0.1.0 | 更新：2026-05-24

## 整体流程

```
创建知识库 → 上传资料 → 导入知识点 → 开始学习 → 主动回忆 → AI 分析 → 复习巩固
```

## 1. 学习会话

```
POST /api/learning-sessions
{ mode: "active_recall", knowledgeBaseId: "kb-1" }
────────────────────────►  创建会话 (status=active)
◄───────────────────────  { id, startedAt, mode }

...学习过程...

POST /api/learning-sessions/:id/end
────────────────────────►  结束会话 (status=completed)
                         记录 durationSeconds
◄───────────────────────  { id, durationSeconds }
```

**mode 枚举：** `active_recall` | `feynman` | `review` | `reading`

## 2. 主动回忆

```
GET /api/active-recalls?page=1&limit=20
◄───────────────────────  题目列表（含问题/选项）

POST /api/active-recalls/:id/submit
{ answer: "用户答案" }
────────────────────────►  记录回答 → 触发 AI 分析
                          (异步：BullMQ ai-analysis 队列)
◄───────────────────────  { success: true }
```

## 3. AI 分析

```
POST /api/ai-analysis
{ ... }
────────────────────────►  创建分析作业

GET /api/ai-analysis/jobs/:id
◄───────────────────────  { status: "pending|processing|completed|failed" }

GET /api/ai-analysis/:id
◄───────────────────────  分析结果（强项/弱项/建议）
```

**分析完成后自动生成：**
- ReviewCard（复习卡片，SM-2 算法调度）
- FocusItem（薄弱项，待巩固）

## 4. 复习（SM-2 间隔重复）

```
GET /api/reviews/due
◄───────────────────────  今日待复习卡片列表
                         [{
                           id, frontText, difficulty,
                           scheduleState, intervalDays,
                           repetitionCount, lapseCount
                         }]

POST /api/reviews/:id/submit
{ quality: 4 }
────────────────────────►  提交复习质量评分 (0-5)
                         SM-2 算法更新:
                         - easeFactor
                         - intervalDays
                         - nextReviewAt
                         - scheduleState
◄───────────────────────  { id, nextReviewAt, intervalDays }
```

**scheduleState：** `new` → `learning` → `review` → `relearning`

**quality 评分指南：**

| 评分 | 含义 |
|------|------|
| 0 | 完全忘记 |
| 1 | 错误，有印象 |
| 2 | 错误，但正确答案看起来很熟悉 |
| 3 | 正确，但费了很大劲 |
| 4 | 正确，有些犹豫 |
| 5 | 完美，毫不费力 |

## 5. 薄弱项跟踪

```
GET /api/focus-items?status=open
◄───────────────────────  [{ id, title, priority, status }]

POST /api/focus-items/:id/complete
────────────────────────►  标记为已掌握
◄───────────────────────  { id, status: "completed" }
```

**priority 枚举：** `high` | `normal` | `low`

## 6. 学习统计

```
GET /api/activity/heatmap
◄───────────────────────  [{ date, count }]  365 天热力图数据

GET /api/activity/streak
◄───────────────────────  { currentStreak, longestStreak }

GET /api/activity/summary
◄───────────────────────  { totalSessions, totalDuration, ... }
```

## 完整学习主链路

```
1. 创建/选择知识库     POST /api/knowledge-bases
2. 上传资料            POST /api/files/upload-url → PUT COS → POST /api/files/complete
3. 创建来源 + 导入     POST /api/knowledge-bases/:id/sources
4. 轮询导入状态        GET /api/imports/:id/status
5. 开始学习会话        POST /api/learning-sessions
6. 主动回忆练习        GET/POST /api/active-recalls
7. AI 分析             POST /api/ai-analysis
8. 每日复习            GET /api/reviews/due → POST /api/reviews/:id/submit
9. 跟踪薄弱项          GET → POST /api/focus-items/:id/complete
```