NextEdu/docs/architecture/audit/grades-diagnostic-audit-report-v3.md

成绩和学情诊断模块易用性审计报告 v3

审查日期：2026-06-23 审查范围：在 v1/v2 审计完成后，从用户视角对 src/modules/grades/**、src/modules/diagnostic/**、相关路由层进行易用性深度审计 审查目的：对比同类型 K12 系统（PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb），发现功能易用性差距并实现改进 审查方法：逐文件分析 44 个源文件，从教师/学生/家长/管理员四种角色视角评估每个功能的易用性

---

一、v2 完成情况确认

v2 审计报告所有 P1（9 项）和 P2（10 项）改进项均已真实落地：

v2 编号	改进项	验证结果
v2-P1-1	WidgetBoundary 应用	✅ 3 个页面已应用
v2-P1-2	admin/school/grades/insights loading/error	✅ 已补齐
v2-P1-3	架构 JSON 005 权限记录	✅ 已修正为 school:manage
v2-P1-4	i18n 接入	✅ 21 个组件全部接入 useTranslations
v2-P1-5	exportGradesAction 安全漏洞	✅ 已传递 currentUserId 和 dataScope
v2-P1-6	diagnostic stats-service.ts	✅ 已抽取（352 行，12 个纯函数）
v2-P1-7	热力图色块 a11y	✅ 已添加 role="img" + aria-label
v2-P1-8	getKnowledgePointStats 无参调用	✅ 已修复
v2-P1-9	updateMasteryFromSubmission 覆盖逻辑	✅ 已改为累积模式
v2-P2-1 ~ P2-10	10 项 P2 改进	✅ 全部完成

---

二、同类 K12 系统易用性对比

2.1 成绩录入功能对比

功能	PowerSchool	Infinite Campus	Skyward	Alma	Gradelink	RenWeb	本系统（v2）
单条录入	✅	✅	✅	✅	✅	✅	✅
批量录入	✅	✅	✅	✅	✅	✅	✅
Excel 粘贴	✅	✅	✅	❌	✅	❌	❌
行内编辑	✅	✅	✅	✅	❌	✅	❌
撤销功能	❌	✅	❌	❌	❌	❌	❌
草稿自动保存	✅	✅	✅	✅	❌	✅	✅（localStorage）
键盘导航	✅	✅	✅	❌	❌	❌	✅（Enter 跳转）
实时统计	❌	✅	❌	❌	✅	❌	✅

2.2 成绩查询功能对比

功能	PowerSchool	Infinite Campus	Skyward	Alma	Gradelink	RenWeb	本系统（v2）
学生成绩列表	✅	✅	✅	✅	✅	✅	✅
编辑入口	✅	✅	✅	✅	✅	✅	❌（仅删除）
成绩趋势图	✅	✅	✅	✅	❌	❌	✅
排名显示	✅	✅	✅	✅	✅	✅	❌（硬编码 0）
排名趋势	✅	❌	❌	❌	❌	❌	❌（Action 已实现未调用）
班级平均对比	✅	✅	✅	✅	❌	❌	❌
导出 Excel	✅	✅	✅	✅	✅	✅	✅

2.3 学情诊断功能对比

功能	PowerSchool	Infinite Campus	Skyward	Alma	Gradelink	RenWeb	本系统（v2）
知识点掌握度	✅	✅	❌	✅	❌	❌	✅
强弱项分析	✅	✅	❌	✅	❌	❌	✅
班级诊断	✅	✅	❌	✅	❌	❌	✅
报告发布通知	✅	✅	✅	✅	✅	✅	❌
弱项练习推荐	✅	❌	❌	✅	❌	❌	❌
报告导出	✅	✅	✅	✅	✅	✅	❌
按知识点筛选学生	✅	✅	❌	❌	❌	❌	❌

2.4 关键差距总结

对比同类系统，本系统在以下方面存在明显差距：

1. 成绩列表无编辑入口：所有同类系统都支持在列表中直接编辑成绩，本系统仅有删除
2. 不支持 Excel 粘贴：PowerSchool/Infinite Campus/Skyward/Gradelink 都支持从 Excel 粘贴成绩，大幅提升录入效率
3. 学生排名硬编码为 0：所有同类系统都显示班级排名，本系统虽有 getClassRanking 函数但 getStudentGradeSummary 返回 rank: 0
4. 排名趋势图未接入：getRankingTrendAction 已实现但学生页面未调用，浪费已有功能
5. 诊断报告发布无通知：所有同类系统在报告发布时都会通知学生/家长，本系统仅更新状态
6. 成绩录入不触发诊断更新：成绩变化应反映到掌握度，本系统仅 exam submission 触发
7. 无撤销功能：Infinite Campus 支持撤销批量录入，本系统无此功能
8. 无报告导出：所有同类系统都支持导出诊断报告，本系统无此功能

---

三、v3 新发现问题

3.1 P1 严重易用性问题

v3-P1-1 成绩列表无编辑入口

位置	问题	影响
grade-record-list.tsx L102-112	仅有删除按钮，无编辑按钮	教师录错成绩后只能删除重录，效率极低
actions.ts L156-188	updateGradeRecordAction 已实现但前端从未调用	已有功能浪费

同类系统对比：PowerSchool、Infinite Campus、Skyward、Alma、RenWeb 全部支持列表内编辑成绩。

用户痛点：教师录入 50 人成绩后发现某项分数录错，当前流程是"删除→重新打开录入页→重新填写全部字段→保存"，至少 5 步操作；同类系统仅需"点击编辑→修改分数→保存"2 步。

改进方向：在 grade-record-list.tsx 增加编辑按钮，弹出 Dialog 复用 GradeRecordForm 的字段（标题、分数、满分、类型、学期、备注），调用 updateGradeRecordAction。

v3-P1-2 批量录入不支持 Excel 粘贴

位置	问题	影响
batch-grade-entry.tsx L119-123	handleScoreChange 只接受单值输入，无 paste 事件处理	教师无法从 Excel 粘贴一列成绩

同类系统对比：PowerSchool、Infinite Campus、Skyward、Gradelink 都支持从 Excel 复制一列分数粘贴到批量录入表格。

用户痛点：教师常在 Excel 中整理好成绩（如按学号排序的分数列），当前需要逐个手动输入 50 人分数；同类系统支持复制 Excel 一列→粘贴到第一个输入框→自动填充所有学生。

改进方向：在分数输入框添加 onPaste 处理器，解析剪贴板文本（按行/Tab 分割），按学生顺序自动填充。

v3-P1-3 学生排名硬编码为 0 且排名趋势图未接入

位置	问题	影响
data-access.ts L351	getStudentGradeSummary 返回 rank: 0 硬编码	学生看不到自己的班级排名
student/grades/page.tsx	未调用 getRankingTrendAction	排名趋势图功能浪费

同类系统对比：PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb 全部显示学生班级排名。

用户痛点：学生/家长查看成绩时最关心"班级第几名"，当前页面只显示平均分和记录列表，无法回答"孩子排第几"这个核心问题。

改进方向：

1. getStudentGradeSummary 调用 getClassRanking 计算实际排名
2. 学生页面接入 getRankingTrendAction，显示排名趋势图

v3-P1-4 诊断报告发布无通知机制

位置	问题	影响
diagnostic/actions.ts L78-100	publishReportAction 仅执行 revalidatePath，未触发通知	学生/家长不知道报告已发布

同类系统对比：PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb 全部在报告发布时发送通知。

用户痛点：教师发布诊断报告后，学生/家长需要主动登录查看才知道有新报告，信息传递滞后；同类系统会自动推送站内通知/邮件/短信。

改进方向：publishReportAction 调用 notifications 模块的 createNotification，向学生（个人报告）或全班学生（班级报告）发送站内通知。

v3-P1-5 成绩录入不触发诊断掌握度更新

位置	问题	影响
diagnostic/data-access.ts L64-139	updateMasteryFromSubmission 只从 exam submission 触发	手动录入的成绩不反映到掌握度

同类系统对比：PowerSchool、Infinite Campus、Alma 的成绩变化会自动更新学情分析。

用户痛点：教师手动录入期中考试成绩后，学情诊断页面仍显示旧数据，导致诊断报告与成绩单不一致。

改进方向：在 createGradeRecord 和 batchCreateGradeRecords 后，若成绩关联了 examId，调用 updateMasteryFromSubmission 更新掌握度。

3.2 P2 中等易用性问题

v3-P2-1 学生成绩过滤器科目使用名称而非 ID

位置	问题
student/grades/page.tsx L49	r.subjectName !== subjectFilter 按名称过滤，科目重名时会冲突

改进方向：改为按 subjectId 过滤，GradeFilters 组件的科目选项使用 ID 作为 value。

v3-P2-2 成绩趋势图无班级平均对比线

位置	问题
grade-trend-card.tsx	仅显示学生个人趋势，无班级平均对比

同类系统对比：PowerSchool、Infinite Campus、Skyward、Alma 都支持个人 vs 班级平均对比。

改进方向：GradeTrendCard 接收 classAverageData prop，在趋势图中添加第二条对比线。

v3-P2-3 批量录入无撤销功能

位置	问题
batch-grade-entry.tsx	提交后无法撤销，录错全班成绩需要逐条删除

同类系统对比：Infinite Campus 支持撤销最近一次批量录入。

改进方向：batchCreateGradeRecordsAction 返回创建的记录 ID 列表，前端缓存到 sessionStorage，提供"撤销"按钮调用批量删除。

v3-P2-4 诊断报告无导出功能

位置	问题
diagnostic 模块	无导出功能，教师无法将诊断报告导出为 PDF/Excel

同类系统对比：所有 6 个同类系统都支持导出诊断报告。

改进方向：新增 exportDiagnosticReportAction，导出为 Excel（复用 grades/export.ts 模式）。

v3-P2-5 班级诊断不支持按知识点筛选学生

位置	问题
class-diagnostic-view.tsx	无法按"某知识点掌握度 < 60%"筛选学生列表

同类系统对比：PowerSchool、Infinite Campus 支持按知识点筛选学生。

改进方向：class-diagnostic-view.tsx 增加知识点筛选下拉框，筛选出该知识点掌握度低于阈值的学生。

v3-P2-6 弱项无个性化练习推荐

位置	问题
student-diagnostic-view.tsx	"Practice" 按钮无实际跳转目标

同类系统对比：PowerSchool、Alma 支持基于弱项推荐练习题。

改进方向：student-diagnostic-view.tsx 的"Practice"按钮跳转到题目库，带知识点筛选参数。

v3-P2-7 成绩分析页无学期/考试筛选

位置	问题
teacher/grades/analytics/page.tsx	仅有班级/科目/年级筛选，无学期和考试筛选

改进方向：AnalyticsFilters 增加学期和考试筛选下拉框。

v3-P2-8 家长页面缺失趋势图

位置	问题
src/app/(dashboard)/parent/grades/page.tsx	仅显示成绩列表，无趋势图

改进方向：家长页面复用 GradeTrendCard 显示子女成绩趋势。

v3-P2-9 管理员无全校成绩汇总视图

位置	问题
src/app/(dashboard)/admin/school/grades/insights/page.tsx	仅有单班级分析，无全校汇总

改进方向：新增全校成绩汇总卡片（各年级平均分、及格率、优秀率对比）。

v3-P2-10 批量录入无服务端草稿自动保存

位置	问题
batch-grade-entry.tsx L192-205	草稿仅保存到 localStorage，换设备丢失

改进方向：新增 saveGradeDraftAction 和 getGradeDraftAction，将草稿保存到 DB。

3.3 P3 长期易用性问题（记录但不本次实施）

编号	问题	位置
v3-P3-1	成绩录入无模板下载	batch-grade-entry.tsx
v3-P3-2	成绩列表无批量操作	grade-record-list.tsx
v3-P3-3	诊断报告无自定义模板	data-access-reports.ts
v3-P3-4	成绩趋势图无日期范围选择	grade-trend-card.tsx
v3-P3-5	班级对比图无显著性标记	class-comparison-chart.tsx
v3-P3-6	学生诊断无历史对比	student-diagnostic-view.tsx
v3-P3-7	成绩录入无语音输入	batch-grade-entry.tsx
v3-P3-8	诊断报告无分享功能	report-list.tsx

---

四、v3 改进优先级

P1（本次实施）

#	问题	改进方向	状态
v3-P1-1	成绩列表无编辑入口	增加编辑按钮，Dialog 内编辑	✅ 已完成
v3-P1-2	批量录入不支持 Excel 粘贴	添加 onPaste 处理器	✅ 已完成
v3-P1-3	学生排名硬编码且趋势图未接入	计算实际排名 + 接入趋势图	✅ 已完成
v3-P1-4	诊断报告发布无通知	对接 notifications 模块	✅ 已完成
v3-P1-5	成绩录入不触发诊断更新	关联 examId 时触发掌握度更新	✅ 已完成

P2（本次实施）

#	问题	改进方向	状态
v3-P2-1	科目过滤器用名称	改用 subjectId	✅ 已完成
v3-P2-2	趋势图无班级对比	添加班级平均对比线	✅ 已完成
v3-P2-3	批量录入无撤销	返回 ID 列表 + 撤销按钮	✅ 已完成
v3-P2-4	诊断报告无导出	新增 exportDiagnosticReportAction	✅ 已完成
v3-P2-5	班级诊断无知识点筛选	增加知识点筛选下拉框	✅ 已完成
v3-P2-6	弱项无练习推荐	Practice 按钮跳转题目库	✅ 已完成
v3-P2-7	分析页无学期/考试筛选	AnalyticsFilters 增加筛选	✅ 已完成
v3-P2-8	家长页面无趋势图	复用 GradeTrendCard	✅ 已完成
v3-P2-9	管理员无全校汇总	新增全校汇总卡片	✅ 已完成
v3-P2-10	草稿仅本地	新增服务端草稿保存	✅ 已完成

P3（长期，本次不实施）

v3-P3-1 ~ v3-P3-8 共 8 项长期易用性改进，记录备查，后续迭代处理。

---

五、实施计划

实施顺序：

1. P1 易用性核心修复（v3-P1-1 ~ v3-P1-5）
2. P2 易用性增强（v3-P2-1 ~ v3-P2-10）
3. 验证：lint + tsc + 架构文档同步