feat(school,classes): 学校/年级/班级模块审计修复 — 权限校验 + i18n + 架构图同步

- 新增审计报告 docs/architecture/audit/school-grade-class-audit-report.md - 修复 P0-4: teacher/classes 4 个页面补充 requirePermission 权限校验 - 修复 P0-5: 新增 school.json i18n 文件（zh-CN/en）并接入 schools-view 组件 - 同步架构图 004：补充 grade-management 死模块记录与 teacher/classes 权限修复说明
2026-06-22 16:44:02 +08:00
parent 22d3f07fcf
commit 10c668f36a
11 changed files with 787 additions and 86 deletions
--- a/docs/architecture/004_architecture_impact_map.md
+++ b/docs/architecture/004_architecture_impact_map.md
@@ -402,6 +402,12 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"

   ✅ P0 安全修复：admin/layout.tsx 提供登录态统一守卫，
      各页面 requirePermission() 提供细粒度权限校验
+
+   teacher/classes/* 路由权限校验（2026-06-22 审计修复）：
+   ├─▶ /teacher/classes/my           → requirePermission(CLASS_READ)  ✅ 已修复
+   ├─▶ /teacher/classes/my/[id]      → requirePermission(CLASS_READ)  ✅ 已修复
+   ├─▶ /teacher/classes/schedule     → requirePermission(CLASS_READ)  ✅ 已修复
+   └─▶ /teacher/classes/students     → requirePermission(CLASS_READ)  ✅ 已修复
 ```

 ---
@@ -674,6 +680,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - Actions：`getGradeRecordsAction` / `createGradeRecordAction` / `updateGradeRecordAction` / `deleteGradeRecordAction` / `exportGradesAction` / `getGradeTrendAction` / `getClassComparisonAction` / `getSubjectComparisonAction` / `getGradeDistributionAction` / `getClassRankingAction` / `getRankingTrendAction` / `getGradeRecordByIdAction` / `getClassGradeStatsAction` / `getStudentGradeSummaryAction` / `batchCreateGradeRecordsAction`
 - Data-access：`getGradeRecords` / `getStudentGradeSummary` / `getClassRanking` / `getClassStudentsForEntry` / `getClassGradeStats` / `getClassGradeStatsWithMeta` / `getGradeTrend` / `getClassComparison` / `getSubjectComparison` / `getGradeDistribution` / `getRankingTrend`
 - Lib（✅ P1-2 新增）：`toNumber` / `normalize` / `buildScopeClassFilter`（从 3 个 data-access 文件抽取的公共工具函数）
+- Stats-service（✅ P1-1 新增）：`computeGradeStats` / `computeAverageScore` / `buildGradeTrendPoints` / `computeTrendAverage` / `computeClassComparisonStats` / `computeSubjectComparisonStats` / `computeGradeDistribution` / `buildRankingTrendPoints`（从 3 个 data-access 文件抽取的纯函数，使数据层专注 DB I/O，统计逻辑可独立测试）
+- Components（✅ P1-5 新增）：`WidgetBoundary`（Error Boundary + Suspense + Skeleton 组合，含 a11y 属性）

 **依赖关系**：
 - 依赖：`shared/*`、`@/auth`、`classes`（✅ P1-1 已修复：通过 classes data-access.getClassExists/getClassNameById/getClassNamesByIds/getActiveStudentIdsByClassId/getStudentActiveClassId/getClassesByGradeId）、`school`（✅ P1-1 已修复：通过 school data-access.getSubjectOptions/getGradeOptions）、`users`（✅ P1-1 已修复：通过 users data-access.getUserNamesByIds）
@@ -681,11 +689,12 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"

 **已知问题**：
 - ✅ P1-1 已修复：~~多处直查 `classes`/`classEnrollments`/`subjects`/`users` 表~~ 改为调用对应模块 data-access 函数（classes/school/users）
+- ✅ P1-1 已修复：~~统计计算业务逻辑混入 data-access（`getClassGradeStats` / `getGradeDistribution`）~~ 抽取为纯函数到 `stats-service.ts`，数据层专注 DB I/O
 - ✅ P1-2 已修复：~~`toNumber`/`normalize`/`buildScopeClassFilter` 在 3 个 data-access 文件中重复定义~~ 抽取到 `lib/grade-utils.ts` 统一维护
 - ✅ P1-3 已修复：~~12 个查询/分析 Action 缺少 Zod 校验~~ 新增 12 个查询 schema（DeleteGradeRecordSchema/GetGradeRecordByIdSchema/GradeQuerySchema/ClassGradeStatsQuerySchema/StudentGradeSummaryQuerySchema/ClassRankingQuerySchema/ExportGradesSchema/GradeTrendQuerySchema/ClassComparisonQuerySchema/SubjectComparisonQuerySchema/GradeDistributionQuerySchema/RankingTrendQuerySchema），所有 Action 使用 safeParse 校验
 - ✅ P1-4 已修复：~~`batch-grade-entry.tsx`/`grade-record-form.tsx`/`grade-distribution-chart.tsx` 中存在 `as` 断言~~ 改用类型守卫函数（isGradeType/isSemester/isDistributionTooltipPayload）
+- ✅ P1-5 已修复：~~teacher/grades 与 teacher/diagnostic 路由缺少 loading.tsx/error.tsx~~ 已为 7 个路由补齐 loading.tsx + error.tsx，并新增 `WidgetBoundary` 通用组件
 - ✅ P2-2 已修复：~~diagnostic 组件中存在 Tailwind 任意值~~ 改用标准 Tailwind 类
- ⚠️ P2：统计计算业务逻辑混入 data-access（`getClassGradeStats` / `getGradeDistribution`）
 - ✅ actions 层无直接 DB 访问（标杆）
 - ✅ data-access 按职责拆分为 3 个文件（标杆）
 - ✅ P2 已修复：`export.ts` 中 `scoreMap.get(r.studentId)!` 非空断言清理为安全守卫（`if (!subjMap) continue`）
@@ -698,9 +707,11 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 | `data-access.ts` | 361 | 成绩 CRUD + 统计 |
 | `data-access-analytics.ts` | 266 | 趋势/对比分析 |
 | `data-access-ranking.ts` | 96 | 排名查询 |
+| `stats-service.ts` | - | 统计计算纯函数（P1-1 新增：8 个纯函数 + 2 个常量 + 2 个接口） |
 | `export.ts` | 214 | Excel 导出 |
 | `schema.ts` | 100 | Zod 校验（含 12 个查询 schema） |
 | `lib/grade-utils.ts` | 46 | 公共工具函数（toNumber/normalize/buildScopeClassFilter） |
+| `components/widget-boundary.tsx` | - | Widget 边界组件（P1-5 新增） |
 | `types.ts` | - | 类型定义 |

 ---
@@ -758,17 +769,58 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
 - ✅ P2 已修复：`data-access.ts` 中 8 处 catch 块添加 `console.error` 输出错误上下文（getDepartments/getAcademicYears/getSchools/getGrades/getStaffOptions/getGradesForStaff/getSubjectOptions/getGradeOptions）
 - ⚠️ P2：审计日志不一致（仅 school 实体记录，department/academicYear/grade 未记录）
 - ⚠️ P2：`getStaffOptions`/`getGrades` 直查 users/roles（展示用，可接受）
+- ⚠️ P0-2（2026-06-22 审计发现）：年级 CRUD 逻辑与 `grade-management` 模块重复定义，两套实现并存
+- ⚠️ P0-5（2026-06-22 审计发现）：`school/components/*` 4 个组件均缺少 i18n（`schools-view.tsx` 已修复，其余 3 个待修复）；缺少 Error Boundary / Skeleton
+- ✅ P0-5 部分修复（2026-06-22）：新增 `school.json` i18n 文件，`schools-view.tsx` 接入 `useTranslations("school")`

 **文件清单**：
 | 文件 | 行数 | 职责 |
 |------|------|------|
-| `actions.ts` | 326 | 12 个 Server Action（编排层，无 DB 直访） |
-| `data-access.ts` | 320 | 只读查询 + 12 个写操作（CRUD） |
+| `actions.ts` | 349 | 12 个 Server Action（编排层，无 DB 直访） |
+| `data-access.ts` | 504 | 只读查询 + 12 个写操作 + 跨模块查询接口（`isGradeHead`/`isGradeManager`/`findGradeIdByHeadAndName`/`getGradeNameById`/`getSubjectNameById`） |
 | `schema.ts` | 51 | Zod 校验 |
 | `types.ts` | 96 | 类型定义（含 Insert/Update 入参类型） |

 ---

+## 2.8b grade-management（年级管理模块）— ⚠️ 死模块
+
+> **2026-06-22 审计发现**：该模块拥有完整的理想架构（Service 接口 + Context DI + 角色配置 + Error Boundary + Skeleton + i18n + hooks 分离），但 **13 个相关页面中无任何一个导入此模块**。`management/grade/*` 页面实际依赖 `classes` 和 `school` 模块的 data-access。详见 `docs/architecture/audit/school-grade-class-audit-report.md`。
+
+**职责**：年级 CRUD + 年级作业洞察（重构版，对标理想架构模式）。
+
+**导出函数**：
+- Actions：`createGradeAction` / `updateGradeAction` / `deleteGradeAction`（与 school 模块重复定义）
+- Data-access：`getGrades` / `getGradesForStaff` / `getSchools` / `getStaffOptions` / `createGrade` / `updateGrade` / `deleteGrade` / `generateGradeId`（与 school 模块重复）
+- Data-access-insights：`getGradeInsights`（通过 `classes/data-access.getGradeHomeworkInsights` 获取数据，跨模块通信合规）
+- Services：`GradeService` 接口 + `AdminGradeService` / `TeacherGradeService` 实现 + `GradeServiceProvider` Context
+- Config：`GRADE_ROLE_CONFIG` 角色配置 + `getGradeRoleConfig` / `resolveGradeRoleConfig`
+- Hooks：`useGradeData` / `useGradeFilters` / `useGradeForm` / `useGradeInsights`
+- Widgets：`GradeManagementWidget` / `GradeInsightsWidget`
+
+**依赖关系**：
+- 依赖：`shared/*`、`@/auth`、`classes`（通过 `data-access.getGradeHomeworkInsights`，合规）
+- 被依赖：⚠️ **无任何模块或页面依赖此模块**
+
+**已知问题**：
+- ⚠️ P0-1：模块完全未被使用（死模块），所有页面使用 school/classes 模块的 data-access
+- ⚠️ P0-2：年级 CRUD 逻辑与 school 模块重复定义
+
+**文件清单**：
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 213 | 3 个 Server Action（含审计日志，比 school 模块版本更完善） |
+| `data-access.ts` | 238 | 年级 CRUD + 查询（与 school 模块重复） |
+| `data-access-insights.ts` | 75 | 年级洞察（适配 classes 模块数据） |
+| `types.ts` | 149 | 类型定义（含 GradeService 接口、角色配置、埋点接口） |
+| `services/*.tsx` | 4 文件 | GradeService 接口 + 实现 + Context DI |
+| `config/role-config.ts` | 66 | 角色配置驱动设计 |
+| `hooks/*.ts` | 4 文件 | 数据/筛选/表单/洞察 hooks |
+| `widgets/*.tsx` | 2 文件 | 管理面板 + 洞察面板 |
+| `components/*.tsx` | 11 文件 | 表格/工具栏/对话框/骨架屏/错误边界/空状态 |
+
+---
+
 ## 2.9 scheduling（排课模块）

 **职责**：自动排课算法 + 课表调整 + 排课规则管理。