xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

refactor(school,classes): 完成 school/grade/class 审计全量改进项

Browse Source 
P0-1/P0-2: 删除 grade-management 死模块，年级 CRUD 统一由 school 模块负责

P0-3: classes/actions.ts 从 974 行拆分为 6 个职责文件 + barrel re-export

P0-5: 13 个页面 i18n 全量接入（grades/departments/academic-year/classes/insights）

P1-1: 角色硬编码改为 hasAdminScope/hasTeacherScope/hasStudentScope 基于 dataScope.type

P1-3: 新增 SchoolErrorBoundary + SchoolListSkeleton/SchoolCardSkeleton，4 个页面包裹 Error Boundary

P1-4: classes/types.ts 跨领域类型添加归属决策注释

P1-5: schools-view.tsx 拆分为组合模式（SchoolFormDialog + SchoolDeleteDialog + SchoolListToolbar）

P1-6: 新增 getSchoolsForUser/getGradesForUser 权限感知查询函数

P2-1: 抽取 useSchoolData hook，对话框状态管理与 UI 分离

同步更新架构图文档 004/005
This commit is contained in:
SpecialX
2026-06-22 18:54:01 +08:00
parent 97e59b95a1
commit 15aa84b72c
29 changed files with 2267 additions and 1380 deletions
Download Patch File Download Diff File Expand all files Collapse all files

70
docs/architecture/004_architecture_impact_map.md
View File

