27db170c0a
- Update architecture impact map, data, feature checklist, gap audit - Add audit reports for dashboard, exam-homework, grades-diagnostic, settings-profile, textbooks - Update bug reports (admin, teacher, lesson-preparation, others, shared) - Update coding standards, DR plan, design docs, and README
8.8 KiB
考试/作业模块审计报告 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 优先级）
当前流程：
- 学生提交作业 →
submitHomeworkAction→markHomeworkSubmitted→ 跳转列表页 - 教师打开批改页 →
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. 实施顺序
- V3-1: 修复预存 TypeScript 错误（阻塞后续）
- V3-2: 即时自动批改回写（核心体验）
- V3-6: 多选题部分分自动判分（与 V3-2 协同）
- V3-3: 注册 ExamHomeworkServicePort 实现
- V3-4: trackExamEvent 埋点接入
- V3-5: useExamHomeworkFeatures hook 接入
- V3-7: 批量批改 UI
- V3-8: 考试分析仪表盘
- V3-9: 提交后即时反馈页
- V3-10: 错题本
- V3-11: 家长考试详情视图
- V3-12: 移动端触控优化
5. 预期收益
| 维度 | 改进前 | 改进后 |
|---|---|---|
| 学生提交后反馈延迟 | 等待教师批改（小时-天） | 客观题即时（秒级） |
| 教师批改效率 | 逐份手动 | 批量+自动批改 |
| 考试后分析 | 无 | 完整分析仪表盘 |
| 多选题评分精度 | 全对才得分 | 按选项比例得分 |
| 家长了解孩子考试 | 无 | 考试详情+趋势 |
| TypeScript 错误数 | 22 | 0（考试/作业模块） |
| 死代码（已定义未使用） | 3 处 | 0 处 |