# 成绩与诊断模块易用性审计报告 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 项，记录备查。