Files

SpecialX 747344bfe3 chore: snapshot before P0 security phase (backup point)

2026-07-07 19:12:33 +08:00

17 KiB

Raw Blame History

学校/年级/班级管理模块审计报告 v2

审查范围：school（学校/学年/部门/年级 CRUD）、classes（班级管理）审查日期：2026-06-22（v2 复审）审查依据：项目规则（三层架构、权限校验、i18n、TypeScript 严格模式、单文件行数限制）、K12 行业优秀实践审查方式：只读源码分析 + 架构图比对 + 行业对标

一、现有实现概要

1.1 v1 审计修复回顾

v1 审计报告识别了 14 个问题（5 个 P0 + 6 个 P1 + 5 个 P2），截至本次复审，全部 14 个问题已修复：

编号	问题	状态
P0-1	`grade-management` 死模块	✅ 已删除
P0-2	年级 CRUD 逻辑重复	✅ 统一到 school 模块
P0-3	`classes/actions.ts` 974 行	✅ 拆分为 6 个文件
P0-4	`teacher/classes/*` 无权限校验	✅ 4 个页面已加 `requirePermission`
P0-5	school 模块无 i18n	✅ 4 个组件已接入 `useTranslations`
P1-1	角色硬编码	✅ 改为 `dataScope.type` 判断
P1-2	school 无 i18n 文件	✅ `school.json` 已创建（413 行翻译键）
P1-3	school 缺 Error Boundary/Skeleton	✅ 已补充
P1-4	classes/types.ts 跨领域类型	✅ 保留并加注释说明
P1-5	school 未用组合模式	✅ 拆分为 4 个子组件
P1-6	data-access 无权限过滤	✅ 新增 `getSchoolsForUser`/`getGradesForUser`
P2-1~P2-5	各项优化	✅ 全部修复

1.2 当前模块文件分布

模块	核心文件	行数	职责
`school`	`actions.ts`	457	13 个 Server Action（含 `promoteGradesAction`）
`school`	`data-access.ts`	757	只读查询 + 12 个写操作 + 组织树 + 权限感知函数
`school`	`schema.ts` / `types.ts`	51 / 90	Zod 校验 / 类型定义
`school`	`components/` (14 文件)	60~860	学校/学年/部门/年级视图 + 仪表盘 + 组织树
`school`	`hooks/use-school-data.ts`	36	学校数据管理 hook
`classes`	`actions.ts` (barrel)	51	re-export 入口
`classes`	`actions-{teacher,admin,grade,invitations,schedule,shared}.ts`	60~448	按职责拆分的 6 个 Action 文件
`classes`	`data-access.ts`	833	核心班级 CRUD + 邀请码 + 教师班级管理
`classes`	`data-access-{admin,stats,schedule,students,invitations}.ts`	93~454	按领域拆分的 5 个 data-access
`classes`	`schema.ts` / `types.ts`	152 / 177	Zod 校验 / 类型定义
`classes`	`components/` (14 文件)	137~499	班级列表/详情/学生/课表/邀请码

1.3 页面分布（共 13 个 page.tsx）

路由分组	页面	权限校验	i18n	Error Boundary	Loading
`admin/school/schools`	✅ `SCHOOL_MANAGE`	✅	✅	✅	✅
`admin/school/grades`	✅ `SCHOOL_MANAGE`	✅	✅	✅	✅
`admin/school/grades/insights`	✅ `SCHOOL_MANAGE`	✅	✅	✅	✅
`admin/school/departments`	✅ `SCHOOL_MANAGE`	✅	✅	✅	✅
`admin/school/academic-year`	✅ `SCHOOL_MANAGE`	✅	✅	✅	✅
`admin/school/classes`	✅ `SCHOOL_MANAGE`	❌	❌	✅	✅
`management/grade/classes`	✅ `GRADE_MANAGE`	✅	✅	✅	✅
`management/grade/insights`	✅ `GRADE_MANAGE`	✅	✅	✅	✅
`management/grade/dashboard`	✅ `GRADE_MANAGE`	✅	✅	❌	✅
`teacher/classes/my`	✅ `CLASS_READ`	❌	❌	❌	✅
`teacher/classes/my/[id]`	✅ `CLASS_READ`	❌	❌	❌	❌
`teacher/classes/schedule`	✅ `CLASS_READ`	❌	✅(Suspense)	❌	✅
`teacher/classes/students`	✅ `CLASS_READ`	❌	✅(Suspense)	❌	✅

