xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
1f833097e27ec6e5b018f0d86adb4654acf14318
NextEdu/docs/architecture/audit/grades-diagnostic-audit-report-v4.md
SpecialX 27db170c0a 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

241 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 成绩与诊断模块易用性审计报告 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 项，记录备查。
Reference in New Issue View Git Blame Copy Permalink