# 错题本模块审计报告

> 审计日期：2026-06-24
> 审计范围：`src/modules/error-book/` 及 `src/app/(dashboard)/{student,teacher,parent,admin}/error-book/`
> 审计依据：项目规则 `docs/standards/coding-standards.md`、架构影响地图 `004`/`005`

---

## 一、现有实现概要

### 1.1 文件分布

错题本模块位于 `src/modules/error-book/`，包含以下文件：

| 文件 | 行数 | 职责 |
|------|------|------|
| `actions.ts` | 341 | 9 个 Server Actions（列表/详情/统计/增删改/复习/采集） |
| `data-access.ts` | **1029** | 数据访问层（学生 CRUD + 教师/管理员分析查询 + 跨模块接口） |
| `data-access-collection.ts` | 170 | 自动采集逻辑（考试/作业错题采集） |
| `schema.ts` | 51 | 4 个 Zod 验证 schema |
| `types.ts` | 245 | 11 个类型定义 + 状态映射常量 |
| `sm2-algorithm.ts` | 177 | SM-2 间隔重复算法（纯函数） |
| `sm2-algorithm.test.ts` | - | 39 个单元测试 |
| `components/` | 17 个文件 | UI 组件（学生卡片/列表/筛选/详情/图表等） |

### 1.2 路由分布

| 路由 | 角色 | 文件完整性 |
|------|------|-----------|
| `/student/error-book` | 学生 | page + loading + error ✅ |
| `/teacher/error-book` | 教师 | page + loading + error ✅ |
| `/parent/error-book` | 家长 | page + loading + error ✅ |
| `/admin/error-book` | 管理员 | page + loading + error ✅ |

### 1.3 架构图覆盖情况

架构影响地图 `004_architecture_impact_map.md` 第 2.28 节已覆盖该模块，记录了：
- 模块职责、导出函数、权限点、DataScope 行级权限
- SM-2 算法说明、自动采集机制
- 文件清单、路由清单、数据库表

**但存在以下不一致**：
1. `005_architecture_data.json` 的 `uses.shared` 仍列出 `examSubmissions`、`submissionAnswers`、`homeworkSubmissions` 等表，实际上这些已通过跨模块 data-access 接口访问（`data-access-collection.ts`），不再直接查询
2. JSON 未记录 `adaptive-practice` 依赖，但 `error-book-detail-dialog.tsx` 直接 import 了 `createPracticeSessionAction`
3. JSON 未记录 `ai` 模块依赖，但 `error-book-detail-dialog.tsx` 直接 import 了 `AiErrorBookAnalysis` 组件

---

## 二、现存问题与原因分析

### 2.1 【P0】跨模块直接依赖（违反三层架构规则）

**项目规则**：「模块间只能通过对方 data-access 通信，禁止跨模块直接查询数据库表」「该模块必须作为独立功能单元」