1.4 数据流概要

admin/school/* 页面（✅ 完整 i18n + Error Boundary + Skeleton）
  └─→ school/data-access.getSchools() / getGrades() / getStaffOptions() / getGradeOverviewStats()
  └─→ school/components/*（✅ 全部使用 useTranslations）
  └─→ school/actions.ts → createXxxAction / updateXxxAction / deleteXxxAction

management/grade/* 页面（✅ 完整 i18n + Error Boundary）
  └─→ classes/data-access.getGradeManagedClasses() / getTeacherOptions()
  └─→ school/data-access.getGradesForStaff()
  └─→ classes/components/grade-classes-view.tsx（❌ 无 i18n）
  └─→ classes/actions.ts → createGradeClassAction / ...

teacher/classes/* 页面（❌ 组件无 i18n，❌ 无 Error Boundary）
  └─→ classes/data-access.getTeacherClasses() / getClassStudents() / getClassSchedule()
  └─→ classes/components/*（❌ 14 个组件中仅 1 个使用 useTranslations）
  └─→ classes/actions.ts → createTeacherClassAction / ...

二、现存问题与原因分析（v2 新发现）

2.1 国际化层面

P0-A：classes 模块 13/14 个组件未接入 i18n

位置：
- src/modules/classes/components/admin-classes-view.tsx — 16 处英文硬编码（"Failed to create class"、"No classes"、"Select a school" 等）
- src/modules/classes/components/grade-classes-view.tsx — 20+ 处英文硬编码（"Homeroom Teacher"、"Subject Teachers"、"Select a grade" 等）
- src/modules/classes/components/my-classes-grid.tsx — 15+ 处英文硬编码（"Join New Class"、"Invitation Code"、"Cancel" 等）+ 1 处中文硬编码（"教学科目"、"暂无可选科目"）
- src/modules/classes/components/schedule-view.tsx — 10+ 处英文硬编码
- src/modules/classes/components/schedule-filters.tsx — 8 处英文硬编码
- src/modules/classes/components/students-filters.tsx — 5 处英文硬编码
- src/modules/classes/components/students-table.tsx — 英文硬编码
- src/modules/classes/components/class-detail/*.tsx（7 个文件）— 全部英文硬编码（"Recent Homework"、"Weekly Schedule"、"Quick Actions" 等）
问题：14 个组件中仅 class-invitation-manager.tsx 使用 useTranslations，其余 13 个组件全部硬编码文本，且 my-classes-grid.tsx 中存在中英文混用
违反规则：所有用户可见文本必须适配 i18n（使用 next-intl），提取翻译键
原因：v1 审计仅修复了 school 模块的 i18n，classes 模块的 i18n 遗留未处理
后果：teacher/management 视角下的班级管理页面无法支持多语言；中英文混用严重影响专业度

P0-B：classes.json i18n 文件内容严重不足

位置：src/shared/i18n/messages/{zh-CN,en}/classes.json
问题：当前仅 55 行，只覆盖 invitation.* 和 class.*（5 个基础字段）。缺少班级 CRUD 表单、列表、筛选器、详情页、学生管理、课表等全部场景的翻译键
违反规则：i18n 就绪规范
后果：即使组件想接入 i18n，也缺少翻译键可用

2.2 文件大小层面

P1-A：`grades-view.tsx` 860 行超出组件行数限制

位置：src/modules/school/components/grades-view.tsx（860 行）
问题：单个客户端组件文件 860 行，超过 React 组件建议上限 500 行（复杂表单可放宽至 800 行，但仍超）。包含年级列表 + 概览卡片 + 筛选器 + 创建/编辑表单 + 删除对话框 + 年级升级对话框全部逻辑
违反规则：单文件行数限制（React 组件建议 ≤ 500 行，复杂表单/大型表格可放宽至 800 行）
后果：可读性差，难以维护；筛选逻辑、表单校验逻辑、对话框状态管理全部耦合

P1-B：`classes/data-access.ts` 833 行超出 data-access 限制

位置：src/modules/classes/data-access.ts（833 行）
问题：虽然已拆分为 5 个 data-access 子文件，但主 data-access.ts 仍达 833 行，超过 data-access 建议 800 行上限。包含核心班级 CRUD + 邀请码 + 教师班级管理 + 跨模块接口
违反规则：单文件行数限制（Server Actions / Data Access 模块建议 ≤ 800 行）
后果：接近硬上限，后续增加功能即超限

2.3 错误处理层面

P1-C：classes 模块组件缺少 Error Boundary 和 Skeleton

位置：
- src/app/(dashboard)/teacher/classes/my/[id]/page.tsx — 无 Error Boundary
- src/app/(dashboard)/admin/school/classes/page.tsx — 无 Error Boundary
- src/app/(dashboard)/management/grade/dashboard/page.tsx — 无 Error Boundary
- src/modules/classes/components/* — 无骨架屏组件
问题：对比 school 模块已有 school-error-boundary.tsx + school-skeleton.tsx，classes 模块完全没有错误边界和骨架屏组件
违反规则：错误与边界处理（每个独立数据区块必须用 React Error Boundary 包裹；异步数据使用 React Suspense + 骨架屏）
后果：数据加载失败时整页崩溃无降级；加载过程无反馈

2.4 组件质量层面

P1-D：classes 组件未使用组合模式

位置：
- src/modules/classes/components/admin-classes-view.tsx（499 行）— 单体组件包含 Table + Dialog + AlertDialog + Select 全部逻辑
- src/modules/classes/components/grade-classes-view.tsx（408 行）— 同上
- src/modules/classes/components/my-classes-grid.tsx（390 行）— 单体组件包含卡片网格 + 加入班级对话框 + 邀请码管理
问题：对比 school 模块已拆分为 SchoolListToolbar + SchoolFormDialog + SchoolDeleteDialog + useSchoolData hook，classes 模块仍是单体组件，无法复用子部件
违反规则：组合优先（所有 UI 通过组件组合实现灵活性）
后果：admin/grade/teacher 三个视角的班级管理存在大量重复代码（表单、对话框、筛选器），无法复用

P1-E：classes 模块缺少 hooks 抽取

位置：src/modules/classes/ — 无 hooks/ 目录
问题：对比 school 模块已抽取 use-school-data hook，classes 模块的对话框状态管理、表单校验、筛选逻辑全部耦合在组件内部
违反规则：可测试性（数据获取、计算、格式化等纯逻辑全部放入纯函数或 hooks，与 UI 分离）
后果：无法对筛选逻辑、表单校验逻辑进行独立单测

2.5 架构模式层面

P2-A：缺少 Service 接口抽象和依赖注入

位置：整个 school + classes 模块
问题：组件直接 import data-access 函数，未通过 Service 接口抽象数据依赖。对比已删除的 grade-management 模块曾有完整的 GradeService 接口 + Context DI 模式
违反规则：完全解耦（通过定义 TypeScript 接口抽象数据依赖，使用 React Context 注入数据服务）
后果：组件与 data-access 直接耦合，难以 mock 测试；不同角色的差异通过 if/else 硬编码而非接口实现隔离

P2-B：缺少角色配置驱动设计

位置：整个 school + classes 模块
问题：admin/teacher/grade 三个视角的班级管理通过 3 套独立的组件实现（admin-classes-view / grade-classes-view / my-classes-grid），而非通过配置驱动同一套组件
违反规则：可扩展性（采用配置驱动设计，通过角色配置决定渲染哪些 Widget）
后果：新增角色需复制整套组件；三套组件存在大量重复代码

三、行业差距对比

3.1 与优秀 K12 产品的差距（v2 更新）

功能/交互	行业优秀实践	当前状态	影响
i18n 完整覆盖	所有角色所有页面支持多语言	school 模块 ✅，classes 模块 ❌（13/14 组件硬编码）	classes 模块无法支持多语言
错误边界	每个数据区块独立 Error Boundary	school 模块 ✅，classes 模块 ❌	classes 数据加载失败整页崩溃
骨架屏	加载时保持布局稳定	school 模块 ✅，classes 模块 ❌	classes 加载过程布局跳动
组件复用	三个角色共用一套可配置组件	三套独立组件（admin/grade/teacher）	代码重复，维护成本高
班级详情仪表盘	一页聚合基本信息 + 学生 + 课表 + 作业 + 成绩	`teacher/classes/my/[id]` 已有，但 admin/grade 视角无	admin/年级组长无法下钻
批量操作	批量导入学生、批量分配教师	✅ 已实现（v1 P2-4 修复）	已达标
年级升级	学年末一键升级	✅ 已实现（v1 P2-3 修复）	已达标
组织树导航	学校→年级→班级三级树	✅ 已实现（v1 P2-2 修复）	已达标
邀请码加入	6 位码 + 有效期 + 次数	✅ 已实现	已达标
数据权限隔离	data-access 层结合用户权限过滤	✅ 已实现（v1 P1-6 修复）	已达标

3.2 多角色体验差距

角色	优秀实践	当前状态
admin	统一管理面板，i18n 完整，错误边界完整	school 模块 ✅，classes 模块 ❌（无 i18n、无 Error Boundary）
teacher	我的班级 + 邀请码 + 课表 + 学生，i18n 完整	有基本功能，但 ❌ 无 i18n、❌ 无 Error Boundary
grade_head	年级班级管理 + 学情洞察，i18n 完整	有基本功能，但 ❌ 组件无 i18n
parent	查看孩子所在班级信息	无专属页面（依赖 dashboard 间接展示）
student	查看我的班级、同学名单、课表	有基本功能，但 ❌ 无 i18n

四、改进优先级建议

P0（紧急 — i18n 与错误处理）

编号	问题	改进方向
P0-A	classes 模块 13/14 个组件未接入 i18n	为所有 classes 组件接入 `useTranslations("classes")`，提取全部硬编码文本到翻译键
P0-B	classes.json i18n 文件内容不足	扩充 `classes.json`，覆盖班级 CRUD、列表、筛选器、详情页、学生管理、课表、详情子组件等全部场景

P1（重要 — 代码质量与可维护性）

编号	问题	改进方向
P1-A	`grades-view.tsx` 860 行	拆分为 `GradeListSection` + `GradeOverviewSection` + `GradeFormDialog` + `GradeDeleteDialog` + `GradePromoteDialog` + `use-grade-data` hook
P1-B	`classes/data-access.ts` 833 行	将邀请码相关函数迁移至 `data-access-invitations.ts`，将教师班级管理迁移至 `data-access-teacher.ts`
P1-C	classes 模块缺少 Error Boundary/Skeleton	新增 `class-error-boundary.tsx` + `class-skeleton.tsx`，为所有 classes 页面包裹
P1-D	classes 组件未使用组合模式	将 `admin-classes-view` / `grade-classes-view` / `my-classes-grid` 拆分为可复用的 `ClassListTable` + `ClassFormDialog` + `ClassDeleteDialog` + `ClassListToolbar`
P1-E	classes 模块缺少 hooks	抽取 `use-class-data` hook（对话框状态管理）+ `use-class-filters` hook（筛选逻辑）

P2（优化 — 架构模式）

编号	问题	改进方向
P2-A	缺少 Service 接口抽象	定义 `SchoolService` / `ClassService` 接口，通过 Context DI 注入（中长期）
P2-B	缺少角色配置驱动	建立 `CLASS_ROLE_CONFIG`，通过配置决定不同角色渲染哪些 Widget（中长期）

五、架构图同步说明

5.1 需更新的节点

文档	需更新内容
`004_architecture_impact_map.md` §2.7 classes	更新组件 i18n 状态（❌ → ✅）、更新 Error Boundary 状态（❌ → ✅）、更新组合模式状态、更新文件行数
`004_architecture_impact_map.md` §2.8 school	更新 `grades-view.tsx` 行数（860 → 拆分后）、更新组件拆分情况
`005_architecture_data.json`	更新 classes 模块的 i18n/errorBoundary/composition 状态标记

5.2 实施后同步

本次审计实施后，需同步更新：

classes 模块的 i18n 接入状态
classes 模块的 Error Boundary/Skeleton 新增
grades-view.tsx 拆分后的文件清单
classes/data-access.ts 拆分后的文件清单
classes 组件拆分后的文件清单

附录：审计检查清单（v2）

检查项	school	classes	状态
三层架构划分合理	✅	✅	v1 已修复
文件大小符合规范	⚠️ grades-view 860 行	⚠️ data-access 833 行	P1-A/P1-B
无跨模块直接依赖	✅	✅	v1 已修复
Server Action 权限校验	✅	✅	v1 已修复
前端无 role 硬编码	✅	✅	v1 已修复
i18n 适配	✅	❌ 13/14 组件未接入	P0-A/P0-B
错误处理/边界	✅	❌ 无 Error Boundary	P1-C
骨架屏/空状态	✅	⚠️ 有空状态无骨架屏	P1-C
逻辑与 UI 分离	✅ use-school-data	❌ 无 hooks	P1-E
组合模式	✅	❌ 三套单体组件	P1-D
配置驱动	❌	❌	P2-B（中长期）
审计日志完整	✅	✅	v1 已修复
监控埋点接口	❌	❌	P2（中长期）

17 KiB Raw Blame History Unescape Escape

学校/年级/班级管理模块审计报告 v2

一、现有实现概要

1.1 v1 审计修复回顾

1.2 当前模块文件分布

1.3 页面分布（共 13 个 page.tsx）

1.4 数据流概要

二、现存问题与原因分析（v2 新发现）

2.1 国际化层面

P0-A：classes 模块 13/14 个组件未接入 i18n

P0-B：classes.json i18n 文件内容严重不足

2.2 文件大小层面

P1-A：grades-view.tsx 860 行超出组件行数限制

P1-B：classes/data-access.ts 833 行超出 data-access 限制

2.3 错误处理层面

P1-C：classes 模块组件缺少 Error Boundary 和 Skeleton

2.4 组件质量层面

P1-D：classes 组件未使用组合模式

P1-E：classes 模块缺少 hooks 抽取

2.5 架构模式层面

P2-A：缺少 Service 接口抽象和依赖注入

P2-B：缺少角色配置驱动设计

三、行业差距对比

3.1 与优秀 K12 产品的差距（v2 更新）

3.2 多角色体验差距

四、改进优先级建议

P0（紧急 — i18n 与错误处理）

P1（重要 — 代码质量与可维护性）

P2（优化 — 架构模式）

五、架构图同步说明

5.1 需更新的节点

5.2 实施后同步

附录：审计检查清单（v2）

17 KiB

Raw Blame History

P1-A：`grades-view.tsx` 860 行超出组件行数限制

P1-B：`classes/data-access.ts` 833 行超出 data-access 限制