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-v3.md
+++ b/docs/architecture/audit/grades-diagnostic-audit-report-v3.md
@@ -0,0 +1,296 @@
+# 成绩和学情诊断模块易用性审计报告 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](file:///e:/Desktop/CICD/src/modules/grades/components/grade-record-list.tsx) L102-112 | 仅有删除按钮，无编辑按钮 | 教师录错成绩后只能删除重录，效率极低 |
+| [actions.ts](file:///e:/Desktop/CICD/src/modules/grades/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](file:///e:/Desktop/CICD/src/modules/grades/components/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](file:///e:/Desktop/CICD/src/modules/grades/data-access.ts) L351 | `getStudentGradeSummary` 返回 `rank: 0` 硬编码 | 学生看不到自己的班级排名 |
+| [student/grades/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/student/grades/page.tsx) | 未调用 `getRankingTrendAction` | 排名趋势图功能浪费 |
+
+**同类系统对比**：PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb 全部显示学生班级排名。
+
+**用户痛点**：学生/家长查看成绩时最关心"班级第几名"，当前页面只显示平均分和记录列表，无法回答"孩子排第几"这个核心问题。
+
+**改进方向**：
+1. `getStudentGradeSummary` 调用 `getClassRanking` 计算实际排名
+2. 学生页面接入 `getRankingTrendAction`，显示排名趋势图
+
+#### v3-P1-4 诊断报告发布无通知机制
+
+| 位置 | 问题 | 影响 |
+|------|------|------|
+| [diagnostic/actions.ts](file:///e:/Desktop/CICD/src/modules/diagnostic/actions.ts) L78-100 | `publishReportAction` 仅执行 `revalidatePath`，未触发通知 | 学生/家长不知道报告已发布 |
+
+**同类系统对比**：PowerSchool、Infinite Campus、Skyward、Alma、Gradelink、RenWeb 全部在报告发布时发送通知。
+
+**用户痛点**：教师发布诊断报告后，学生/家长需要主动登录查看才知道有新报告，信息传递滞后；同类系统会自动推送站内通知/邮件/短信。
+
+**改进方向**：`publishReportAction` 调用 `notifications` 模块的 `createNotification`，向学生（个人报告）或全班学生（班级报告）发送站内通知。
+
+#### v3-P1-5 成绩录入不触发诊断掌握度更新
+
+| 位置 | 问题 | 影响 |
+|------|------|------|
+| [diagnostic/data-access.ts](file:///e:/Desktop/CICD/src/modules/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](file:///e:/Desktop/CICD/src/app/(dashboard)/student/grades/page.tsx) L49 | `r.subjectName !== subjectFilter` 按名称过滤，科目重名时会冲突 |
+
+**改进方向**：改为按 subjectId 过滤，`GradeFilters` 组件的科目选项使用 ID 作为 value。
+
+#### v3-P2-2 成绩趋势图无班级平均对比线
+
+| 位置 | 问题 |
+|------|------|
+| [grade-trend-card.tsx](file:///e:/Desktop/CICD/src/modules/grades/components/grade-trend-card.tsx) | 仅显示学生个人趋势，无班级平均对比 |
+
+**同类系统对比**：PowerSchool、Infinite Campus、Skyward、Alma 都支持个人 vs 班级平均对比。
+
+**改进方向**：`GradeTrendCard` 接收 `classAverageData` prop，在趋势图中添加第二条对比线。
+
+#### v3-P2-3 批量录入无撤销功能
+
+| 位置 | 问题 |
+|------|------|
+| [batch-grade-entry.tsx](file:///e:/Desktop/CICD/src/modules/grades/components/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](file:///e:/Desktop/CICD/src/modules/diagnostic/components/class-diagnostic-view.tsx) | 无法按"某知识点掌握度 < 60%"筛选学生列表 |
+
+**同类系统对比**：PowerSchool、Infinite Campus 支持按知识点筛选学生。
+
+**改进方向**：`class-diagnostic-view.tsx` 增加知识点筛选下拉框，筛选出该知识点掌握度低于阈值的学生。
+
+#### v3-P2-6 弱项无个性化练习推荐
+
+| 位置 | 问题 |
+|------|------|
+| [student-diagnostic-view.tsx](file:///e:/Desktop/CICD/src/modules/diagnostic/components/student-diagnostic-view.tsx) | "Practice" 按钮无实际跳转目标 |
+
+**同类系统对比**：PowerSchool、Alma 支持基于弱项推荐练习题。
+
+**改进方向**：`student-diagnostic-view.tsx` 的"Practice"按钮跳转到题目库，带知识点筛选参数。
+
+#### v3-P2-7 成绩分析页无学期/考试筛选
+
+| 位置 | 问题 |
+|------|------|
+| [teacher/grades/analytics/page.tsx](file:///e:/Desktop/CICD/src/app/(dashboard)/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](file:///e:/Desktop/CICD/src/modules/grades/components/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 + 架构文档同步