docs: update architecture docs, audit reports, and bug tracking

- 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
2026-06-23 17:36:18 +08:00
parent 5195a4bcf1
commit 27db170c0a
21 changed files with 5104 additions and 332 deletions
--- a/docs/architecture/audit/grades-diagnostic-audit-report-v4.md
+++ b/docs/architecture/audit/grades-diagnostic-audit-report-v4.md
@@ -0,0 +1,240 @@
+# 成绩与诊断模块易用性审计报告 v4
+
+> **审计日期**：2026-06-23
+> **审计范围**：成绩模块（grades）+ 诊断模块（diagnostic）
+> **对标系统**：PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb、Google Classroom、Canvas、超星学习通、ClassIn
+> **前置文档**：[v3 审计报告](./grades-diagnostic-audit-report-v3.md)（5 P1 + 10 P2 已全部完成）
+
+---
+
+## 一、v3 完成确认
+
+v3 审计报告中 **5 个 P1 + 10 个 P2 改进项全部已实现并验证通过**（tsc + lint 通过，架构文档已同步）。
+
+---
+
+## 二、v4 新增易用性问题（深度分析）
+
+本轮分析从 12 个维度对成绩和诊断模块进行了深度审查，对比 10 个同类 K12 系统，共发现 **48 个易用性问题**（成绩模块 24 项 + 诊断模块 24 项）。
+
+### 严重程度分布
+
+| 严重程度 | 成绩模块 | 诊断模块 | 合计 | 本次实施 |
+|---------|---------|---------|------|---------|
+| P1（核心缺陷） | 12 | 12 | 24 | 12 项 |
+| P2（易用性增强） | 22 | 20 | 42 | 0 项（下迭代） |
+| P3（长期优化） | 2 | 7 | 9 | 0 项（记录备查） |
+
+### 本次实施范围
+
+聚焦 P1 中影响**数据安全、通知机制、基础可读性、移动端可用性**的 12 项改进。
+
+---
+
+## 三、P1 改进项详情（本次实施）
+
+### 数据安全修复（诊断模块，3 项）
+
+#### v4-P1-1 getDiagnosticReports 无 dataScope 过滤（数据泄露）
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [data-access-reports.ts](file:///e:/Desktop/CICD/src/modules/diagnostic/data-access-reports.ts) L115-147 |
+| 问题 | `getDiagnosticReports` 接收 filters 但无 dataScope 参数，教师调用时返回全校所有报告 |
+| 对比 | PowerSchool、Infinite Campus 严格按教师所教班级过滤 |
+| 改进 | 增加 dataScope 参数，教师仅返回所教班级学生报告 |
+
+#### v4-P1-2 教师学生诊断页未校验师生关系
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [teacher/diagnostic/student/[studentId]/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/teacher/diagnostic/student/[studentId]/page.tsx) L24-32 |
+| 问题 | 仅校验 class_members 和 children，未校验 class_taught，教师可通过 URL 查看任意学生 |
+| 对比 | PowerSchool、Infinite Campus 严格校验师生关系 |
+| 改进 | 增加 class_taught 校验，查询 studentId 是否属于教师所教班级 |
+
+#### v4-P1-3 学生可见草稿报告（发布流程缺陷）
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [student/diagnostic/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/student/diagnostic/page.tsx) L13-16 |
+| 问题 | 学生/家长调用 getDiagnosticReports 未传 status 过滤，且组件回退到 reports[0]（可能是草稿） |
+| 对比 | 所有对标系统严格区分草稿/已发布 |
+| 改进 | 学生/家长页面传 status: "published"，移除组件回退逻辑 |
+
+### 通知机制修复（3 项）
+
+#### v4-P1-4 班级报告发布不通知学生
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [actions.ts](file:///e:/Desktop/CICD/src/modules/diagnostic/actions.ts) L96-109 |
+| 问题 | publishReportAction 仅当 studentId 非空时通知，班级报告 studentId=null 全班不通知 |
+| 对比 | 所有对标系统班级报告发布均通知全班 |
+| 改进 | learningDiagnosticReports 表新增 classId 字段，班级报告发布时查询全班学生批量通知 |
+
+#### v4-P1-5 家长未收到子女报告发布通知
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [actions.ts](file:///e:/Desktop/CICD/src/modules/diagnostic/actions.ts) L102-108 |
+| 问题 | createNotification 仅通知学生本人，未查询 parent_student_relations 通知家长 |
+| 对比 | PowerSchool、Infinite Campus、超星学习通同步通知家长 |
+| 改进 | 发布通知时查询家长 userId 列表，批量发送通知 |
+
+#### v4-P1-6 成绩录入无通知机制
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [actions.ts](file:///e:/Desktop/CICD/src/modules/grades/actions.ts) L82-130 |
+| 问题 | createGradeRecordAction 和 batchCreateGradeRecordsAction 录入后仅 revalidatePath，不触发通知 |
+| 对比 | PowerSchool、Canvas、超星学习通成绩发布自动通知学生和家长 |
+| 改进 | 录入成功后调用通知模块，通知学生本人和家长 |
+
+### 可读性修复（3 项）
+
+#### v4-P1-7 成绩列表缺少颜色编码
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [grade-record-list.tsx](file:///e:/Desktop/CICD/src/modules/grades/components/grade-record-list.tsx) L161-163 |
+| 问题 | 分数展示为纯文本，不及格不标红，优秀不标绿 |
+| 对比 | PowerSchool、Canvas、超星学习通均按区间着色 |
+| 改进 | 新增 ScoreCell 组件，根据得分率着色（红<60%/黄60-84%/绿≥85%） |
+
+#### v4-P1-8 热力图缺少颜色图例
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [class-diagnostic-view.tsx](file:///e:/Desktop/CICD/src/modules/diagnostic/components/class-diagnostic-view.tsx) L166-206 |
+| 问题 | 热力图渲染了色块但无图例说明颜色含义 |
+| 对比 | PowerSchool、Infinite Campus、Alma 热力图均带图例 |
+| 改进 | 热力图卡片底部增加图例条 |
+
+#### v4-P1-9 家长页静默丢弃查询失败的子女
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [parent/diagnostic/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/parent/diagnostic/page.tsx) L31-48 |
+| 问题 | Promise.allSettled rejected 状态被静默丢弃，家长不知有子女数据加载失败 |
+| 对比 | PowerSchool、Infinite Campus 显示错误提示并允许重试 |
+| 改进 | 保留 rejected 项，渲染错误卡片提供重试按钮 |
+
+### 移动端修复（2 项）
+
+#### v4-P1-10 成绩列表表格移动端溢出
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [grade-record-list.tsx](file:///e:/Desktop/CICD/src/modules/grades/components/grade-record-list.tsx) L138-196 |
+| 问题 | 10 列表格无水平滚动容器，手机端溢出 |
+| 对比 | PowerSchool、Infinite Campus 移动端表格可横向滚动 |
+| 改进 | 表格容器添加 overflow-x-auto |
+
+#### v4-P1-11 诊断模块表格移动端溢出
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [class-diagnostic-view.tsx](file:///e:/Desktop/CICD/src/modules/diagnostic/components/class-diagnostic-view.tsx) L242-376 |
+| 问题 | 多个表格无 overflow-x-auto 包裹，手机端溢出 |
+| 对比 | 所有对标系统移动端表格可横向滚动 |
+| 改进 | 所有 Table 外层包裹 overflow-x-auto |
+
+### 家长端导出修复（1 项）
+
+#### v4-P1-12 家长端导出按钮为占位实现
+
+| 项 | 内容 |
+|----|------|
+| 位置 | [parent-export-button.tsx](file:///e:/Desktop/CICD/src/modules/parent/components/parent-export-button.tsx) L25-31 |
+| 问题 | handleExport 仅 setTimeout 后 toast "coming soon"，无实际导出 |
+| 对比 | PowerSchool、Infinite Campus 家长端完整导出功能 |
+| 改进 | 接入 exportGradesAction，支持按 studentId 导出 |
+
+---
+
+## 四、P2 改进项（下迭代规划，本次不实施）
+
+成绩模块 22 项 + 诊断模块 20 项，共 42 项 P2 易用性增强，记录备查。
+
+### 成绩模块 P2 代表性问题
+
+- v4-P2-1 MAX_SCORE 硬编码与 fullScore 不一致
+- v4-P2-2 缺少自动计算与智能填充
+- v4-P2-3 成绩表格不支持列排序
+- v4-P2-4 班级排名缺少进步/退步趋势标识
+- v4-P2-5 趋势图缺少交互式钻取
+- v4-P2-6 缺少科目相关性分析
+- v4-P2-7 缺少成绩发布状态控制
+- v4-P2-8 grade_managed scope 校验过于宽松
+- v4-P2-9 历史成绩访问无时间窗口限制
+- v4-P2-10 缺少 CSV 导出与打印友好视图
+
+### 诊断模块 P2 代表性问题
+
+- v4-P2-1 报告内容硬编码无模板系统
+- v4-P2-2 雷达图截断知识点名称无 tooltip
+- v4-P2-3 无学生×知识点掌握度矩阵
+- v4-P2-4 无掌握度趋势/历史分析
+- v4-P2-5 无预测性分析（at-risk 预警）
+- v4-P2-6 无掌握度下降预警
+- v4-P2-7 通知类型使用 "grade" 而非专用类型
+- v4-P2-8 grade_managed 范围未处理
+- v4-P2-9 导出 action 未校验报告归属
+- v4-P2-10 无 PDF 导出
+
+---
+
+## 五、P3 长期改进（记录备查）
+
+成绩模块 2 项 + 诊断模块 7 项，共 9 项长期优化。
+
+### 代表性问题
+- v4-P3-1 成绩录入无语音输入
+- v4-P3-2 缺少成绩录入指引与新手引导
+- v4-P3-3 无定时/自动化报告生成
+- v4-P3-4 色盲用户友好性不足
+- v4-P3-5 无知识点前置依赖图
+- v4-P3-6 雷达图键盘不可达
+- v4-P3-7 无数据置信度指示
+
+---
+
+## 六、实施计划
+
+实施顺序：
+1. 数据安全修复（v4-P1-1 ~ v4-P1-3）— 最高优先级
+2. 通知机制修复（v4-P1-4 ~ v4-P1-6）
+3. 可读性修复（v4-P1-7 ~ v4-P1-9）
+4. 移动端修复（v4-P1-10 ~ v4-P1-11）
+5. 家长端导出修复（v4-P1-12）
+6. 验证：lint + tsc + 架构文档同步
+
+---
+
+## 七、实施状态跟踪
+
+### P1（本次实施）
+
+| # | 问题 | 改进方向 | 状态 |
+|---|------|----------|------|
+| v4-P1-1 | getDiagnosticReports 无 dataScope 过滤 | 增加 dataScope 参数 | ✅ 已完成 |
+| v4-P1-2 | 教师学生诊断页未校验师生关系 | 增加 class_taught 校验 | ✅ 已完成 |
+| v4-P1-3 | 学生可见草稿报告 | 传 status: "published" | ✅ 已完成 |
+| v4-P1-4 | 班级报告发布不通知学生 | 新增 classId 字段 + 批量通知 | ✅ 已完成 |
+| v4-P1-5 | 家长未收到报告发布通知 | 查询家长 userId 批量通知 | ✅ 已完成 |
+| v4-P1-6 | 成绩录入无通知机制 | 录入后通知学生和家长 | ✅ 已完成 |
+| v4-P1-7 | 成绩列表缺少颜色编码 | 新增 ScoreCell 组件 | ✅ 已完成 |
+| v4-P1-8 | 热力图缺少颜色图例 | 增加图例条 | ✅ 已完成 |
+| v4-P1-9 | 家长页静默丢弃查询失败 | 渲染错误卡片 | ✅ 已完成 |
+| v4-P1-10 | 成绩列表表格移动端溢出 | 添加 overflow-x-auto | ✅ 已完成 |
+| v4-P1-11 | 诊断模块表格移动端溢出 | 添加 overflow-x-auto | ✅ 已完成 |
+| v4-P1-12 | 家长端导出按钮占位 | 接入 exportGradesAction | ✅ 已完成 |
+
+### P2（下迭代规划）
+
+成绩模块 22 项 + 诊断模块 20 项，共 42 项，本次不实施。
+
+### P3（长期，本次不实施）
+
+成绩模块 2 项 + 诊断模块 7 项，共 9 项，记录备查。