NextEdu/docs/architecture/audit/exam-homework-audit-report-v3.md

# 考试/作业模块审计报告 v3

> 基于 v2 审计报告的深度用户体验审计与同类产品对标分析
> 生成时间：2026-06-22
> 审计范围：`src/modules/exams/`、`src/modules/homework/`、`src/modules/proctoring/`、`src/modules/parent/`（考试相关）、`src/shared/`（考试/作业相关共享层）

---

## 1. v2 遗留项验证

### 1.1 遗留项状态

| 编号 | v2 描述 | v3 验证结果 |
|------|---------|-------------|
| L-1 | ExamHomeworkServicePort 已定义但未注册实现 | ❌ `registerExamHomeworkService` 全项目零调用，`instrumentation.ts` 不存在 |
| L-2 | trackExamEvent 已定义但未在 actions 中调用 | ❌ `trackExamEvent` 全项目零调用，3 个目标文件均未导入 |
| L-3 | useExamHomeworkFeatures hook 已创建但未在页面中使用 | ❌ hook 全项目零使用，app/ 与 modules/ 下无任何引用 |
| L-4 | ai-pipeline/structure.ts 仍有 ~300 行 | ✅ 已降至 209 行（低于 800 行建议值） |
| L-5 | 预存 TypeScript 错误（7 个） | ❌ 实际为 22 个，其中 8 个在 homework 模块（`data-access.ts`/`stats-service.ts` 的 `db.select().from().where()` 返回数组但代码直接访问 `.c` 属性） |

### 1.2 新发现的预存 TypeScript 错误

**位置**：`src/modules/homework/data-access.ts` 第 489-492 行、`src/modules/homework/stats-service.ts` 第 236-239 行

**根因**：`db.select({ c: count() }).from(table).where(condition)` 返回 `{ c: number }[]` 数组，但代码直接访问 `targetsRow?.c`，应为 `targetsRow[0]?.c`。

---

## 2. 用户体验深度分析（对标同类产品）

### 2.1 对标产品矩阵

| 功能维度 | 智学网 | 猿题库 | Google Classroom | Canvas LMS | 当前实现 |
|---------|--------|--------|------------------|------------|---------|
| 即时自动批改 | ✅ 提交即出分 | ✅ 提交即出分 | ❌ 需教师批改 | ✅ 可配置 | ❌ 仅在批改页计算，不回写 |
| 批量批改 | ✅ 多选+批量打分 | ❌ 逐题批改 | ❌ 无 | ✅ 批量打分 | ❌ 仅支持逐份批改 |
| 考试分析 | ✅ 难度/区分度/知识点 | ✅ 错题统计 | ❌ 基础统计 | ✅ 完整分析 | ❌ 作业有分析，考试无分析 |
| 多选题部分分 | ✅ 漏选得部分分 | ✅ 按选项计分 | ❌ 全对才得分 | ✅ 可配置 | ❌ 全对才得分 |
| 提交后反馈 | ✅ 即时显示分数+错题 | ✅ 即时显示 | ❌ 等待教师 | ✅ 即时显示 | ❌ 提交后跳转列表，无反馈 |
| 错题本 | ✅ 自动归集 | ✅ 自动归集 | ❌ 无 | ✅ 可导出 | ❌ 无错题本 |
| 家长视图 | ✅ 考试详情+趋势 | N/A | ❌ 无 | ✅ 观察员模式 | ❌ 仅作业摘要，无考试详情 |
| 移动端适配 | ✅ 原生 App | ✅ 原生 App | ✅ 响应式 | ✅ 响应式 | ⚠️ 响应式但触控未优化 |

### 2.2 关键 UX 缺陷分析

#### UX-1: 即时自动批改回写（P0 优先级）

**当前流程**：
1. 学生提交作业 → `submitHomeworkAction` → `markHomeworkSubmitted` → 跳转列表页
2. 教师打开批改页 → `applyAutoGrades` 在客户端计算 → 教师手动点击"提交成绩"

**问题**：
- 学生提交后看不到即时成绩，体验割裂
- 自动批改结果仅存在教师浏览器内存中，未回写 DB
- 若教师不打开批改页，选择题/判断题永远不会有分数

**同类产品做法**：智学网/猿题库在学生提交瞬间服务端自动批改选择题/判断题，学生立即看到客观题分数，主观题等待教师批改。

**改进方案**：在 `markHomeworkSubmitted` 中调用 `applyAutoGrades` 并回写 DB，将 submission 状态设为 `graded`（若全部可自动判分）或 `submitted`（若含主观题）。

#### UX-2: 批量批改 UI（P1 优先级）

**当前**：`homework/assignments/[id]/submissions` 页面仅展示提交列表，教师需逐份点击进入批改页。

**同类产品**：智学网支持列表页勾选多份提交，批量设置分数（全对/全错/自定义）。

**改进方案**：提交列表页增加多选 checkbox + 批量操作工具栏（批量自动批改、批量设置分数）。

#### UX-3: 考试分析仪表盘（P1 优先级）

**当前**：`homework/stats-service.ts` 有作业分析（`getHomeworkAssignmentAnalytics`），但考试无分析。

**同类产品**：智学网考试后展示题目难度、区分度、知识点掌握度、班级对比。

