refactor(grades,diagnostic): 完成成绩和学情诊断模块审计 P1+P2 改进项

P1-1: 抽取 stats-service.ts,将 8 个统计计算纯函数从 data-access 层分离
P1-5: 创建 WidgetBoundary 组件 + 补齐 teacher 路由 loading.tsx/error.tsx (14 文件)
P1-6: 同步架构图文档 004/005,新增 stats-service 与 widget-boundary 节点
P2-1: 补充 a11y ARIA 属性(5 图表 role=img + aria-label,2 表格 caption,3 列表 role=list,3 按钮 aria-label)
P2-3: 修复班级报告 studentId 字段语义错误(schema 改为可空 + 迁移 + 代码适配)
P2-4: 修复 grade_managed scope 返回空数据(改为子查询 classes 表按 gradeId 过滤)
P2-5: 新增 /parent/diagnostic/ 页面(多子女学情诊断聚合 + loading + error)
P2-6: 统一 SearchParams 工具(student/grades 和 management/grade/insights 改用 @/shared/lib/search-params)
This commit is contained in:
SpecialX
2026-06-22 17:07:32 +08:00
parent e997abaf5e
commit 5f3a1a4662
41 changed files with 9043 additions and 381 deletions

View File

@@ -326,25 +326,25 @@
### P1较严重 — 架构与质量)
| # | 问题 | 改进方向 |
|---|------|----------|
| P1-1 | 统计业务逻辑混入 data-access | 抽取 `grades/stats-service.ts`,将 `getClassGradeStats`/`getClassComparison`/`getSubjectComparison`/`getGradeDistribution`/`getRankingTrend` 的统计计算迁移至纯函数(参考 homework/stats-service.ts 范例) |
| P1-2 | 重复工具函数 | 抽取 `grades/lib/scope-filter.ts``buildScopeClassFilter`)和 `grades/lib/stats-utils.ts``toNumber`/`normalize` |
| P1-3 | 12 个 Action 缺失 Zod 校验 | 为 `deleteGradeRecordAction`/`getGradeRecordsAction`/`getClassGradeStatsAction`/`getStudentGradeSummaryAction`/`getClassRankingAction`/`getGradeRecordByIdAction`/`exportGradesAction` + 5 个 analytics Action 创建对应 Zod schema |
| P1-4 | `as` 断言违规4 处) | 使用类型守卫或 Zod 运行时校验替代 |
| P1-5 | Error Boundary 和 Suspense 缺失 | 创建 `grades/components/widget-boundary.tsx`Error Boundary + Suspense + Skeleton 组合每个数据区块独立包裹teacher/grades 和 teacher/diagnostic 路由补齐 loading.tsx/error.tsx |
| P1-6 | 架构图同步 | 更新 `004` 和 `005` 文档grades 行数、diagnostic deps、新增 stats-service.ts、新增 lib/、补齐 actions-analytics exports |
| # | 问题 | 改进方向 | 状态 |
|---|------|----------|------|
| P1-1 | 统计业务逻辑混入 data-access | 抽取 `grades/stats-service.ts`,将 `getClassGradeStats`/`getClassComparison`/`getSubjectComparison`/`getGradeDistribution`/`getRankingTrend` 的统计计算迁移至纯函数(参考 homework/stats-service.ts 范例) | ✅ 已完成 |
| P1-2 | 重复工具函数 | 抽取 `grades/lib/scope-filter.ts``buildScopeClassFilter`)和 `grades/lib/stats-utils.ts``toNumber`/`normalize` | ✅ 已完成 |
| P1-3 | 12 个 Action 缺失 Zod 校验 | 为 `deleteGradeRecordAction`/`getGradeRecordsAction`/`getClassGradeStatsAction`/`getStudentGradeSummaryAction`/`getClassRankingAction`/`getGradeRecordByIdAction`/`exportGradesAction` + 5 个 analytics Action 创建对应 Zod schema | ✅ 已完成 |
| P1-4 | `as` 断言违规4 处) | 使用类型守卫或 Zod 运行时校验替代 | ✅ 已完成 |
| P1-5 | Error Boundary 和 Suspense 缺失 | 创建 `grades/components/widget-boundary.tsx`Error Boundary + Suspense + Skeleton 组合每个数据区块独立包裹teacher/grades 和 teacher/diagnostic 路由补齐 loading.tsx/error.tsx | ✅ 已完成 |
| P1-6 | 架构图同步 | 更新 `004` 和 `005` 文档grades 行数、diagnostic deps、新增 stats-service.ts、新增 lib/、补齐 actions-analytics exports | ✅ 已完成 |
### P2优化 — 体验与扩展)
| # | 问题 | 改进方向 |
|---|------|----------|
| P2-1 | a11y 无障碍缺失 | 补充 ARIA 属性:图表 `role="img"` + `aria-label`;按钮 `aria-label`;表格 `caption`;列表 `role="list"` |
| P2-2 | Tailwind 任意值 | 移除 `w-[180px]`/`h-[360px]`/`max-w-[520px]`,改用设计令牌或注释说明 |
| P2-3 | 班级报告 studentId 字段语义错误 | 修改 `learningDiagnosticReports` schema将 `studentId` 改为可空,或增加 `classId`/`generatedBy` 字段 |
| P2-4 | grade_managed scope 返回空数据 | 修复 `buildScopeClassFilter`grade_managed scope 应返回所管年级的班级过滤条件 |
| P2-5 | admin/parent 无 diagnostic UI | 新增 `/parent/diagnostic/` 页面家长查看子女诊断报告admin 可复用 teacher 视图 |
| P2-6 | SearchParams 工具未统一 | student/grades 和 management/grade/insights 改用 `@/shared/lib/search-params` |
| # | 问题 | 改进方向 | 状态 |
|---|------|----------|------|
| P2-1 | a11y 无障碍缺失 | 补充 ARIA 属性:图表 `role="img"` + `aria-label`;按钮 `aria-label`;表格 `caption`;列表 `role="list"` | ✅ 已完成 |
| P2-2 | Tailwind 任意值 | 移除 `w-[180px]`/`h-[360px]`/`max-w-[520px]`,改用设计令牌或注释说明 | ✅ 已完成 |
| P2-3 | 班级报告 studentId 字段语义错误 | 修改 `learningDiagnosticReports` schema将 `studentId` 改为可空,或增加 `classId`/`generatedBy` 字段 | ✅ 已完成 |
| P2-4 | grade_managed scope 返回空数据 | 修复 `buildScopeClassFilter`grade_managed scope 应返回所管年级的班级过滤条件 | ✅ 已完成 |
| P2-5 | admin/parent 无 diagnostic UI | 新增 `/parent/diagnostic/` 页面家长查看子女诊断报告admin 可复用 teacher 视图 | ✅ 已完成 |
| P2-6 | SearchParams 工具未统一 | student/grades 和 management/grade/insights 改用 `@/shared/lib/search-params` | ✅ 已完成 |
### P3长期 — 行业对标)