| 位置 | 违规内容 | 原因 | 后果 |
|------|---------|------|------|
| [error-book-detail-dialog.tsx](file:///e:/Desktop/CICD/src/modules/error-book/components/error-book-detail-dialog.tsx#L40) | `import { AiErrorBookAnalysis } from "@/modules/ai/components/ai-error-book-analysis"` | error-book 组件直接 import ai 模块组件 | 模块强耦合，无法独立测试/部署 |
| [error-book-detail-dialog.tsx](file:///e:/Desktop/CICD/src/modules/error-book/components/error-book-detail-dialog.tsx#L41) | `import { createPracticeSessionAction } from "@/modules/adaptive-practice/actions"` | error-book 组件直接 import adaptive-practice 的 Server Action | 模块强耦合，违反依赖注入原则 |
| [add-error-book-dialog.tsx](file:///e:/Desktop/CICD/src/modules/error-book/components/add-error-book-dialog.tsx#L26) | `import { getQuestionsAction } from "@/modules/questions/actions"` | error-book 组件直接 import questions 模块的 Action | 应通过 data-access 或注入接口调用 |

### 2.2 【P0】i18n 国际化严重遗漏

**项目规则**：「所有用户可见文本必须适配 i18n（使用 next-intl），提取翻译键」

虽然 `error-book.json` 翻译文件已存在（123 行），但**大量组件仍使用硬编码中文**：

| 组件 | 硬编码文本示例 | 行数 |
|------|--------------|------|
| `error-book-item-card.tsx` | "题目内容"、"难度"、"掌握度"、"复习 X 次"、"需复习"、"下次"、"未学习"、"入门"... | 10+ 处 |
| `error-book-detail-dialog.tsx` | "题目"、"我的答案"、"正确答案"、"AI 智能分析"、"复习自评"、"学习笔记"、"错误原因标签"、"复习历史"、"归档"、"删除"、"添加于"... | 20+ 处 |
| `error-book-filters.tsx` | "搜索笔记内容..."、"状态"、"来源"、"复习"、"全部状态"、"全部来源"... | 8+ 处 |
| `add-error-book-dialog.tsx` | "手动添加"、"添加错题"、"选择题目"、"学习笔记（可选）"、"错误原因标签"、"取消"、"添加"... | 10+ 处 |
| `review-buttons.tsx` | "重来"、"困难"、"良好"、"简单" 及描述文案（i18n 已有翻译但未使用） | 8 处 |
| `error-book-stats-cards.tsx` | "错题总数"、"待学习"、"学习中"、"已掌握"、"待复习" 及描述 | 10 处 |
| `analytics-stats-cards.tsx` | "覆盖学生"、"错题总数"、"平均掌握率"、"待复习"、"涉及知识点" 及子文案 | 10+ 处 |
| `subject-tabs.tsx` | "全部学科"、"待复习" | 2 处 |
| `class-filter.tsx` | "全部班级"、"错题"、"待复习" | 3 处 |
| `top-wrong-questions.tsx` | "高频错题"、"高频错题 Top 10"、"暂无高频错题"、"人错"、"人已掌握"、"掌握率" | 8 处 |
| `knowledge-point-weakness-chart.tsx` | "薄弱知识点 Top X"、"错题数"、"所属章节"、"错题数"、"已掌握"、"掌握率" | 8+ 处 |
| `chapter-weakness-chart.tsx` | "章节错题分布（哪些课在错）"、"错题数"、"已掌握"、"掌握率"、"知识点数"、"薄弱知识点" | 10+ 处 |
| `class-error-bar-chart.tsx` | "各班级错题数对比"、"错题总数"、"学生数"、"人均错题"、"平均掌握率"、"待复习" | 6+ 处 |
| `subject-distribution-chart.tsx` | "各学科错题分布"、"错题数"、"已掌握"、"掌握率" | 4+ 处 |
| `grouped-student-error-table.tsx` | "未分班"、"人"、"人有错题"、"错题总数"、"平均掌握率"、"学生" 及表头 | 15+ 处 |
| `class-error-overview.tsx` | "覆盖学生"、"错题总数"、"平均掌握率"、"薄弱知识点"、"学科错题分布" 等 | 15+ 处 |
| `error-book-list.tsx` | "错题本为空"、"查看详情" | 2 处 |
| `teacher/error-book/page.tsx` | "错题分析"、"按学科、班级查看学生的错题统计与薄弱知识点" 等 | 8+ 处 |

**总计约 150+ 处硬编码中文文本**，违反 i18n 规则。

### 2.3 【P0】类型安全问题（违反 TypeScript 严格模式）

**项目规则**：「禁止 `any`、禁止 `as` 断言（除类型收窄外）」

| 文件 | 行号 | 违规代码 | 类型 |
|------|------|---------|------|
| `data-access.ts` | 77 | `row.sourceType as ErrorBookItem["sourceType"]` | `as` 断言 |
| `data-access.ts` | 82 | `row.knowledgePointIds as string[] \| null` | `as` 断言 |
| `data-access.ts` | 90 | `row.errorTags as string[] \| null` | `as` 断言 |
| `data-access.ts` | 133 | `or(...)!` | 非空断言 |
| `data-access.ts` | 175 | `row as unknown as Parameters<typeof mapRowToItem>[0]` | 双重断言 |
| `data-access.ts` | 222 | 同上 | 双重断言 |
| `data-access.ts` | 657 | `row.knowledgePointIds as string[] \| null` | `as` 断言 |
| `data-access.ts` | 792 | 同上 | `as` 断言 |
| `actions.ts` | 63 | `params.status as "new" \| "learning" \| ...` | `as` 断言 |
| `actions.ts` | 69 | `params.sourceType as "exam" \| "homework" \| ...` | `as` 断言 |
| `error-book-item-card.tsx` | 31 | `node as Record<string, unknown>` | `as` 断言 |
| `error-book-detail-dialog.tsx` | 61 | `content as Record<string, unknown>` | `as` 断言 |
| `add-error-book-dialog.tsx` | 48 | `node as Record<string, unknown>` | `as` 断言 |
| `top-wrong-questions.tsx` | 26 | `node as Record<string, unknown>` | `as` 断言 |
| `knowledge-point-weakness-chart.tsx` | 77 | `payload as unknown as {...}` | 双重断言 |
| `chapter-weakness-chart.tsx` | 74 | `payload as unknown as {...}` | 双重断言 |
| `class-error-bar-chart.tsx` | 76 | `payload as unknown as {...}` | 双重断言 |
| `subject-distribution-chart.tsx` | 77 | `payload as unknown as {...}` | 双重断言 |

### 2.4 【P1】data-access.ts 超过 1000 行硬性上限

**项目规则**：「硬性上限：任何文件不超过 1000 行，超过必须拆分」

`data-access.ts` 当前 **1029 行**，超出硬性上限。该文件混合了：
- 学生端 CRUD（`getErrorBookItems`、`createErrorBookItem`、`recordReview` 等）
- 教师/管理员分析查询（`getStudentErrorBookSummaries`、`getKnowledgePointWeakness`、`getChapterWeakness`、`getClassErrorOverviews`、`getSubjectErrorOverviews` 等）
- 跨模块查询接口（`getStudentIdsByClassIdList`、`getAllStudentIds`）

### 2.5 【P1】性能问题：全量查询 + JS 端聚合

| 函数 | 问题 | 影响 |
|------|------|------|
| `getErrorBookStats` | 查询该学生**所有**错题行到内存，再 JS 循环统计 | 学生错题多时内存/CPU 浪费 |
| `getStudentErrorBookSummaries` | 查询所有学生的所有错题行，再 JS 聚合 | 班级学生多时性能差 |
| `getKnowledgePointWeakness` | 查询所有错题行，JS 展开知识点数组再统计 | 同上 |
| `getChapterWeakness` | 同上 | 同上 |
| `getSubjectErrorDistribution` | 同上 | 同上 |
| `getClassErrorOverviews` | 同上 | 同上 |
| `getSubjectErrorOverviews` | 同上 | 同上 |
| `getTopWrongQuestionsByStudentIds` | 同上 | 同上 |
| `admin/page.tsx` | `allStudentIds.slice(0, 500)` 硬编码限制，无分页 | 超过 500 学生时数据不完整 |

**应使用 SQL `GROUP BY` + `COUNT` 聚合查询**，避免全量加载到内存。

### 2.6 【P1】a11y 可访问性缺失

**项目规则**：「可访问性（a11y）：语义化标签、ARIA 属性、键盘导航」

| 位置 | 问题 |
|------|------|
| `grouped-student-error-table.tsx:162` | 使用 `<a href>` 而非 Next.js `<Link>`（违反项目记忆中的 Link 规范） |
| `subject-tabs.tsx` | `<button>` 缺少 `role="tab"` / `aria-selected` / `aria-controls` |
| `class-filter.tsx` | 同上 |
| 所有图表组件 | 缺少 `aria-label` 描述图表内容 |
| `review-buttons.tsx` | 按钮缺少 `aria-label` 描述操作 |
| `grouped-student-error-table.tsx:96` | 可展开行缺少 `aria-expanded` |
| `error-book-detail-dialog.tsx` | `<textarea>` 缺少 `aria-label` |

### 2.7 【P1】错误边界不完整

**项目规则**：「每个独立的数据区块必须用 React Error Boundary 包裹」

| 位置 | 问题 |
|------|------|
| `parent/error-book/page.tsx` | 无 `Suspense` 包裹，整个页面同步渲染 |
| 所有页面 | 仅页面级 `error.tsx`，各数据区块（统计卡片/图表/表格）无独立 Error Boundary |
| 图表组件 | recharts 渲染失败时无 fallback |

### 2.8 【P2】组件复用问题

| 问题 | 位置 | 说明 |
|------|------|------|
| `extractQuestionPreview` 函数重复 3 次 | `error-book-item-card.tsx`、`add-error-book-dialog.tsx`、`top-wrong-questions.tsx` | 应提取到 shared 工具函数 |
| `extractQuestionText` 函数重复 | `error-book-detail-dialog.tsx` | 与上面类似但实现不同 |
| `MASTERY_LEVEL_LABELS` 硬编码 | `error-book-item-card.tsx:47` | 应使用 i18n |
| `QUESTION_TYPE_LABEL` 硬编码 | `top-wrong-questions.tsx:35` | 应使用 i18n |
| `class-error-overview.tsx` 导出 `StudentErrorTable` | 似乎已被 `GroupedStudentErrorTable` 取代 | 死代码 |
| `COMMON_ERROR_TAGS` 硬编码中文 | `types.ts:55` | 应使用 i18n 键 |

### 2.9 【P2】数据服务未抽象（不可测试）

**项目规则**：「可测试性：数据获取、计算、格式化等纯逻辑全部放入纯函数或 hooks，与 UI 分离」

当前组件直接 import `actions` 和 `data-access`：
- `error-book-detail-dialog.tsx` 直接 import `archiveErrorBookItemAction`、`deleteErrorBookItemAction`、`updateErrorBookNoteAction`
- `add-error-book-dialog.tsx` 直接 import `createErrorBookItemAction`
- `review-buttons.tsx` 直接 import `reviewErrorBookItemAction`

**无法在不启动整个应用的情况下 mock 这些依赖**，违反可测试性原则。

### 2.10 【P2】权限校验位置不统一

`getAllStudentIds()` 在 data-access 层通过 `roles.name === "student"` 查询，虽然不在前端，但角色名字符串硬编码在查询中。应使用 `shared/types/permissions` 中的角色常量。

---

## 三、行业差距对比

### 3.1 与优秀 K12 产品的差距

| 功能 | 我们 | 智学网 | 猿题库 | 钉钉教育 | 差距影响 |
|------|------|--------|--------|---------|---------|
| 智能复习队列 | ✅ SM-2 | ✅ | ✅ | ❌ | 基本持平 |
| 复习提醒通知 | ❌ | ✅ 推送 | ✅ 推送 | ✅ | 学生不知道何时复习 |
| 错题趋势图 | ❌（类型已定义未实现） | ✅ | ✅ | ❌ | 无法看到进步趋势 |
| 导出/打印错题 | ❌ | ✅ PDF | ✅ PDF | ❌ | 无法离线复习 |
| 批量操作 | ❌ | ✅ | ✅ | ❌ | 管理大量错题效率低 |
| 班级平均对比 | ❌ | ✅ | ✅ | ❌ | 学生不知道自己水平 |
| 复习日历视图 | ❌ | ✅ | ✅ | ❌ | 无法直观看到复习安排 |
| 错题来源详情跳转 | ❌ | ✅ | ✅ | ❌ | 无法回看原试卷/作业 |
| 知识点掌握度雷达图 | ❌ | ✅ | ✅ | ❌ | 无法多维度看薄弱点 |
| 游戏化激励（连续复习天数） | ❌ | ✅ | ✅ | ❌ | 学生缺乏复习动力 |
| 智能推题（基于错题变式） | ✅（已接入 adaptive-practice） | ✅ | ✅ | ❌ | 基本持平 |

### 3.2 UI/UX 差距

| 差距 | 说明 | 影响角色 |
|------|------|---------|
| 学生端缺少复习仪表盘 | 当前只有列表+筛选，无"今日待复习"独立视图 | 学生 |
| 教师端缺少学生个体下钻 | 点击学生只能跳转带参数，无学生错题详情面板 | 教师 |
| 家长端无子女切换 | 多子女时用卡片展示，无 Tab 切换对比 | 家长 |
| 管理员端无年级维度 | 只有全校维度，无年级/班级下钻 | 管理员 |
| 无骨架屏一致性 | 各页面 loading.tsx 结构不一致 | 全部 |

---

## 四、改进优先级建议

### P0（紧急，影响架构合规与安全）

| 编号 | 问题 | 改进方向 |
|------|------|---------|
| P0-1 | 跨模块直接依赖 | 将 `AiErrorBookAnalysis`、`createPracticeSessionAction`、`getQuestionsAction` 改为通过 props/Context 注入，error-book 模块不直接 import 其他业务模块 |
| P0-2 | i18n 硬编码（150+ 处） | 全部提取为翻译键，扩展 `error-book.json` 翻译文件 |
| P0-3 | 类型安全（18 处 as 断言） | 使用类型守卫替代 `as`，图表 tooltip 使用泛型组件 |

### P1（重要，影响性能与可访问性）

| 编号 | 问题 | 改进方向 |
|------|------|---------|
| P1-1 | data-access.ts 超 1000 行 | 拆分为 `data-access.ts`（学生 CRUD）+ `data-access-analytics.ts`（教师/管理员分析） |
| P1-2 | 全量查询 + JS 聚合 | 改用 SQL `GROUP BY` + `COUNT` 聚合 |
| P1-3 | a11y 缺失 | 添加 ARIA 属性、语义化标签、`<Link>` 替代 `<a>` |
| P1-4 | 错误边界不完整 | 为各数据区块添加 Error Boundary |
| P1-5 | admin 无分页 | 实现分页查询或虚拟滚动 |

### P2（优化，提升可维护性与用户体验）

| 编号 | 问题 | 改进方向 |
|------|------|---------|
| P2-1 | 重复函数 | 提取 `extractQuestionPreview` 到 `shared/lib/question-content.ts`（已存在） |
| P2-2 | 数据服务未抽象 | 定义 `ErrorBookService` 接口，通过 Context 注入 |
| P2-3 | 死代码 | 删除 `class-error-overview.tsx` 中未使用的 `StudentErrorTable` |
| P2-4 | 缺失功能 | 错题趋势图、复习提醒、导出、批量操作（中长期） |
| P2-5 | 角色字符串硬编码 | `getAllStudentIds` 使用角色常量 |

---

## 五、架构图同步说明

### 5.1 需要修改的节点

1. **`005_architecture_data.json` → `error-book.uses.shared`**：
   - 移除 `db.schema.examSubmissions`、`db.schema.submissionAnswers`、`db.schema.homeworkSubmissions`、`db.schema.homeworkAnswers`、`db.schema.examQuestions`、`db.schema.homeworkAssignmentQuestions`（这些已通过跨模块 data-access 访问）

2. **`005_architecture_data.json` → `error-book.dependsOn`**：
   - 新增 `ai`（error-book-detail-dialog 直接依赖 ai 组件）
   - 新增 `adaptive-practice`（error-book-detail-dialog 直接依赖其 Action）
   - 新增 `questions`（add-error-book-dialog 直接依赖其 Action）—— 注意：questions 已在 dependsOn 中，但 uses 中记录的是 `actions.getQuestionsAction` 而非 data-access

3. **`004_architecture_impact_map.md` 第 2.28 节**：
   - 文件清单中 `data-access.ts` 行数更新为拆分后的两个文件
   - 依赖关系新增 ai / adaptive-practice 的直接依赖说明（标注为"待解耦"）

### 5.2 架构图待补充项

- 拆分后的 `data-access-analytics.ts` 文件信息
- `ErrorBookService` 接口定义（如实施 P2-2）
- i18n 翻译文件结构更新