@@ -750,6 +750,9 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
- ✅ P1-1 已修复：~~`actions.ts` 直查 `grades` 表做权限校验~~ 改为调用 `school/data-access` 函数
- ✅ P1-1 已修复：~~`getSessionTeacherId` 在 data-access 调用 `auth()`~~ 改为通过 `shared/lib/auth-guard.getAuthContext()` 获取
- ✅ P2 已修复：`data-access.ts` 中 `idByName.get(name)!` 非空断言清理为 `flatMap` 安全过滤；`data-access-admin.ts` 中同类非空断言清理
- ✅ P0-3 修复（2026-06-22）：~~`actions.ts` 974 行接近 1000 行硬上限~~ 拆分为 6 个文件（actions-teacher/actions-admin/actions-grade/actions-invitations/actions-schedule/actions-shared），原 `actions.ts` 改为 50 行 barrel re-export
- ✅ P1-1 修复（2026-06-22）：~~`ctx.roles.includes("admin"/"teacher"/"student")` 角色硬编码~~ 改为 `hasAdminScope(ctx)`/`hasTeacherScope(ctx)`/`hasStudentScope(ctx)` 基于 `dataScope.type` 判断
- ✅ P1-4 修复（2026-06-22）：`types.ts` 中 ClassHomeworkInsights 等跨领域类型保留在 classes 模块（因为是 classes 对 homework 数据的视图），添加注释说明归属决策
**文件清单**：
| 文件 | 行数 | 职责 |
@@ -759,9 +762,15 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions"
| `data-access-schedule.ts` | 93 | 课表查询（学生/班级课表只读，P0-5 已修复：写函数已迁移至 scheduling 模块） |
| `data-access-students.ts` | 253 | 学生相关查询（科目成绩、学生名单、学生班级，通过 homework/data-access-classes 获取数据） |
| `data-access-admin.ts` | 406 | 管理员班级管理（管理员班级 CRUD、年级管理班级查询） |
| `actions.ts` | 785 | 17 个 Server Action（三组重复，使用 Zod schema 校验） |
| `actions.ts` | 50 | Barrel re-export（P0-3 修复：从 974 行拆分为 6 个文件） |
| `actions-teacher.ts` | 100 | 教师班级 CRUD（3 个 Action） |
| `actions-admin.ts` | 120 | 管理员班级 CRUD（3 个 Action） |
| `actions-grade.ts` | 110 | 年级组长班级 CRUD（3 个 Action） |
| `actions-invitations.ts` | 280 | 邀请码与注册（8 个 Action） |
| `actions-schedule.ts` | 90 | 班级课表 CRUD（3 个 Action） |
| `actions-shared.ts` | 60 | 共享工具（hasAdminScope/hasTeacherScope/hasStudentScope/parseSubjectTeachers/toWeekday） |
| `schema.ts` | 152 | Zod 校验（13 个 schema：教师/管理员/年级班级 CRUD + 课表 CRUD + 邮箱注册） |
| `types.ts` | 201 | 类型定义（含跨领域类型污染） |
| `types.ts` | 201 | 类型定义（含跨领域类型说明注释，P1-4 修复） |
---
@@ -783,58 +792,35 @@ 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")`
- ✅ P0-2 修复（2026-06-22）：~~年级 CRUD 逻辑与 `grade-management` 模块重复定义~~ `grade-management` 死模块已删除，年级 CRUD 统一由 school 模块负责
- ✅ P0-5 修复（2026-06-22）：~~`school/components/*` 4 个组件缺少 i18n~~ 全部 4 个组件（schools-view/grades-view/departments-view/academic-year-view）已接入 `useTranslations("school")`；`school.json` i18n 文件已创建并扩充
- ✅ P1-3 修复（2026-06-22）：新增 school-error-boundary.tsx（class component Error Boundary + i18n + router.refresh 重试）和 school-skeleton.tsx（SchoolListSkeleton 表格骨架 + SchoolCardSkeleton 卡片骨架）；4 个页面（schools/grades/departments/academic-year）均已包裹 SchoolErrorBoundary；school.json 补充 errors.boundary.* 翻译键
- ✅ P1-5 修复（2026-06-22）：~~`schools-view.tsx` 硬编码 Table+Dialog+AlertDialog~~ 拆分为组合模式：SchoolListToolbar + SchoolFormDialog + SchoolDeleteDialog + useSchoolData hook
- ✅ P1-6 修复（2026-06-22）：新增 `getSchoolsForUser(userId)` / `getGradesForUser(userId)` 权限感知查询函数，根据用户角色返回可见数据范围
- ✅ P2-1 修复（2026-06-22）：抽取 `use-school-data` hook，将对话框状态管理逻辑与 UI 分离
**文件清单**：
| 文件 | 行数 | 职责 |
|------|------|------|
| `actions.ts` | 349 | 12 个 Server Action（编排层，无 DB 直访） |
| `data-access.ts` | 504 | 只读查询 + 12 个写操作 + 跨模块查询接口（`isGradeHead`/`isGradeManager`/`findGradeIdByHeadAndName`/`getGradeNameById`/`getSubjectNameById`） |
| `data-access.ts` | 504+ | 只读查询 + 12 个写操作 + 跨模块查询接口 + 权限感知函数（getSchoolsForUser/getGradesForUser） |
| `schema.ts` | 51 | Zod 校验 |
| `types.ts` | 96 | 类型定义（含 Insert/Update 入参类型） |
| components/school-error-boundary.tsx | 72 | 共享 Error Boundary（class component + i18n + router.refresh 重试） |
| components/school-skeleton.tsx | 69 | 共享骨架屏（SchoolListSkeleton 表格骨架 + SchoolCardSkeleton 卡片骨架） |
| components/schools-view.tsx | 132 | 学校列表容器（组合模式，P1-5 修复） |
| components/school-form-dialog.tsx | 80 | 学校创建/编辑对话框（P1-5 修复） |
| components/school-delete-dialog.tsx | 50 | 学校删除确认对话框（P1-5 修复） |
| components/school-list-toolbar.tsx | 30 | 学校列表工具栏（P1-5 修复） |
| components/school-error-boundary.tsx | 72 | 共享 Error Boundary（P1-3 修复） |
| components/school-skeleton.tsx | 69 | 共享骨架屏（P1-3 修复） |
| hooks/use-school-data.ts | 40 | 学校数据管理 hook（P2-1 修复） |
---
## 2.8b grade-management（年级管理模块）— ⚠️ 死模块
## 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 文件 | 表格/工具栏/对话框/骨架屏/错误边界/空状态 |
> **2026-06-22 审计发现**：该模块拥有完整的理想架构（Service 接口 + Context DI + 角色配置 + Error Boundary + Skeleton + i18n + hooks 分离），但 **13 个相关页面中无任何一个导入此模块**。`management/grade/*` 页面实际依赖 `classes` 和 `school` 模块的 data-access。
>
> **2026-06-22 处置决策（P0-1/P0-2 修复）**：该死模块已**完整删除**。年级 CRUD 统一由 `school` 模块负责（`school/actions.ts` + `school/data-access.ts`），避免两套重复实现。详见 `docs/architecture/audit/school-grade-class-audit-report.md`。
---