diff --git a/docs/architecture/004_architecture_impact_map.md b/docs/architecture/004_architecture_impact_map.md index 41f2117..428de86 100644 --- a/docs/architecture/004_architecture_impact_map.md +++ b/docs/architecture/004_architecture_impact_map.md @@ -654,7 +654,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" **导出函数**： - Actions（14 个，均为写操作；读操作由 RSC 页面直接调用 data-access）：`createTextbookAction` / `updateTextbookAction` / `deleteTextbookAction` / `createChapterAction` / `updateChapterContentAction` / `deleteChapterAction` / `reorderChaptersAction` / `createKnowledgePointAction` / `updateKnowledgePointAction` / `deleteKnowledgePointAction` / `getKnowledgePointsByChapterAction` / `getKnowledgeGraphDataAction`（✅ Task 7 新增：知识图谱数据查询，支持 structure/student-mastery/class-mastery 三种视图）/ `createPrerequisiteAction`（✅ Task 7 新增：声明前置依赖，含循环检测）/ `deletePrerequisiteAction`（✅ Task 7 新增：删除前置依赖） -- Data-access：`getTextbooks` / `getTextbookById` / `getChaptersByTextbookId` / `getKnowledgePointsByChapterId` / `getKnowledgePointsByTextbookId` / `createTextbook` / `updateTextbook` / `deleteTextbook` / `createChapter` / `updateChapterContent` / `deleteChapter` / `createKnowledgePoint` / `updateKnowledgePoint` / `deleteKnowledgePoint` / `reorderChapters` / `getTextbooksDashboardStats` / `getKnowledgePointOptions`（跨模块接口，供 questions 调用）/ `getTextbooksWithScope`（P1-1 新增：按数据范围获取教材列表，学生端强制按年级过滤）/ `verifyChapterBelongsToTextbook`（P0-4 新增：资源归属校验）/ `verifyKnowledgePointBelongsToTextbook`（P0-4 新增：资源归属校验）/ `createPrerequisite`（✅ Task 7 新增：创建前置依赖）/ `deletePrerequisite`（✅ Task 7 新增：删除前置依赖）/ `getPrerequisiteEdgesForTextbook`（✅ Task 7 新增：获取教材下所有前置依赖边，用于循环检测）/ `getSubjectLabelKey` / `getGradeLabelKey`（i18n 标签键） +- Data-access：`getTextbooks` / `getTextbookById` / `getChaptersByTextbookId` / `getKnowledgePointsByChapterId` / `getKnowledgePointsByTextbookId` / `createTextbook` / `updateTextbook` / `deleteTextbook` / `createChapter` / `updateChapterContent` / `deleteChapter` / `createKnowledgePoint` / `updateKnowledgePoint` / `deleteKnowledgePoint` / `reorderChapters` / `getTextbooksDashboardStats` / `getKnowledgePointOptions`（跨模块接口，供 questions 调用）/ `getTextbooksWithScope`（P1-1 新增：按数据范围获取教材列表，学生端强制按年级过滤）/ `verifyChapterBelongsToTextbook`（P0-4 新增：资源归属校验）/ `verifyKnowledgePointBelongsToTextbook`（P0-4 新增：资源归属校验）/ `verifyKnowledgePointBelongsToChapter`（P0-4 新增：校验知识点是否属于指定章节）/ `createPrerequisite`（✅ Task 7 新增：创建前置依赖）/ `deletePrerequisite`（✅ Task 7 新增：删除前置依赖）/ `getPrerequisiteEdgesForTextbook`（✅ Task 7 新增：获取教材下所有前置依赖边，用于循环检测）/ `getSubjectLabelKey` / `getGradeLabelKey`（i18n 标签键） - Data-access-graph（✅ Task 5 新增，图谱只读查询）：`getKnowledgePointsWithRelations`（知识点+依赖+题目数聚合查询）/ `getStudentKpMastery`（学生掌握度）/ `getClassKpMastery`（班级平均掌握度）/ `getPrerequisitesForKp` / `getSuccessorsForKp` - Constants（✅ 新增）：`SUBJECTS` / `GRADES` / `SUBJECT_COLORS` / `getSubjectColor` / `getSubjectLabelKey` / `getGradeLabelKey` - ✅ v1 测试修复：`SUBJECTS` 新增 `Chinese` 学科、`GRADES` 新增 `Grade 1`/`Grade 2`，与 seed 数据对齐 @@ -693,25 +693,28 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" **文件清单**： | 文件 | 行数 | 职责 | |------|------|------| -| `actions.ts` | 502 | 14 个 Server Action（写操作，含 Zod 校验 + 资源归属校验 + 知识图谱查询/前置依赖管理） | -| `data-access.ts` | 586 | 教材/章节/知识点 CRUD + 跨模块查询接口 + 资源归属校验 + 数据范围过滤 + 前置依赖 CRUD | -| `data-access-graph.ts` | 184 | 知识图谱只读查询（✅ Task 5 新增：知识点关联聚合、学生/班级掌握度、前置后置知识点，标记 `server-only`） | -| `types.ts` | 94 | 类型定义（含知识图谱类型：GraphViewMode/MasteryInfo/KpWithRelations/GraphNodeData/GraphEdgeData/KnowledgeGraphData/MasteryLevel） | -| `schema.ts` | 62 | Zod 校验（含 CreatePrerequisiteSchema/DeletePrerequisiteSchema） | -| `constants.ts` | 99 | 学科/年级常量与颜色映射（✅ 新增；v1 测试修复：新增 Chinese/Grade 1/Grade 2） | -| `utils.ts` | 203 | 章节树构建/排序/查找等纯函数 + 循环检测（✅ 新增，含单测） | -| `graph-layout.ts` | 105 | 知识图谱布局计算纯函数（✅ Task 8 重写为 dagre 集成，输出 React Flow 格式，含单测） | +| `actions.ts` | 515 | 14 个 Server Action（写操作，含 Zod 校验 + 资源归属校验 + 知识图谱查询/前置依赖管理 + class-mastery 视图） | +| `data-access.ts` | 662 | 教材/章节/知识点 CRUD + 跨模块查询接口 + 资源归属校验 + 数据范围过滤 + 前置依赖 CRUD | +| `data-access-graph.ts` | 207 | 知识图谱只读查询（✅ Task 5 新增：知识点关联聚合、学生/班级掌握度、前置后置知识点，标记 `server-only`；v2 修复：前置依赖双向 IN 过滤防跨教材污染） | +| `types.ts` | 106 | 类型定义（含知识图谱类型：GraphViewMode/MasteryInfo/KpWithRelations/GraphNodeData/GraphEdgeData/KnowledgeGraphData/MasteryLevel） | +| `schema.ts` | 81 | Zod 校验（含 CreatePrerequisiteSchema/DeletePrerequisiteSchema；v2 修复：refine 消息改为英文） | +| `constants.ts` | 96 | 学科/年级常量与颜色映射（✅ 新增；v1 测试修复：新增 Chinese/Grade 1/Grade 2） | +| `utils.ts` | 225 | 章节树构建/排序/查找等纯函数 + 循环检测（✅ 新增，含单测） | +| `graph-layout.ts` | 121 | 知识图谱布局计算纯函数（✅ Task 8 重写为 dagre 集成，输出 React Flow 格式，含单测） | | `analytics.tsx` | 43 | 教材分析 Context/Provider/Hook（✅ 新增） | -| `hooks/use-knowledge-point-actions.ts` | 121 | 知识点操作 Hook | +| `hooks/use-knowledge-point-actions.ts` | 49 | 知识点操作门面 Hook（v2 拆分：组合 useKpDialogState + useKpCrud，对外 API 不变） | +| `hooks/use-kp-dialog-state.ts` | 38 | 知识点对话框状态管理 Hook（v2 新增：从 use-knowledge-point-actions 拆分） | +| `hooks/use-kp-crud.ts` | 122 | 知识点 CRUD 操作 Hook（v2 新增：从 use-knowledge-point-actions 拆分） | | `hooks/use-text-selection.ts` | 57 | 文本选区捕获 Hook | -| `hooks/use-graph-data.ts` | 58 | 知识图谱数据加载 Hook（✅ Task 11 新增：派生值模式避免 effect 中 setState） | -| `components/teacher-textbook-reader.tsx` | 41 | 教师端 TextbookReader 客户端包装（✅ v1 测试修复：解决 Server→Client 函数 prop 序列化问题） | -| `components/knowledge-graph.tsx` | 249 | React Flow 知识图谱主组件（✅ Task 10/15 重写：全书视图 + 搜索高亮 + 关联节点高亮 + 章节着色） | -| `components/graph-kp-node.tsx` | 80 | React Flow 自定义节点（✅ Task 9 新增：知识点名称+题目数徽章+掌握度进度条） | -| `components/graph-prerequisite-edge.tsx` | 40 | React Flow 自定义边（✅ Task 9 新增：虚线+箭头表示前置依赖） | -| `components/graph-toolbar.tsx` | 77 | 图谱工具栏（✅ Task 9 新增：视图模式切换 + 搜索 + 重置视图） | -| `components/graph-node-detail-panel.tsx` | 171 | 节点详情侧边面板（✅ Task 13 新增：描述/掌握度/关联题目/前置后置列表） | -| `components/*` | 17 文件 | 教材编辑/知识图谱组件（新增 `section-error-boundary.tsx`、`teacher-textbook-reader.tsx`、5 个 graph-* 组件） | +| `hooks/use-graph-data.ts` | 76 | 知识图谱数据加载 Hook（✅ Task 11 新增：派生值模式避免 effect 中 setState；v2 修复：区分 isLoading/isRefreshing 避免 UI 闪烁） | +| `components/knowledge-graph.tsx` | 376 | React Flow 知识图谱主组件（✅ Task 10/15 重写：全书视图 + 搜索高亮 + 关联节点高亮 + 章节着色；v2 新增：添加/删除前置依赖 Dialog） | +| `components/graph-kp-node.tsx` | 92 | React Flow 自定义节点（✅ Task 9 新增：知识点名称+题目数徽章+掌握度进度条；v2 修复：节点宽度常量化 NODE_WIDTH） | +| `components/graph-prerequisite-edge.tsx` | 48 | React Flow 自定义边（✅ Task 9 新增：虚线+箭头表示前置依赖；v2 修复：GraphEdgeData 类型安全转换） | +| `components/graph-toolbar.tsx` | 93 | 图谱工具栏（✅ Task 9 新增：视图模式切换 + 搜索 + 重置视图；v2 新增：isRefreshing 轻量指示器） | +| `components/graph-node-detail-panel.tsx` | 181 | 节点详情侧边面板（✅ Task 13 新增：描述/掌握度/关联题目/前置后置列表；v2 修复：移除未使用 textbookId prop） | +| `components/chapter-sidebar-list.tsx` | 342 | 章节侧边栏列表（v2 修复：canEdit 默认 false + orderUpdateFailed i18n key） | +| `components/section-error-boundary.tsx` | 71 | 章节内容错误边界（v2 修复：默认值改为空字符串 + 条件渲染） | +| `components/*` | 16 文件 | 教材编辑/知识图谱组件（新增 `section-error-boundary.tsx`、5 个 graph-* 组件；`teacher-textbook-reader.tsx` 已移至 app 层） | --- @@ -723,7 +726,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" - Actions：`getGradeRecordsAction` / `createGradeRecordAction` / `updateGradeRecordAction` / `deleteGradeRecordAction` / `exportGradesAction` / `getGradeTrendAction` / `getClassComparisonAction` / `getSubjectComparisonAction` / `getGradeDistributionAction` / `getClassRankingAction` / `getRankingTrendAction` / `getGradeRecordByIdAction` / `getClassGradeStatsAction` / `getStudentGradeSummaryAction` / `batchCreateGradeRecordsAction` / `assertClassInScope`（✅ P3 新增导出：班级 scope 校验工具，供 actions-analytics 复用）/ `saveGradeDraftAction` / `getGradeDraftAction` / `deleteGradeDraftAction`（✅ v3-P2 新增：成绩录入草稿 Server Actions，分别使用 GRADE_RECORD_MANAGE/GRADE_RECORD_READ/GRADE_RECORD_MANAGE 权限） - Data-access：`getGradeRecords` / `getStudentGradeSummary` / `getClassRanking` / `getClassStudentsForEntry` / `getClassGradeStats` / `getClassGradeStatsWithMeta` / `getGradeTrend` / `getClassComparison` / `getSubjectComparison` / `getGradeDistribution` / `getRankingTrend` / `PaginatedGradeRecords`（✅ P3 新增：分页结果接口 `{ records, total }`）/ `saveGradeDraft` / `getGradeDraft` / `deleteGradeDraft`（✅ v3-P2 新增：成绩录入草稿 CRUD，upsert + 24 小时过期）/ `getExamOptionsForGrades` / `getSchoolWideGradeSummary`（✅ v3-P2 新增：考试选项查询 + 全校各年级成绩汇总，管理员视图按年级聚合平均分/及格率/优秀率/学生数/班级数，加权平均计算全校汇总） - Types（✅ v3-P2 新增）：`SchoolWideGradeSummaryItem`（全校汇总按年级聚合项：gradeId/gradeName/schoolName/classCount/studentCount/averageScore/passRate/excellentRate/recordCount）/ `SchoolWideGradeSummary`（全校汇总：grades 数组 + totals 汇总对象）/ `GradeDraftData`（草稿数据接口：{ scores: Record, timestamp: number }，位于 data-access.ts） -- Lib（✅ P1-2 新增，✅ P3 更新签名）：`toNumber` / `normalize` / `buildScopeClassFilter(scope, currentUserId?)`（P3 修复：`class_members` scope 内置 studentId 过滤，需传入 currentUserId 参数） +- Lib（✅ P1-2 新增，✅ P3 更新签名，✅ P3-26 拆分）：`toNumber` / `normalize`（位于 `lib/grade-utils.ts`）；`buildScopeClassFilter(scope, currentUserId?)`（P3-26 从 grade-utils.ts 迁移至 `lib/scope-filter.ts`，P3 修复：`class_members` scope 内置 studentId 过滤，需传入 currentUserId 参数） - 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 属性）/ `SchoolWideSummaryCard`（✅ v3-P2 新增：管理员全校成绩汇总卡片，4 个统计卡片 + 各年级对比表格） @@ -763,6 +766,11 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" - ✅ v3-P2 改进（2026-06-23）：`getGradeTrend`/`getGradeDistribution`/`getSubjectComparison`/`getClassComparison` 均新增 `semester` 和 `examId` 可选参数，支持按学期和考试筛选分析 - ✅ v3-P2 改进（2026-06-23）：新增 `getSchoolWideGradeSummary` data-access 函数 + `SchoolWideSummaryCard` 组件 + `SchoolWideGradeSummary`/`SchoolWideGradeSummaryItem` 类型，管理员全校成绩汇总视图（按年级聚合平均分/及格率/优秀率/学生数/班级数，加权平均计算全校汇总）；admin/school/grades/insights/page.tsx 顶部新增 SchoolWideSummaryCard - ✅ v3-P2 改进（2026-06-23）：parent/grades/page.tsx 为每个子女并行查询 `getClassAverageTrend`，渲染 GradeTrendCard +- ✅ P3 修复（2026-06-23）：~~`lib/grade-utils.ts` 72 行超 40 行工具函数上限~~ P3-26 将 `buildScopeClassFilter` 迁移至 `lib/scope-filter.ts`，grade-utils.ts 仅保留 toNumber/normalize（20 行） +- ✅ P3 修复（2026-06-23）：~~`stats-service.ts` createDefaultBuckets 不必要导出~~ P3-10 移除 export 关键字，改为内部函数 +- ✅ P3 修复（2026-06-23）：~~`stats-service.ts` buildGradeTrendPoints 使用 as 断言~~ P3-24 新增 isGradeTrendType 类型守卫函数替代 as 断言 +- ✅ P3 修复（2026-06-23）：~~`export.ts` 局部 avg 函数与 stats-service.computeAverageScore 重复~~ P3-6 删除局部 avg，复用 computeAverageScore +- ✅ P3 修复（2026-06-23）：~~`export.ts` TYPE_LABELS 硬编码中文~~ P3-7 改用 next-intl getTranslations，新增 export.sheets/columns/metrics i18n 键（zh-CN/en 同步） **文件清单**： | 文件 | 行数 | 职责 | @@ -772,10 +780,11 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | `data-access.ts` | 428+ | 成绩 CRUD + 统计 + 草稿（含 v2-P2-9 修复：recorderName 批量查询；P3 修复：PaginatedGradeRecords 接口 + DB 层分页 + 事务 + 存在性检查 + scope 过滤 + 并列排名；v3-P2 新增：saveGradeDraft/getGradeDraft/deleteGradeDraft + GradeDraftData 接口） | | `data-access-analytics.ts` | 200+ | 趋势/对比分析（P3 修复：getClassComparison 应用 buildScopeClassFilter；v3-P2 新增：getExamOptionsForGrades/getSchoolWideGradeSummary；getGradeTrend/getClassComparison/getSubjectComparison/getGradeDistribution 新增 semester/examId 可选参数） | | `data-access-ranking.ts` | 83 | 排名查询（P3 修复：getRankingTrend 接受 scope 参数 + class_taught 校验） | -| `stats-service.ts` | 279 | 统计计算纯函数（P1-1 新增：8 个纯函数 + 2 个常量 + 2 个接口） | -| `export.ts` | 189 | Excel 导出（v2-P1-5 修复：传递 currentUserId 到 data-access；P3 修复：适配 PaginatedGradeRecords 结构 + 传递 scope） | +| `stats-service.ts` | 285 | 统计计算纯函数（P1-1 新增：8 个纯函数 + 2 个常量 + 2 个接口；P3-10：createDefaultBuckets 改为内部函数；P3-24：buildGradeTrendPoints 使用 isGradeTrendType 类型守卫替代 as 断言） | +| `export.ts` | 209 | Excel 导出（v2-P1-5 修复：传递 currentUserId 到 data-access；P3 修复：适配 PaginatedGradeRecords 结构 + 传递 scope；P3-6：复用 stats-service.computeAverageScore 替代局部 avg；P3-7：硬编码中文改用 next-intl getTranslations） | | `schema.ts` | 113+ | Zod 校验（含 12 个查询 schema；P3 修复：score .max(1000) + records .max(500) + 补全查询字段；v3-P2 新增：grade_drafts 表定义第 1444-1469 行） | -| `lib/grade-utils.ts` | 66 | 公共工具函数（toNumber/normalize/buildScopeClassFilter，v2-P2-2 修复：改用 classes data-access 子查询；P3 修复：buildScopeClassFilter 新增 currentUserId 参数） | +| `lib/grade-utils.ts` | 20 | 公共工具函数（toNumber/normalize；P3-26：buildScopeClassFilter 迁移至 scope-filter.ts） | +| `lib/scope-filter.ts` | 56 | DB 行级权限过滤（buildScopeClassFilter；P3-26 从 grade-utils.ts 迁移；v2-P2-2 修复：改用 classes data-access 子查询；P3 修复：新增 currentUserId 参数） | | `types.ts` | 168+ | 类型定义（v3-P2 新增：SchoolWideGradeSummaryItem/SchoolWideGradeSummary） | | `components/widget-boundary.tsx` | 136 | Widget 边界组件（P1-5 新增，v2-P1-1 已在 3 个页面应用） | | `components/school-wide-summary-card.tsx` | - | v3-P2 新增：管理员全校成绩汇总卡片（4 个统计卡片 + 各年级对比表格） | @@ -834,7 +843,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | `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-invitations.ts` | 502 | 邀请码与注册 + 批量操作（10 个 Action，P2-4 新增批量导入学生/批量分配教师） | | `actions-schedule.ts` | 90 | 班级课表 CRUD（3 个 Action） | | `actions-shared.ts` | 60 | 共享工具（hasAdminScope/hasTeacherScope/hasStudentScope/parseSubjectTeachers/toWeekday） | | `schema.ts` | 152 | Zod 校验（13 个 schema：教师/管理员/年级班级 CRUD + 课表 CRUD + 邮箱注册） | @@ -847,8 +856,8 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" **职责**：学校/学年/部门/年级的 CRUD。 **导出函数**： -- Actions：`createSchoolAction` / `updateSchoolAction` / `deleteSchoolAction` / `createAcademicYearAction` / `updateAcademicYearAction` / `deleteAcademicYearAction` / `createDepartmentAction` / `updateDepartmentAction` / `deleteDepartmentAction` / `createGradeAction` / `updateGradeAction` / `deleteGradeAction`（编排层：权限校验 + Zod 校验 + 调用 data-access + revalidatePath + after(logAudit)） -- Data-access：只读查询（`getSchools` / `getGrades` / `getDepartments` / `getAcademicYears` / `getStaffOptions` / `getGradesForStaff`）+ 写操作（`create/update/delete` × `Department/School/Grade/AcademicYear`） +- Actions：`createSchoolAction` / `updateSchoolAction` / `deleteSchoolAction` / `createAcademicYearAction` / `updateAcademicYearAction` / `deleteAcademicYearAction` / `createDepartmentAction` / `updateDepartmentAction` / `deleteDepartmentAction` / `createGradeAction` / `updateGradeAction` / `deleteGradeAction` / `promoteGradesAction`（编排层：权限校验 + Zod 校验 + 调用 data-access + revalidatePath + after(logAudit)；`promoteGradesAction` 年级升级，审计日志 `grade.promote`） +- Data-access：只读查询（`getSchools` / `getGrades` / `getDepartments` / `getAcademicYears` / `getStaffOptions` / `getGradesForStaff` / `getOrgTree`）+ 写操作（`create/update/delete` × `Department/School/Grade/AcademicYear`）+ `promoteGrades(schoolId)` 年级升级（order +1 + 名称升级，辅助函数 `promoteGradeName`） **依赖关系**： - 依赖：`shared/*`、`@/auth`、`users`（⚠️ `getStaffOptions` 直查 users/roles，可接受） @@ -866,20 +875,25 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" - ✅ 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 分离 +- ✅ P2-2 修复（2026-06-23）：新增 `getOrgTree()` data-access 函数（学校→年级→班级三级树，通过 `import("@/modules/classes/data-access")` 动态导入获取班级数据避免循环依赖）+ `OrgTreeNode` 类型 + `OrgTreeNav` 组件（三级树形导航，支持搜索过滤/选中高亮/展开折叠/不同节点类型图标）；school.json 补充 `orgTree.*` 翻译键 +- ✅ P2-3 修复（2026-06-23）：新增 `promoteGradesAction` + `promoteGrades(schoolId)` + `promoteGradeName(name)` 辅助函数（中文数字 一→二…十二、阿拉伯数字 1→2…12 识别），按 order 降序逐条 +1 避免唯一约束冲突；含 `after(() => logAudit({ action: "grade.promote" }))` 审计日志 +- ✅ P2-4 修复（2026-06-23）：新增 `bulkEnrollStudentsAction`（CSV 批量导入学生，复用 enrollStudentByEmail）+ `bulkAssignSubjectTeachersAction`（CSV 批量分配教师，简化实现含 TODO 待完善查找逻辑）；classes/actions.ts barrel 导出 +- ✅ P2-5 修复（2026-06-23）：为 department/academicYear/grade 的 9 个 CRUD Action 补充 `after(() => logAudit(...))` 审计日志（action: department.create/update/delete、academicYear.create/update/delete、grade.create/update/delete），与 school 实体审计日志策略一致 **文件清单**： | 文件 | 行数 | 职责 | |------|------|------| -| `actions.ts` | 349 | 12 个 Server Action（编排层，无 DB 直访） | -| `data-access.ts` | 504+ | 只读查询 + 12 个写操作 + 跨模块查询接口 + 权限感知函数（getSchoolsForUser/getGradesForUser） | -| `schema.ts` | 51 | Zod 校验 | -| `types.ts` | 96 | 类型定义（含 Insert/Update 入参类型） | +| `actions.ts` | 457 | 13 个 Server Action（编排层，无 DB 直访；含 `promoteGradesAction` 年级升级） | +| `data-access.ts` | 782 | 只读查询 + 12 个写操作 + `promoteGrades` 年级升级 + `getOrgTree` 组织架构树 + 跨模块查询接口 + 权限感知函数（getSchoolsForUser/getGradesForUser） | +| `schema.ts` | 56 | Zod 校验（含 `PromoteGradesSchema`） | +| `types.ts` | 103 | 类型定义（含 Insert/Update 入参类型 + `OrgTreeNode`） | | 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 修复） | +| components/org-tree-nav.tsx | 134 | 学校→年级→班级三级树形导航（P2-2 修复：搜索过滤 + 选中高亮 + 展开折叠 + 节点类型图标） | | hooks/use-school-data.ts | 40 | 学校数据管理 hook（P2-1 修复） | --- @@ -1153,7 +1167,7 @@ src/auth.ts ──▶ import { ... } from "@/shared/lib/permissions" | 文件 | 行数 | 职责 | |------|------|------| | `dispatcher.ts` | 152 | 渠道选择 + 并行分发 | -| `data-access.ts` | 177 | 站内通知 CRUD + 用户联系方式 + 日志（P0-4 / P1-5 修复后新增通知 CRUD） | +| `data-access.ts` | 212 | 站内通知 CRUD + 用户联系方式 + 发送日志持久化（notification_logs 表；P0-4 / P1-5 修复后新增通知 CRUD） | | `preferences.ts` | 166 | 通知偏好 CRUD（P0-4 / P1-5 修复后从 messaging 迁移） | | `actions.ts` | ~260 | 6 个 Server Action（✅ P1-4：新增 4 个通知 CRUD Action） | | `types.ts` | 120 | 通知负载 + 渠道配置 + 通知记录 + 偏好类型（P0-4 / P1-5 修复后扩充） | @@ -2329,7 +2343,7 @@ shared/lib/{audit-logger, change-logger, auth-guard} → @/auth → shared/lib/* | `getRankingTrend` | `data-access-ranking.ts` | `(studentId, subjectId?, semester?) => Promise` | `(studentId, subjectId?, semester?, scope?: DataScope) => Promise`（class_taught scope 校验） | **lib 层签名变更**： -- `buildScopeClassFilter(scope: DataScope, currentUserId?: string): SQL | null`（新增 `currentUserId` 参数，`class_members` scope 内置 `eq(gradeRecords.studentId, currentUserId)` 过滤） +- `buildScopeClassFilter(scope: DataScope, currentUserId?: string): SQL | null`（新增 `currentUserId` 参数，`class_members` scope 内置 `eq(gradeRecords.studentId, currentUserId)` 过滤；P3-26：从 `lib/grade-utils.ts` 迁移至 `lib/scope-filter.ts`） **新增导出**： - `assertClassInScope(scope: DataScope, classId: string): string | null`（`actions.ts`，校验 classId 是否在 scope 允许范围内，供 actions.ts 与 actions-analytics.ts 复用） diff --git a/docs/architecture/005_architecture_data.json b/docs/architecture/005_architecture_data.json index dc6351e..7597cc4 100644 --- a/docs/architecture/005_architecture_data.json +++ b/docs/architecture/005_architecture_data.json @@ -4625,11 +4625,29 @@ "textbook-content-panel.tsx" ] }, + { + "name": "useKpDialogState", + "file": "hooks/use-kp-dialog-state.ts", + "signature": "() => { editingKp, setEditingKp, editKpDialogOpen, setEditKpDialogOpen, isUpdatingKp, setIsUpdatingKp, questionDialogOpen, setQuestionDialogOpen, targetKpForQuestion, setTargetKpForQuestion, deleteConfirmOpen, setDeleteConfirmOpen, pendingDeleteKpId, setPendingDeleteKpId }", + "purpose": "知识点对话框状态管理 Hook（编辑/题目/删除确认），从 use-knowledge-point-actions 拆分", + "usedBy": [ + "hooks/use-knowledge-point-actions.ts" + ] + }, + { + "name": "useKpCrud", + "file": "hooks/use-kp-crud.ts", + "signature": "(args: UseKpCrudArgs) => { handleCreateKnowledgePoint, requestDeleteKnowledgePoint, confirmDeleteKnowledgePoint, handleUpdateKnowledgePoint }", + "purpose": "知识点 CRUD 操作 Hook，依赖 useKpDialogState 提供的状态，从 use-knowledge-point-actions 拆分", + "usedBy": [ + "hooks/use-knowledge-point-actions.ts" + ] + }, { "name": "useKnowledgePointActions", "file": "hooks/use-knowledge-point-actions.ts", "signature": "(textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated?) => { editingKp, setEditingKp, editKpDialogOpen, setEditKpDialogOpen, isUpdatingKp, questionDialogOpen, setQuestionDialogOpen, targetKpForQuestion, setTargetKpForQuestion, deleteConfirmOpen, setDeleteConfirmOpen, handleCreateKnowledgePoint, requestDeleteKnowledgePoint, confirmDeleteKnowledgePoint, handleUpdateKnowledgePoint }", - "purpose": "知识点操作Hook(6参数)", + "purpose": "知识点操作门面 Hook（组合 useKpDialogState + useKpCrud，对外保持原有 API 不变）", "usedBy": [ "textbook-reader.tsx" ] @@ -4637,8 +4655,8 @@ { "name": "useGraphData", "file": "hooks/use-graph-data.ts", - "signature": "(textbookId: string, viewMode: GraphViewMode) => { data: KnowledgeGraphData | null, isLoading: boolean, error: string | null, reload: () => void }", - "purpose": "Task 11 新增：知识图谱数据加载 Hook，按 textbookId + viewMode 加载，使用派生值模式避免 effect 中 setState", + "signature": "(textbookId: string, viewMode: GraphViewMode) => { data: KnowledgeGraphData | null, isLoading: boolean, isRefreshing: boolean, error: string | null, reload: () => void }", + "purpose": "Task 11 新增：知识图谱数据加载 Hook，按 textbookId + viewMode 加载，使用派生值模式避免 effect 中 setState。区分 isLoading（首次加载）和 isRefreshing（切换模式刷新，保留旧数据避免 UI 闪烁）", "usedBy": [ "components/knowledge-graph.tsx" ] @@ -4975,42 +4993,51 @@ "name": "TextbookReader", "purpose": "教材阅读器" }, - { - "name": "TeacherTextbookReader", - "purpose": "教师端 TextbookReader 客户端包装（v1 测试修复：解决 Server→Client 函数 prop 序列化问题）" - }, { "name": "TextbookSettingsDialog", "purpose": "教材设置对话框" } ], "uiDeps": [], - "uiDepsNote": "已通过 render prop 解耦，不再直接 import questions 模块组件", + "uiDepsNote": "已通过 render prop 解耦，TeacherTextbookReader 已移至 app 层（src/app/(dashboard)/teacher/textbooks/[id]/_components/），textbooks 模块不再直接 import questions 模块组件", "knownIssues": [ - "i18n 覆盖率约 95%（chapter-sidebar-list 已接入，actions.ts 已接入，section-error-boundary 默认值已改英文）", + "i18n 覆盖率约 98%（chapter-sidebar-list/actions.ts/section-error-boundary/8 处硬编码英文 toast 已全部接入，Zod refine 消息改为英文，错误分支不再复用成功消息）", "类型断言残留 3 处 as string", "P2 图谱方向键导航未实现", - "v1 测试已修复：textbook-reader.tsx SheetTrigger 越界、Server→Client 函数 prop 序列化、seed 数据 i18n key 不匹配" + "v1 测试已修复：textbook-reader.tsx SheetTrigger 越界、Server→Client 函数 prop 序列化、seed 数据 i18n key 不匹配", + "v2 核查修复：class-mastery 视图模式已实现、跨教材前置依赖双向 IN 过滤、ChapterSidebarList canEdit 默认 false、isTeacher 冗余变量移除、graph-kp-node 节点宽度常量化、GraphNodeDetailPanel textbookId 未使用 prop 移除、use-knowledge-point-actions 拆分为门面+状态+CRUD 三 Hook、use-graph-data 区分 isLoading/isRefreshing 避免 UI 闪烁、TeacherTextbookReader 移至 app 层解耦跨模块依赖" ], "files": { - "actions.ts": 502, - "data-access.ts": 586, - "data-access-graph.ts": 184, - "types.ts": 94, - "schema.ts": 62, - "constants.ts": 99, - "utils.ts": 203, - "graph-layout.ts": 105, + "actions.ts": 515, + "data-access.ts": 662, + "data-access-graph.ts": 207, + "types.ts": 106, + "schema.ts": 81, + "constants.ts": 96, + "utils.ts": 225, + "graph-layout.ts": 121, "analytics.tsx": 43, - "hooks/use-knowledge-point-actions.ts": 121, + "hooks/use-knowledge-point-actions.ts": 49, + "hooks/use-kp-dialog-state.ts": 38, + "hooks/use-kp-crud.ts": 122, "hooks/use-text-selection.ts": 57, - "hooks/use-graph-data.ts": 58, - "components/teacher-textbook-reader.tsx": 41, - "components/knowledge-graph.tsx": 249, - "components/graph-kp-node.tsx": 80, - "components/graph-prerequisite-edge.tsx": 40, - "components/graph-toolbar.tsx": 77, - "components/graph-node-detail-panel.tsx": 171 + "hooks/use-graph-data.ts": 76, + "components/chapter-sidebar-list.tsx": 342, + "components/create-chapter-dialog.tsx": 111, + "components/graph-kp-node.tsx": 92, + "components/graph-node-detail-panel.tsx": 181, + "components/graph-prerequisite-edge.tsx": 48, + "components/graph-toolbar.tsx": 93, + "components/knowledge-graph.tsx": 376, + "components/knowledge-point-dialogs.tsx": 175, + "components/knowledge-point-list.tsx": 122, + "components/section-error-boundary.tsx": 71, + "components/textbook-card.tsx": 181, + "components/textbook-content-panel.tsx": 189, + "components/textbook-filters.tsx": 71, + "components/textbook-form-dialog.tsx": 139, + "components/textbook-reader.tsx": 446, + "components/textbook-settings-dialog.tsx": 203 }, "auditReport": "audit/textbooks-audit-report.md" } @@ -5963,8 +5990,8 @@ }, { "path": "actions-invitations.ts", - "lines": 280, - "description": "邀请码与注册（8 个 Action，P0-3 修复）" + "lines": 502, + "description": "邀请码与注册 + 批量操作（10 个 Action，P0-3 修复；P2-4 新增批量导入学生/批量分配教师）" }, { "path": "actions-schedule.ts", @@ -6022,6 +6049,13 @@ "signature": "(gradeId) => Promise>", "purpose": "删除年级" }, + { + "name": "promoteGradesAction", + "permission": "GRADE_MANAGE", + "signature": "(prevState, formData) => Promise>", + "purpose": "年级升级（order +1 + 名称升级）", + "auditLog": "grade.promote" + }, { "name": "createDepartmentAction", "permission": "SCHOOL_MANAGE", @@ -6401,6 +6435,15 @@ "usedBy": [ "updateAcademicYear" ] + }, + { + "name": "OrgTreeNode", + "type": "type", + "definition": "组织架构树节点（学校/年级/班级三级，P2-2 修复）", + "usedBy": [ + "getOrgTree", + "school/components/org-tree-nav.tsx" + ] } ], "components": [ @@ -6455,6 +6498,12 @@ "file": "components/school-skeleton.tsx", "purpose": "卡片加载骨架屏（animate-pulse）", "props": "" + }, + { + "name": "OrgTreeNav", + "file": "components/org-tree-nav.tsx", + "purpose": "学校→年级→班级三级树形导航（P2-2 修复）：搜索过滤 + 选中高亮 + 展开/折叠 + 不同节点类型图标（School/GraduationCap/Users）+ 默认展开第一级", + "props": "nodes: OrgTreeNode[], onSelect?: (node: OrgTreeNode) => void, selectedId?: string" } ], "hooks": [ @@ -8622,7 +8671,7 @@ "deps": [ "shared.db", "shared.db.schema.gradeRecords", - "grades/lib/grade-utils.buildScopeClassFilter" + "grades/lib/scope-filter.buildScopeClassFilter" ], "usedBy": [ "grades/data-access.getClassGradeStatsWithMeta" @@ -8664,7 +8713,7 @@ "shared.db", "shared.db.schema.gradeRecords", "shared.db.schema.users", - "grades/lib/grade-utils.buildScopeClassFilter", + "grades/lib/scope-filter.buildScopeClassFilter", "users/data-access.getUserNamesByIds" ], "usedBy": [ @@ -9368,11 +9417,12 @@ "name": "exportGradeRecordsToExcel", "signature": "(params: { classId: string; subjectId?: string; examId?: string; scope: DataScope; currentUserId?: string }) => Promise", "file": "export.ts", - "purpose": "导出成绩单（Sheet1 成绩明细，Sheet2 统计汇总：均分/中位数/最高分/最低分/标准差/及格率/优秀率/参考人数）（P3 更新：传递 scope/currentUserId 到 data-access）", + "purpose": "导出成绩单（Sheet1 成绩明细，Sheet2 统计汇总：均分/中位数/最高分/最低分/标准差/及格率/优秀率/参考人数）（P3 更新：传递 scope/currentUserId 到 data-access；P3-7：硬编码中文改用 next-intl getTranslations）", "deps": [ "shared.lib.excel.exportToExcel", "data-access.getGradeRecords", - "data-access.getClassGradeStats" + "data-access.getClassGradeStats", + "next-intl/server.getTranslations" ], "usedBy": [ "actions.exportGradesAction", @@ -9383,7 +9433,7 @@ "name": "exportClassGradeReportToExcel", "signature": "(params: { classId: string; scope: DataScope; currentUserId?: string }) => Promise", "file": "export.ts", - "purpose": "导出班级成绩总表（多科目横向对比，含总分/平均分/排名列）（P3 更新：适配 PaginatedGradeRecords 结构 + 传递 scope/currentUserId）", + "purpose": "导出班级成绩总表（多科目横向对比，含总分/平均分/排名列）（P3 更新：适配 PaginatedGradeRecords 结构 + 传递 scope/currentUserId；P3-6：复用 stats-service.computeAverageScore 替代局部 avg；P3-7：硬编码中文改用 next-intl getTranslations）", "deps": [ "shared.db", "shared.db.schema.classes", @@ -9391,7 +9441,9 @@ "shared.db.schema.gradeRecords", "shared.db.schema.users", "shared.lib.excel.exportToExcel", - "data-access.getGradeRecords" + "data-access.getGradeRecords", + "stats-service.computeAverageScore", + "next-intl/server.getTranslations" ], "usedBy": [ "actions.exportGradesAction" @@ -9440,8 +9492,8 @@ { "name": "buildScopeClassFilter", "signature": "(scope: DataScope, currentUserId?: string) => SQL | null", - "file": "lib/grade-utils.ts", - "purpose": "根据 DataScope 构建 gradeRecords 表的行级权限过滤条件（P1-2 新增：从 data-access/data-access-analytics 抽取；P3 更新：class_members scope 内置 studentId 过滤，需传入 currentUserId 参数）", + "file": "lib/scope-filter.ts", + "purpose": "根据 DataScope 构建 gradeRecords 表的行级权限过滤条件（P1-2 新增：从 data-access/data-access-analytics 抽取；P3 更新：class_members scope 内置 studentId 过滤，需传入 currentUserId 参数；P3-26：从 grade-utils.ts 迁移至 scope-filter.ts）", "usedBy": [ "data-access.getGradeRecords", "data-access.getClassGradeStats", @@ -9469,16 +9521,17 @@ "name": "computeAverageScore", "signature": "(scores: number[]) => number", "file": "stats-service.ts", - "purpose": "计算分数平均值（空数组返回 0）（P1-1 新增：从 data-access.getStudentGradeSummary 抽取为纯函数）", + "purpose": "计算分数平均值（空数组返回 0）（P1-1 新增：从 data-access.getStudentGradeSummary 抽取为纯函数；P3-6：export.ts 复用此函数替代局部 avg）", "usedBy": [ - "data-access.getStudentGradeSummary" + "data-access.getStudentGradeSummary", + "export.exportClassGradeReportToExcel" ] }, { "name": "buildGradeTrendPoints", "signature": "(rows: RawScoreRow[]) => GradeTrendPoint[]", "file": "stats-service.ts", - "purpose": "构建成绩趋势数据点（按考试标题分组，归一化分数 0-100）（P1-1 新增：从 data-access-analytics.getGradeTrend 抽取为纯函数）", + "purpose": "构建成绩趋势数据点（按考试标题分组，归一化分数 0-100）（P1-1 新增：从 data-access-analytics.getGradeTrend 抽取为纯函数；P3-24：使用 isGradeTrendType 类型守卫替代 as 断言）", "usedBy": [ "data-access-analytics.getGradeTrend" ] @@ -11040,19 +11093,23 @@ }, { "name": "logNotificationSend", - "signature": "(result: ChannelSendResult) => void", + "signature": "(result: ChannelSendResult, payload?: { userId: string; title: string }) => Promise", "file": "data-access.ts", - "purpose": "记录单条发送日志（当前使用 console.info；未来可扩展 notification_logs 表）", - "deps": [], + "purpose": "记录单条发送日志到 notification_logs 表（DB 写入失败时降级 console，不阻塞通知流程）", + "deps": [ + "shared.db", + "shared.db.schema.notificationLogs", + "@paralleldrive/cuid2" + ], "usedBy": [ "logNotificationSendBatch" ] }, { "name": "logNotificationSendBatch", - "signature": "(results: ChannelSendResult[]) => void", + "signature": "(results: ChannelSendResult[], payload?: { userId: string; title: string }) => Promise", "file": "data-access.ts", - "purpose": "批量记录发送日志", + "purpose": "批量记录发送日志（并行调用 logNotificationSend）", "deps": [ "logNotificationSend" ], @@ -11221,6 +11278,13 @@ "messaging (via re-export)" ] }, + { + "name": "NotificationLog", + "type": "interface", + "file": "types.ts", + "definition": "{ id, userId, title, channel: NotificationChannel, status: 'success' | 'failure', messageId: string | null, error: string | null, sentAt }", + "usedBy": [] + }, { "name": "PaginatedResult", "type": "interface", @@ -14339,7 +14403,7 @@ }, "dbTables": { "_meta": { - "total": 58, + "total": 59, "orm": "Drizzle ORM 0.45", "database": "MySQL", "idStrategy": "CUID2 (varchar length 128)", @@ -14598,6 +14662,10 @@ "owner": "notifications", "description": "消息通知" }, + "notificationLogs": { + "owner": "notifications", + "description": "通知发送日志(channel/status/messageId/error/sentAt)" + }, "notificationPreferences": { "owner": "notifications", "description": "通知偏好(email/sms/push + 分类开关)" @@ -14980,7 +15048,9 @@ "textbooks": { "dependsOn": [ "shared", - "auth" + "auth", + "users", + "classes" ], "uses": { "shared": [ @@ -14990,6 +15060,12 @@ ], "auth": [ "auth" + ], + "users": [ + "data-access.getCurrentStudentUser" + ], + "classes": [ + "data-access-students.getClassStudents" ] } }, diff --git a/src/modules/classes/actions-invitations.ts b/src/modules/classes/actions-invitations.ts index 6612a03..bfc0cf7 100644 --- a/src/modules/classes/actions-invitations.ts +++ b/src/modules/classes/actions-invitations.ts @@ -375,3 +375,128 @@ export async function setStudentEnrollmentStatusAction( throw e } } + +/** + * P2-4 批量导入学生：解析 CSV（每行 name,email 或仅 email），逐个调用 enrollStudentByEmail。 + * 用于开学季批量注册，提升配置效率。 + */ +export async function bulkEnrollStudentsAction( + classId: string, + prevState: ActionState<{ imported: number; failed: number; errors: string[] }> | undefined, + formData: FormData +): Promise> { + try { + await requirePermission(Permissions.CLASS_ENROLL) + + const csvText = String(formData.get("csv") ?? "").trim() + if (!csvText) { + return { success: false, message: "CSV data is required" } + } + + // 解析 CSV：每行一个邮箱，格式 name,email 或仅 email + const lines = csvText.split(/\r?\n/).filter((line) => line.trim().length > 0) + const entries: Array<{ name?: string; email: string }> = [] + for (const line of lines) { + const parts = line.split(",").map((p) => p.trim()) + if (parts.length === 1) { + entries.push({ email: parts[0] }) + } else if (parts.length >= 2) { + entries.push({ name: parts[0], email: parts[1] }) + } + } + + if (entries.length === 0) { + return { success: false, message: "No valid entries found" } + } + + // 逐个注册（复用 enrollStudentByEmail data-access 逻辑） + let imported = 0 + let failed = 0 + const errors: string[] = [] + + for (const entry of entries) { + try { + await enrollStudentByEmail(classId, entry.email) + imported += 1 + } catch (error) { + failed += 1 + const msg = error instanceof Error ? error.message : "Unknown error" + errors.push(`${entry.email}: ${msg}`) + } + } + + revalidatePath("/teacher/classes/students") + revalidatePath("/admin/school/classes") + return { + success: true, + message: `Imported ${imported} students, ${failed} failed`, + data: { imported, failed, errors }, + } + } catch (e) { + if (e instanceof PermissionDeniedError) return { success: false, message: e.message } + if (e instanceof Error) return { success: false, message: e.message } + return { success: false, message: "Failed to bulk enroll students" } + } +} + +/** + * P2-4 批量分配教师：解析 CSV（每行 className,subject,teacherEmail）。 + * 当前为简化实现：需按名称查找班级、按邮箱查找教师后调用 setClassSubjectTeachers， + * 查找逻辑待后续完善，暂记录为失败。 + */ +export async function bulkAssignSubjectTeachersAction( + prevState: ActionState<{ updated: number; failed: number; errors: string[] }> | undefined, + formData: FormData +): Promise> { + try { + await requirePermission(Permissions.CLASS_UPDATE) + + const csvText = String(formData.get("csv") ?? "").trim() + if (!csvText) { + return { success: false, message: "CSV data is required" } + } + + // 解析 CSV：格式 className,subject,teacherEmail + const lines = csvText.split(/\r?\n/).filter((line) => line.trim().length > 0) + const entries: Array<{ className: string; subject: string; teacherEmail: string }> = [] + + for (const line of lines) { + const parts = line.split(",").map((p) => p.trim()) + if (parts.length >= 3) { + entries.push({ className: parts[0], subject: parts[1], teacherEmail: parts[2] }) + } + } + + if (entries.length === 0) { + return { success: false, message: "No valid entries found" } + } + + const updated = 0 + let failed = 0 + const errors: string[] = [] + + for (const entry of entries) { + try { + // TODO: 查找班级（按名称）与教师（按邮箱），调用 setClassSubjectTeachers 完成分配。 + // 当前版本暂未实现按名称/邮箱的查找逻辑，记录为失败。 + failed += 1 + errors.push(`${entry.className}/${entry.subject}: Not implemented in this version`) + } catch (error) { + failed += 1 + const msg = error instanceof Error ? error.message : "Unknown error" + errors.push(`${entry.className}/${entry.subject}: ${msg}`) + } + } + + revalidatePath("/admin/school/classes") + return { + success: true, + message: `Updated ${updated} assignments, ${failed} failed`, + data: { updated, failed, errors }, + } + } catch (e) { + if (e instanceof PermissionDeniedError) return { success: false, message: e.message } + if (e instanceof Error) return { success: false, message: e.message } + return { success: false, message: "Failed to bulk assign teachers" } + } +} diff --git a/src/modules/classes/actions.ts b/src/modules/classes/actions.ts index eb993cd..1f35d66 100644 --- a/src/modules/classes/actions.ts +++ b/src/modules/classes/actions.ts @@ -40,6 +40,8 @@ export { revokeClassInvitationCodeAction, listClassInvitationCodesAction, setStudentEnrollmentStatusAction, + bulkEnrollStudentsAction, + bulkAssignSubjectTeachersAction, } from "./actions-invitations" export { diff --git a/src/modules/school/actions.ts b/src/modules/school/actions.ts index ab14178..0b74607 100644 --- a/src/modules/school/actions.ts +++ b/src/modules/school/actions.ts @@ -8,7 +8,7 @@ import type { ActionState } from "@/shared/types/action-state" import { requirePermission, PermissionDeniedError } from "@/shared/lib/auth-guard" import { Permissions } from "@/shared/types/permissions" import { logAudit } from "@/shared/lib/audit-logger" -import { UpsertAcademicYearSchema, UpsertDepartmentSchema, UpsertGradeSchema, UpsertSchoolSchema } from "./schema" +import { UpsertAcademicYearSchema, UpsertDepartmentSchema, UpsertGradeSchema, UpsertSchoolSchema, PromoteGradesSchema } from "./schema" import { createAcademicYear, createDepartment, @@ -18,6 +18,7 @@ import { deleteDepartment, deleteGrade, deleteSchool, + promoteGrades, updateAcademicYear, updateDepartment, updateGrade, @@ -44,6 +45,15 @@ export async function createDepartmentAction( description: parsed.data.description ?? null, }) + after(() => + logAudit({ + action: "department.create", + module: "school", + targetType: "department", + detail: { name: parsed.data.name }, + }) + ) + revalidatePath("/admin/school/departments") return { success: true, message: "Department created" } } catch (error) { @@ -73,6 +83,16 @@ export async function updateDepartmentAction( description: parsed.data.description ?? null, }) + after(() => + logAudit({ + action: "department.update", + module: "school", + targetId: departmentId, + targetType: "department", + detail: { name: parsed.data.name }, + }) + ) + revalidatePath("/admin/school/departments") return { success: true, message: "Department updated" } } catch (error) { @@ -86,6 +106,14 @@ export async function deleteDepartmentAction(departmentId: string): Promise + logAudit({ + action: "department.delete", + module: "school", + targetId: departmentId, + targetType: "department", + }) + ) revalidatePath("/admin/school/departments") return { success: true, message: "Department deleted" } } catch (error) { @@ -119,6 +147,15 @@ export async function createAcademicYearAction( isActive: parsed.data.isActive, }) + after(() => + logAudit({ + action: "academicYear.create", + module: "school", + targetType: "academicYear", + detail: { name: parsed.data.name }, + }) + ) + revalidatePath("/admin/school/academic-year") return { success: true, message: "Academic year created" } } catch (error) { @@ -152,6 +189,16 @@ export async function updateAcademicYearAction( isActive: parsed.data.isActive, }) + after(() => + logAudit({ + action: "academicYear.update", + module: "school", + targetId: academicYearId, + targetType: "academicYear", + detail: { name: parsed.data.name }, + }) + ) + revalidatePath("/admin/school/academic-year") return { success: true, message: "Academic year updated" } } catch (error) { @@ -291,6 +338,15 @@ export async function createGradeAction( teachingHeadId: parsed.data.teachingHeadId, }) + after(() => + logAudit({ + action: "grade.create", + module: "school", + targetType: "grade", + detail: { name: parsed.data.name, schoolId: parsed.data.schoolId }, + }) + ) + revalidatePath("/admin/school/grades") return { success: true, message: "Grade created" } } catch (error) { @@ -326,6 +382,16 @@ export async function updateGradeAction( teachingHeadId: parsed.data.teachingHeadId, }) + after(() => + logAudit({ + action: "grade.update", + module: "school", + targetId: gradeId, + targetType: "grade", + detail: { name: parsed.data.name, schoolId: parsed.data.schoolId }, + }) + ) + revalidatePath("/admin/school/grades") return { success: true, message: "Grade updated" } } catch (error) { @@ -339,6 +405,14 @@ export async function deleteGradeAction(gradeId: string): Promise + logAudit({ + action: "grade.delete", + module: "school", + targetId: gradeId, + targetType: "grade", + }) + ) revalidatePath("/admin/school/grades") return { success: true, message: "Grade deleted" } } catch (error) { @@ -347,3 +421,37 @@ export async function deleteGradeAction(gradeId: string): Promise | undefined, + formData: FormData +): Promise> { + try { + await requirePermission(Permissions.GRADE_MANAGE) + const parsed = PromoteGradesSchema.safeParse({ + schoolId: formData.get("schoolId"), + }) + if (!parsed.success) { + return { success: false, message: "Invalid form data", errors: parsed.error.flatten().fieldErrors } + } + + const result = await promoteGrades(parsed.data.schoolId) + + after(() => + logAudit({ + action: "grade.promote", + module: "school", + targetType: "grade", + targetId: parsed.data.schoolId, + detail: { promoted: result.promoted }, + }) + ) + + revalidatePath("/admin/school/grades") + return { success: true, message: `Promoted ${result.promoted} grades` } + } catch (error) { + if (error instanceof PermissionDeniedError) return { success: false, message: error.message } + if (error instanceof Error) return { success: false, message: error.message } + return { success: false, message: "Failed to promote grades" } + } +} diff --git a/src/modules/school/components/org-tree-nav.tsx b/src/modules/school/components/org-tree-nav.tsx new file mode 100644 index 0000000..6fc1476 --- /dev/null +++ b/src/modules/school/components/org-tree-nav.tsx @@ -0,0 +1,148 @@ +"use client" + +import { useMemo, useState, type JSX } from "react" +import { ChevronDown, ChevronRight, GraduationCap, School, Users } from "lucide-react" +import { useTranslations } from "next-intl" + +import type { OrgTreeNode } from "../types" +import { cn } from "@/shared/lib/utils" +import { Input } from "@/shared/components/ui/input" + +type OrgTreeNavProps = { + nodes: OrgTreeNode[] + onSelect?: (node: OrgTreeNode) => void + selectedId?: string +} + +type OrgTreeItemProps = { + node: OrgTreeNode + depth: number + onSelect?: (node: OrgTreeNode) => void + selectedId?: string + search: string +} + +const NODE_ICON: Record = { + school: School, + grade: GraduationCap, + class: Users, +} + +function matchesSearch(node: OrgTreeNode, query: string): boolean { + if (!query) return true + if (node.name.toLowerCase().includes(query)) return true + return (node.children ?? []).some((child) => matchesSearch(child, query)) +} + +function OrgTreeItem({ node, depth, onSelect, selectedId, search }: OrgTreeItemProps): JSX.Element { + const [expanded, setExpanded] = useState(depth === 0) + const children = node.children ?? [] + const hasChildren = children.length > 0 + const isSelected = selectedId === node.id + const Icon = NODE_ICON[node.type] + + const handleToggle = (): void => { + if (hasChildren) setExpanded((v) => !v) + } + + const handleSelect = (): void => { + onSelect?.(node) + if (hasChildren && !expanded) setExpanded(true) + } + + return ( +
+
{ + if (e.key === "Enter" || e.key === " ") { + e.preventDefault() + handleSelect() + } + }} + className={cn( + "flex cursor-pointer items-center gap-1 rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring", + isSelected && "bg-accent font-medium text-accent-foreground" + )} + style={{ paddingLeft: `${depth * 12 + 8}px` }} + > + {hasChildren ? ( + + ) : ( + + )} + + {node.name} +
+ {hasChildren && expanded && ( +
+ {children.map((child) => + matchesSearch(child, search) ? ( + + ) : null + )} +
+ )} +
+ ) +} + +export function OrgTreeNav({ nodes, onSelect, selectedId }: OrgTreeNavProps): JSX.Element { + const t = useTranslations("school") + const [search, setSearch] = useState("") + + const filtered = useMemo( + () => nodes.filter((node) => matchesSearch(node, search.toLowerCase())), + [nodes, search] + ) + + return ( +
+ setSearch(e.target.value)} + placeholder={t("orgTree.search")} + className="h-8 text-sm" + /> + {filtered.length === 0 ? ( +

{t("orgTree.empty")}

+ ) : ( +
+ {filtered.map((node) => ( + + ))} +
+ )} +
+ ) +} diff --git a/src/modules/school/data-access.ts b/src/modules/school/data-access.ts index 4cdcede..5bbe39c 100644 --- a/src/modules/school/data-access.ts +++ b/src/modules/school/data-access.ts @@ -1,7 +1,7 @@ import "server-only" import { cache } from "react" -import { and, asc, eq, inArray, or, sql } from "drizzle-orm" +import { and, asc, desc, eq, inArray, or, sql } from "drizzle-orm" import { db } from "@/shared/db" import { academicYears, departments, grades, roles, schools, subjects, users, usersToRoles } from "@/shared/db/schema" @@ -15,6 +15,7 @@ import type { GradeInsertData, GradeListItem, GradeUpdateData, + OrgTreeNode, SchoolInsertData, SchoolListItem, SchoolUpdateData, @@ -595,6 +596,24 @@ export const getSubjectNameById = cache( }, ) +/** + * 批量获取科目名称映射（subjectId -> name）。 + * 供跨模块调用使用，避免直接查询 subjects 表。 + */ +export const getSubjectNameMapByIds = cache( + async (subjectIds: string[]): Promise> => { + const ids = subjectIds.filter((id) => id.trim().length > 0) + if (ids.length === 0) return new Map() + const rows = await db + .select({ id: subjects.id, name: subjects.name }) + .from(subjects) + .where(inArray(subjects.id, ids)) + const map = new Map() + for (const r of rows) map.set(r.id, r.name) + return map + }, +) + // --------------------------------------------------------------------------- // Cross-module query interfaces — grade head/teaching head verification // --------------------------------------------------------------------------- @@ -668,3 +687,114 @@ export const findGradeIdByHeadAndName = cache(async ( .limit(1) return row?.id ?? null }) + +/** + * 将年级名称升级：一年级→二年级，1年级→2年级，Grade 1→Grade 2 + * 无法识别的名称保持不变。 + */ +function promoteGradeName(name: string): string { + // 中文数字映射 + const chineseNums = ["一", "二", "三", "四", "五", "六", "七", "八", "九", "十", "十一", "十二"] + for (let i = 0; i < chineseNums.length - 1; i++) { + if (name.includes(chineseNums[i]) && !name.includes(chineseNums[i + 1])) { + return name.replace(chineseNums[i], chineseNums[i + 1]) + } + } + + // 阿拉伯数字 + const match = name.match(/(\d+)/) + if (match) { + const num = parseInt(match[1], 10) + if (num > 0 && num < 13) { + return name.replace(match[1], String(num + 1)) + } + } + + return name +} + +/** + * 年级升级：将指定学校下的所有年级 order +1，并更新年级名称（如果符合数字模式）。 + * 例如：一年级 → 二年级，order 1 → 2 + * + * 注意：此函数只更新年级本身的 order 和 name，不迁移班级数据。 + * 班级升级应由 classes 模块的独立 Action 处理。 + */ +export async function promoteGrades(schoolId: string): Promise<{ promoted: number }> { + const rows = await db + .select({ id: grades.id, name: grades.name, order: grades.order }) + .from(grades) + .where(eq(grades.schoolId, schoolId)) + .orderBy(desc(grades.order)) // 从高到低升级，避免唯一约束冲突 + + let promoted = 0 + for (const row of rows) { + const newOrder = (row.order ?? 0) + 1 + const newName = promoteGradeName(row.name) + await db + .update(grades) + .set({ order: newOrder, name: newName }) + .where(eq(grades.id, row.id)) + promoted += 1 + } + + return { promoted } +} + +/** + * 获取学校→年级→班级三级组织架构树。 + * 班级数据通过 classes 模块的 data-access 动态导入获取，避免循环依赖。 + * 任何一层查询失败均返回空数组，保证调用方拿到稳定结构。 + */ +export const getOrgTree = cache(async (): Promise => { + try { + const [schoolList, gradeList] = await Promise.all([getSchools(), getGrades()]) + + const { getAdminClasses } = await import("@/modules/classes/data-access") + const allClasses = await getAdminClasses() + + const classesByGradeId = new Map() + for (const cls of allClasses) { + const gradeId = cls.gradeId + if (typeof gradeId !== "string" || gradeId.length === 0) continue + const node: OrgTreeNode = { + id: cls.id, + name: cls.name, + type: "class", + } + const list = classesByGradeId.get(gradeId) + if (list) { + list.push(node) + } else { + classesByGradeId.set(gradeId, [node]) + } + } + + const gradesBySchoolId = new Map() + for (const grade of gradeList) { + const children = classesByGradeId.get(grade.id) ?? [] + const node: OrgTreeNode = { + id: grade.id, + name: grade.name, + type: "grade", + children, + } + const list = gradesBySchoolId.get(grade.school.id) + if (list) { + list.push(node) + } else { + gradesBySchoolId.set(grade.school.id, [node]) + } + } + + return schoolList.map((school) => ({ + id: school.id, + name: school.name, + type: "school", + children: gradesBySchoolId.get(school.id) ?? [], + })) + } catch (error) { + console.error("getOrgTree failed:", error) + return [] + } +}) diff --git a/src/modules/school/schema.ts b/src/modules/school/schema.ts index 9b5762d..5767209 100644 --- a/src/modules/school/schema.ts +++ b/src/modules/school/schema.ts @@ -50,3 +50,7 @@ export const UpsertGradeSchema = z .refine((v) => Number.isFinite(v.order) && Number.isInteger(v.order) && v.order >= 0, { message: "order must be a non-negative integer", }) + +export const PromoteGradesSchema = z.object({ + schoolId: z.string().trim().min(1), +}) diff --git a/src/modules/school/types.ts b/src/modules/school/types.ts index f5173ba..fa325f6 100644 --- a/src/modules/school/types.ts +++ b/src/modules/school/types.ts @@ -94,3 +94,10 @@ export type AcademicYearUpdateData = { endDate: Date isActive: boolean } + +export type OrgTreeNode = { + id: string + name: string + type: "school" | "grade" | "class" + children?: OrgTreeNode[] +} diff --git a/src/shared/i18n/messages/en/school.json b/src/shared/i18n/messages/en/school.json index 5a4b3a9..c69aa0d 100644 --- a/src/shared/i18n/messages/en/school.json +++ b/src/shared/i18n/messages/en/school.json @@ -122,7 +122,15 @@ "optional": "Optional", "failedCreate": "Failed to create grade", "failedUpdate": "Failed to update grade", - "failedDelete": "Failed to delete grade" + "failedDelete": "Failed to delete grade", + "promote": { + "title": "Promote Grades", + "description": "Promote all grades of the selected school by one level (e.g., Grade 1 → Grade 2). Historical archives are preserved.", + "confirm": "Confirm Promotion", + "selectSchool": "Select a school", + "success": "Successfully promoted {count} grades", + "failed": "Promotion failed" + } }, "departments": { "title": "Department Management", @@ -205,6 +213,24 @@ "classManagement": { "title": "Class Management", "description": "Manage classes and assign teachers.", + "bulk": { + "importStudents": { + "title": "Bulk Import Students", + "description": "One email per line, format: name,email or email only", + "placeholder": "John,john@example.com\njane@example.com", + "submit": "Import", + "success": "Imported {imported} students, {failed} failed", + "failed": "Bulk import failed" + }, + "assignTeachers": { + "title": "Bulk Assign Teachers", + "description": "One row per line: class name,subject,teacher email", + "placeholder": "Class 1,Math,john@example.com\nClass 2,English,jane@example.com", + "submit": "Assign", + "success": "Updated {updated} assignments, {failed} failed", + "failed": "Bulk assignment failed" + } + }, "grade": { "title": "Class Management", "description": "Manage classes for your grades.", @@ -253,5 +279,12 @@ "description": "An error occurred while loading data. Please retry.", "retry": "Retry" } + }, + "orgTree": { + "title": "Organization", + "search": "Search school/grade/class...", + "empty": "No data", + "expandAll": "Expand All", + "collapseAll": "Collapse All" } } diff --git a/src/shared/i18n/messages/zh-CN/school.json b/src/shared/i18n/messages/zh-CN/school.json index b31cb0c..3aebff4 100644 --- a/src/shared/i18n/messages/zh-CN/school.json +++ b/src/shared/i18n/messages/zh-CN/school.json @@ -122,7 +122,15 @@ "optional": "可选", "failedCreate": "创建年级失败", "failedUpdate": "更新年级失败", - "failedDelete": "删除年级失败" + "failedDelete": "删除年级失败", + "promote": { + "title": "年级升级", + "description": "将选定学校的所有年级升级一级（如一年级→二年级），保留历史档案。", + "confirm": "确认升级", + "selectSchool": "请选择学校", + "success": "成功升级 {count} 个年级", + "failed": "升级失败" + } }, "departments": { "title": "部门管理", @@ -205,6 +213,24 @@ "classManagement": { "title": "班级管理", "description": "管理班级并分配教师。", + "bulk": { + "importStudents": { + "title": "批量导入学生", + "description": "每行一个邮箱，格式：name,email 或仅 email", + "placeholder": "张三,zhangsan@example.com\nlisi@example.com", + "submit": "导入", + "success": "成功导入 {imported} 个学生，{failed} 个失败", + "failed": "批量导入失败" + }, + "assignTeachers": { + "title": "批量分配教师", + "description": "每行格式：班级名称,科目,教师邮箱", + "placeholder": "一班,语文,zhangsan@example.com\n二班,数学,lisi@example.com", + "submit": "分配", + "success": "成功更新 {updated} 个分配，{failed} 个失败", + "failed": "批量分配失败" + } + }, "grade": { "title": "班级管理", "description": "管理你所在年级的班级。", @@ -253,5 +279,12 @@ "description": "数据加载时发生错误，请重试", "retry": "重试" } + }, + "orgTree": { + "title": "组织架构", + "search": "搜索学校/年级/班级...", + "empty": "暂无数据", + "expandAll": "全部展开", + "collapseAll": "全部折叠" } }