**改进方案**：新增 `exams/components/exam-analytics-dashboard.tsx`，复用 homework stats-service 模式，基于考试关联的作业提交数据计算分析。

#### UX-4: 多选题部分分自动判分（P1 优先级）

**当前**：`computeIsCorrect` 对多选题采用"全对才得分"策略（`studentSet.size !== correctSet.size` 直接返回 false）。

**同类产品**：智学网/猿题库支持"漏选得部分分"（每个正确选项得分，错误选项扣分）。

**改进方案**：`applyAutoGrades` 增加部分分计算策略，按正确选项比例给分。

#### UX-5: 提交后即时反馈页（P2 优先级）

**当前**：学生提交后跳转到 `/student/learning/assignments` 列表页，无任何反馈。

**同类产品**：智学网/猿题库提交后显示成绩页（分数、对错分布、错题预览）。

**改进方案**：提交后跳转到 `/student/learning/assignments/[assignmentId]/result` 页面，展示分数+对错分布+错题预览。

#### UX-6: 错题本（P2 优先级）

**当前**：无错题本功能，学生无法回顾历史错题。

**同类产品**：智学网/猿题库自动归集错题，支持按科目/时间筛选。

**改进方案**：新增 `student/wrong-answers` 页面，聚合所有已批改作业中的错题。

#### UX-7: 家长考试详情视图（P2 优先级）

**当前**：`parent` 模块仅有 `ChildHomeworkSummary`（作业摘要），无考试详情。

**同类产品**：智学网家长端可查看孩子考试详情、错题、成绩趋势。

**改进方案**：新增 `parent/components/child-exam-detail.tsx`，展示孩子考试详情+成绩趋势。

#### UX-8: 移动端触控优化（P3 优先级）

**当前**：题目导航按钮 `h-8 w-8`（32px），低于 Apple HIG 建议的 44px 最小触控目标。

**改进方案**：移动端按钮尺寸调整为 `h-10 w-10 sm:h-8 sm:w-8`。

---

## 3. v3 改进计划

### 3.1 P0 优先级（核心体验）

| 编号 | 改进项 | 实现方案 |
|------|--------|---------|
| V3-1 | 修复预存 TypeScript 错误 | `data-access.ts`/`stats-service.ts` 的 `db.select()` 结果加 `[0]` 索引 |
| V3-2 | 即时自动批改回写 | `markHomeworkSubmitted` 中调用 `applyAutoGrades` 并回写 DB |
| V3-3 | 注册 ExamHomeworkServicePort 实现 | 新建 `src/instrumentation.ts`，注册真实实现 |
| V3-4 | trackExamEvent 埋点接入 | 在 `createExamAction`/`submitHomeworkAction` 等 8 个关键 action 中调用 |
| V3-5 | useExamHomeworkFeatures hook 接入 | 在 `exam-actions.tsx`/`homework-take-view.tsx` 中使用 |

### 3.2 P1 优先级（重要体验）

| 编号 | 改进项 | 实现方案 |
|------|--------|---------|
| V3-6 | 多选题部分分自动判分 | `applyAutoGrades` 增加部分分计算策略 |
| V3-7 | 批量批改 UI | 提交列表页增加多选+批量操作工具栏 |
| V3-8 | 考试分析仪表盘 | 新增 `exam-analytics-dashboard.tsx` 组件+data-access |

### 3.3 P2 优先级（增强体验）

| 编号 | 改进项 | 实现方案 |
|------|--------|---------|
| V3-9 | 提交后即时反馈页 | 新增 result 页面，展示分数+对错分布 |
| V3-10 | 错题本 | 新增 `student/wrong-answers` 页面 |
| V3-11 | 家长考试详情视图 | 新增 `child-exam-detail.tsx` 组件 |

### 3.4 P3 优先级（细节优化）

| 编号 | 改进项 | 实现方案 |
|------|--------|---------|
| V3-12 | 移动端触控优化 | 题目导航按钮尺寸调整为 44px 最小触控目标 |

---

## 4. 实施顺序

1. V3-1: 修复预存 TypeScript 错误（阻塞后续）
2. V3-2: 即时自动批改回写（核心体验）
3. V3-6: 多选题部分分自动判分（与 V3-2 协同）
4. V3-3: 注册 ExamHomeworkServicePort 实现
5. V3-4: trackExamEvent 埋点接入
6. V3-5: useExamHomeworkFeatures hook 接入
7. V3-7: 批量批改 UI
8. V3-8: 考试分析仪表盘
9. V3-9: 提交后即时反馈页
10. V3-10: 错题本
11. V3-11: 家长考试详情视图
12. V3-12: 移动端触控优化

---

## 5. 预期收益

| 维度 | 改进前 | 改进后 |
|------|--------|--------|
| 学生提交后反馈延迟 | 等待教师批改（小时-天） | 客观题即时（秒级） |
| 教师批改效率 | 逐份手动 | 批量+自动批改 |
| 考试后分析 | 无 | 完整分析仪表盘 |
| 多选题评分精度 | 全对才得分 | 按选项比例得分 |
| 家长了解孩子考试 | 无 | 考试详情+趋势 |
| TypeScript 错误数 | 22 | 0（考试/作业模块） |
| 死代码（已定义未使用） | 3 处 | 0 处 |