docs: 全项目架构审查与文档体系重写
- 全项目逐文件审查: 4 份审计报告(shared/core-business/management/new-modules) - 重写 004 架构影响地图: 图优先 + 模块依赖图 + 数据流 + 调用链 + 问题分级 - 更新 005 结构化数据: 新增 architectureOverview/moduleDependencyGraph/knownIssues/dbTables 节点 - 更新 006 功能清单: 143 项功能标注实现状态, P0 覆盖率 80%->92% - 更新 007 差距审计: v2->v3, P0 完成 69%->84%, 新增架构技术债章节 - 更新 001 项目概览: 6 角色/54 权限/26 模块/54 表 - 新增 docs/README.md 文档索引 - 归档 11 份过时文档(002x2/003/designx8) 标注 - 更新 work_log
This commit is contained in:
SpecialX
87
docs/README.md
Normal file
87
docs/README.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# 文档索引
|
||||
|
||||
> Next_Edu 项目文档总索引。按用途分类，标注维护状态。
|
||||
> 活跃文档随代码同步维护；已归档文档仅保留历史参考。
|
||||
|
||||
---
|
||||
|
||||
## 架构文档（活跃维护）
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [001 项目概览](architecture/001_project_overview.md) | 项目入口概览：技术栈、角色权限、模块、数据库、路由、架构原则、项目状态 |
|
||||
| [004 架构影响地图](architecture/004_architecture_impact_map.md) | 全模块·全函数·全参数级别架构图（人类可读） |
|
||||
| [005 架构数据](architecture/005_architecture_data.json) | AI 友好的结构化架构数据（JSON） |
|
||||
| [006 功能清单](architecture/006_k12_feature_checklist.md) | 企业级 K12 标准功能模块清单（P0/P1/P2 优先级） |
|
||||
| [007 差距审计报告](architecture/007_gap_audit_report.md) | 功能差距审计与补齐路线图 |
|
||||
|
||||
## 架构审查报告
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [审查汇总](architecture/audit/00_summary.md) | 全项目架构审查汇总报告 |
|
||||
| [shared 层审查](architecture/audit/shared-audit.md) | 共享基础设施层审查 |
|
||||
| [核心业务模块审查](architecture/audit/core-business-audit.md) | exams/homework/questions/textbooks 等核心模块审查 |
|
||||
| [管理模块群审查](architecture/audit/management-modules-audit.md) | school/classes/users/audit 等管理模块审查 |
|
||||
| [新增模块和其他模块审查](architecture/audit/new-and-other-modules-audit.md) | diagnostic/elective/proctoring/notifications 等新增模块审查 |
|
||||
|
||||
## 专题文档（活跃维护）
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [无障碍审计](accessibility/a11y-audit.md) | WCAG 2.1 AA 合规审计报告 |
|
||||
| [视觉回归测试](testing/visual-regression.md) | Playwright 视觉回归测试方案 |
|
||||
| [通知渠道](notifications/channels.md) | 多渠道通知（站内/短信/微信/邮件）集成文档 |
|
||||
| [安全扫描](security/scanning.md) | 依赖审计/Snyk/Trivy/OWASP ZAP 安全扫描指南 |
|
||||
| [灾备计划](dr/dr-plan.md) | 灾难恢复计划（RTO/RPO 目标） |
|
||||
| [灾备操作手册](dr/dr-runbook.md) | 生产环境故障处理操作手册 |
|
||||
| [数据库 Schema 变更日志](db/schema-changelog.md) | 数据库迁移变更记录 |
|
||||
|
||||
## 工作日志
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [工作日志](work_log.md) | 项目开发进度日志 |
|
||||
|
||||
## 脚本
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [考试种子数据脚本](scripts/seed-exams.ts) | 考试模块测试数据生成脚本 |
|
||||
|
||||
---
|
||||
|
||||
## 已归档文档
|
||||
|
||||
> 以下文档记录的是历史阶段的设计/实现/分析，当前已由架构文档（004/005/006/007）取代。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
### 架构历史文档
|
||||
|
||||
| 文档 | 归档原因 |
|
||||
|------|---------|
|
||||
| [002 RBAC 重构方案](architecture/002_rbac_refactoring.md) | 描述修复前的安全隐患，当前所有 Server Action 已接入 `requirePermission()` |
|
||||
| [002 角色路由 RFC](architecture/002_role_based_routing.md) | 2025-12-23 提案，当前角色域路由已全部实现 |
|
||||
| [003 UI 重构计划](architecture/003_ui_refactoring_plan.md) | 2026-06-16 重构计划，当前已执行完毕 |
|
||||
|
||||
### 设计历史文档
|
||||
|
||||
| 文档 | 归档原因 |
|
||||
|------|---------|
|
||||
| [002 教师仪表盘实现](design/002_teacher_dashboard_implementation.md) | 2025-12-23 实现记录，已由 004 dashboard 模块章节取代 |
|
||||
| [003 教材模块实现](design/003_textbooks_module_implementation.md) | 2025-12-23 实现记录，已由 004 textbooks 模块章节取代 |
|
||||
| [004 题库模块实现](design/004_question_bank_implementation.md) | 2025-12-23 实现记录，已由 004 questions 模块章节取代 |
|
||||
| [005 考试模块实现](design/005_exam_module_implementation.md) | 考试模块实现设计，已由 004 exams 模块章节取代 |
|
||||
| [006 作业模块实现](design/006_homework_module_implementation.md) | 2025-12-31 实现记录，已由 004 homework 模块章节取代 |
|
||||
| [008 教师页面实现](design/008_teacher_pages_implementation.md) | 2026-03-03 页面分析，路由已大幅扩展 |
|
||||
| [009 功能差距分析](design/009_feature_gap_analysis.md) | 2026-03-03 功能对比，已由 007 差距审计报告取代 |
|
||||
| [010 QA 测试计划](design/010_qa_test_plan_and_feedback.md) | 2026-03-18 测试方案，测试体系已演进 |
|
||||
|
||||
---
|
||||
|
||||
## 文档维护规则
|
||||
|
||||
1. **改码必同步图**：源码修改后须同步更新 004/005 架构文档
|
||||
2. **归档不删除**：过时文档添加归档标注，不删除
|
||||
3. **活跃文档**：001/004/005/006/007 + 专题文档随代码同步维护
|
||||
4. **新增文档**：新增文档须在本索引中登记
|
||||
@@ -1,6 +1,7 @@
|
||||
# Next_Edu 项目架构分析
|
||||
# Next_Edu 项目概览
|
||||
|
||||
> 本文档基于源码逆向分析生成，未参考任何已有文档。
|
||||
> 本文档是项目的入口概览，基于源码与架构影响地图（004/005）维护。
|
||||
> 详细模块/函数/路由/表结构请查阅 [004 架构影响地图](./004_architecture_impact_map.md) 与 [005 架构数据](./005_architecture_data.json)。
|
||||
|
||||
---
|
||||
|
||||
@@ -9,10 +10,10 @@
|
||||
**Next_Edu** 是一个面向 K12 场景的**智慧教务管理系统**，旨在将传统学校的教务流程数字化、智能化。
|
||||
|
||||
核心目标：
|
||||
1. **多角色协同**：管理员、教师、学生、家长四种角色在同一平台协作，各角色有独立的仪表盘和功能入口
|
||||
1. **多角色协同**：6 种角色（管理员、教师、学生、家长、年级组长、教研组长）在同一平台协作，各角色有独立的仪表盘和功能入口
|
||||
2. **AI 赋能教学**：集成大语言模型（智谱/OpenAI/Gemini），支持 AI 自动生成试卷、AI 重写题目、AI 对话辅导
|
||||
3. **全流程闭环**：从教材管理 → 题库建设 → 试卷组卷 → 考试/作业发布 → 学生作答 → 教师批改 → 数据分析，覆盖教学评估全链路
|
||||
4. **知识体系结构化**：教材章节与知识点树形关联，知识点与题目双向链接，支撑精准教学
|
||||
4. **知识体系结构化**：教材章节与知识点树形关联，知识点与题目双向链接，支撑精准教学与学情诊断
|
||||
|
||||
---
|
||||
|
||||
@@ -43,23 +44,28 @@
|
||||
|
||||
| 角色 | 路由前缀 | 核心职责 |
|
||||
|------|---------|---------|
|
||||
| **Admin** | `/admin/*` | 学校管理、年级/班级/部门配置、用户管理、全局设置 |
|
||||
| **Teacher** | `/teacher/*` | 教材管理、题库建设、试卷组卷、作业发布与批改、班级管理 |
|
||||
| **Student** | `/student/*` | 课程学习、作业作答、教材阅读、课表查看 |
|
||||
| **Parent** | `/parent/*` | 子女学情查看、缴费、消息沟通 |
|
||||
| **Admin** | `/admin/*` | 学校管理、年级/班级/部门配置、用户管理、全局设置、审计日志、排课、选修课 |
|
||||
| **Teacher** | `/teacher/*` | 教材管理、题库建设、试卷组卷、作业发布与批改、班级管理、考勤、成绩录入、学情诊断 |
|
||||
| **Student** | `/student/*` | 课程学习、作业作答、教材阅读、课表查看、成绩查询、选课、学情诊断 |
|
||||
| **Parent** | `/parent/*` | 子女学情查看、成绩/考勤/课表、消息沟通 |
|
||||
| **Grade Head** (年级组长) | 映射为 `/teacher/*` | 年级管理、年级作业洞察、学情诊断 |
|
||||
| **Teaching Head** (教研组长) | 映射为 `/teacher/*` | 教研管理、学情诊断 |
|
||||
|
||||
### 权限控制机制
|
||||
|
||||
```
|
||||
请求 → NextAuth Middleware (proxy.ts)
|
||||
→ 检查 session 是否存在 → 无则重定向 /login
|
||||
→ 解析 JWT 中的 role 字段
|
||||
→ 按路由前缀校验角色匹配
|
||||
→ 解析 JWT 中的 role/permissions 字段
|
||||
→ 按路由前缀校验角色与权限点匹配
|
||||
→ 不匹配则重定向到角色首页
|
||||
```
|
||||
|
||||
- **角色解析**：`grade_head` 和 `teaching_head` 映射为 `teacher`；多角色用户取优先级 `admin > teacher > parent > student`
|
||||
- **权限点**：共 **54 个权限点**（`exam:create`、`homework:grade`、`announcement:manage`、`file:upload`、`grade_record:manage`、`attendance:manage`、`message:send`、`schedule:auto`、`elective:select`、`exam:proctor`、`diagnostic:manage` 等），定义于 `src/shared/types/permissions.ts`
|
||||
- **角色-权限映射**：`ROLE_PERMISSIONS` 常量（`src/shared/lib/permissions.ts`），6 角色到权限列表的映射
|
||||
- **角色解析**：`grade_head` 和 `teaching_head` 在路由层映射为 `teacher`；多角色用户取优先级 `admin > teacher > parent > student`
|
||||
- **用户-角色**：多对多关系（`users_to_roles` 表），支持一人多角色
|
||||
- **数据范围控制（DataScope）**：6 种行级权限类型 — `all` / `owned` / `class_taught` / `grade_managed` / `class_members` / `children`
|
||||
- **导航隔离**：`NAV_CONFIG` 按角色定义侧边栏菜单，不同角色看到完全不同的功能入口
|
||||
|
||||
---
|
||||
@@ -72,13 +78,15 @@
|
||||
School ──1:N──→ Grade ──1:N──→ Class ──1:N──→ ClassEnrollment ←──N:1── User(student)
|
||||
│ │
|
||||
│ ├── ClassSubjectTeacher (班级-科目-教师)
|
||||
│ └── ClassSchedule (课表)
|
||||
│ ├── ClassSchedule (课表)
|
||||
│ └── AttendanceRecords (考勤)
|
||||
│
|
||||
├── Department
|
||||
├── Classroom
|
||||
└── AcademicYear
|
||||
|
||||
User ──M:N──→ Role (RBAC)
|
||||
User ──M:N──→ Role (RBAC) ──→ Permissions (54 个权限点)
|
||||
User ──M:N──→ ParentStudentRelation (家长-子女)
|
||||
|
||||
Textbook ──1:N──→ Chapter (树形嵌套) ──1:N──→ KnowledgePoint (树形嵌套)
|
||||
│
|
||||
@@ -90,27 +98,52 @@ Question ──M:N──→ KnowledgePoint │
|
||||
│
|
||||
Exam ──M:N──→ Question (exam_questions) │
|
||||
├── ExamSubmission ──1:N──→ SubmissionAnswer │
|
||||
└── structure (JSON 层级结构) │
|
||||
├── structure (JSON 层级结构) │
|
||||
└── ExamProctoringEvent (监考事件) │
|
||||
│
|
||||
HomeworkAssignment ──M:N──→ Question │
|
||||
├── sourceExamId → Exam (作业源自试卷) │
|
||||
├── HomeworkAssignmentTarget (指定学生) │
|
||||
└── HomeworkSubmission ──1:N──→ HomeworkAnswer │
|
||||
│
|
||||
GradeRecord (成绩) ──→ Student/Class/Subject/Exam │
|
||||
CoursePlan ──1:N──→ CoursePlanItem (课程计划) │
|
||||
│
|
||||
Announcement (公告) ──→ Grade/Class 定向发布 │
|
||||
Message (站内消息) ──→ MessageNotification │
|
||||
AuditLog / LoginLog / DataChangeLog (审计日志) │
|
||||
│
|
||||
ElectiveCourse ──1:N──→ CourseSelection (选课) │
|
||||
LearningDiagnosticReport (学情诊断报告) │
|
||||
KnowledgePointMastery (知识点掌握度) │
|
||||
│
|
||||
AIProvider (zhipu / openai / gemini / custom) │
|
||||
└── apiKeyEncrypted (AES 加密存储) │
|
||||
```
|
||||
|
||||
### 数据库规模
|
||||
|
||||
- **20+ 张表**，覆盖用户认证、RBAC、学校管理、教学资源、考试系统、作业系统、AI 配置
|
||||
- **54 张表**，覆盖用户认证、RBAC、学校管理、教学资源、考试系统、作业系统、AI 配置、审计日志、公告、文件、成绩、课程计划、消息、考勤、排课、选修课、学情诊断、监考
|
||||
- **ID 策略**：CUID2（`@paralleldrive/cuid2`），128 位 varchar
|
||||
- **索引策略**：所有外键和查询字段均有索引，支持级联删除
|
||||
- **Schema 文件**：`src/shared/db/schema.ts`（单文件，54 张表定义）
|
||||
|
||||
---
|
||||
|
||||
## 五、架构设计
|
||||
|
||||
### 架构原则
|
||||
|
||||
1. **分层架构**：`app → modules → shared`，三层单向依赖
|
||||
- `src/app/`：Next.js App Router 路由层，负责路由分发、页面组装、Suspense/error 边界
|
||||
- `src/modules/`：业务模块层，每个模块是一个独立的业务领域
|
||||
- `src/shared/`：共享基础设施层，提供数据库、工具函数、权限系统、UI 基础组件
|
||||
2. **模块化**：每个模块对应一个业务领域，包含 `components/`、`hooks/`、`actions.ts`、`data-access.ts`、`types.ts`、`schema.ts`
|
||||
3. **权限校验**：所有 Server Action 必须使用 `requirePermission()` 或 `requireAuth()` 进行权限校验，前端组件使用 `usePermission().hasPermission()` 条件渲染（禁止 `role === "xxx"` 硬编码）
|
||||
4. **数据访问**：通过 `data-access.ts` 层访问数据库，Server Action 不直接调用 Drizzle ORM
|
||||
5. **类型安全**：TypeScript strict 模式，Zod schema 校验输入，`ActionState<T>` 统一返回结构
|
||||
6. **行级权限**：`DataScope` 提供 6 种数据范围类型，data-access 层按 scope 过滤数据
|
||||
|
||||
### 分层架构
|
||||
|
||||
```
|
||||
@@ -121,7 +154,7 @@ AIProvider (zhipu / openai / gemini / custom) │
|
||||
│ ├── loading.tsx (Suspense 边界) │
|
||||
│ └── error.tsx (错误边界) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ Feature Modules (src/modules/) │
|
||||
│ Feature Modules (src/modules/) — 26 个模块 │
|
||||
│ ├── auth/ 认证模块 │
|
||||
│ ├── exams/ 考试模块 │
|
||||
│ ├── homework/ 作业模块 │
|
||||
@@ -132,24 +165,45 @@ AIProvider (zhipu / openai / gemini / custom) │
|
||||
│ ├── dashboard/ 仪表盘模块 │
|
||||
│ ├── layout/ 布局与导航 │
|
||||
│ ├── settings/ 设置模块 │
|
||||
│ └── users/ 用户管理模块 │
|
||||
│ ├── users/ 用户管理模块 │
|
||||
│ ├── audit/ 审计日志模块 │
|
||||
│ ├── announcements/ 公告模块 │
|
||||
│ ├── files/ 文件管理模块 │
|
||||
│ ├── grades/ 成绩管理模块 │
|
||||
│ ├── course-plans/ 课程计划模块 │
|
||||
│ ├── messaging/ 站内消息模块 │
|
||||
│ ├── notifications/ 通知模块 │
|
||||
│ ├── attendance/ 考勤模块 │
|
||||
│ ├── scheduling/ 排课模块 │
|
||||
│ ├── diagnostic/ 学情诊断模块 │
|
||||
│ ├── elective/ 选课模块 │
|
||||
│ ├── proctoring/ 考试监考模块 │
|
||||
│ ├── parent/ 家长端模块 │
|
||||
│ ├── student/ 学生端模块 │
|
||||
│ 每个模块: │
|
||||
│ ├── components/ UI 组件 │
|
||||
│ ├── hooks/ 自定义 Hook │
|
||||
│ ├── actions.ts Server Actions │
|
||||
│ ├── data-access.ts 数据访问层 │
|
||||
│ ├── schema.ts Zod 校验 Schema │
|
||||
│ └── types.ts 类型定义 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ Shared (src/shared/) │
|
||||
│ ├── components/ui/ shadcn/ui 基础组件 (30+) │
|
||||
│ ├── hooks/ 通用 Hook │
|
||||
│ ├── lib/ 工具函数 │
|
||||
│ ├── lib/ 工具函数 (auth-guard/ai/ │
|
||||
│ │ excel/file-storage/ │
|
||||
│ │ rate-limit/password-policy)│
|
||||
│ ├── db/ 数据库 (schema/relations) │
|
||||
│ └── types/ 公共类型 │
|
||||
│ └── types/ 公共类型 (permissions/ │
|
||||
│ action-state) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ API Routes (src/app/api/) │
|
||||
│ ├── auth/[...nextauth] NextAuth 端点 │
|
||||
│ ├── ai/chat AI 对话 │
|
||||
│ ├── upload / files 文件上传与管理 │
|
||||
│ ├── search 全局全文检索 │
|
||||
│ ├── export / import Excel 导入导出 │
|
||||
│ └── onboarding/* 用户引导 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
@@ -159,7 +213,8 @@ AIProvider (zhipu / openai / gemini / custom) │
|
||||
```
|
||||
用户操作 → Client Component
|
||||
→ Server Action (actions.ts)
|
||||
→ 数据访问层 (data-access.ts)
|
||||
→ requirePermission() 权限校验
|
||||
→ 数据访问层 (data-access.ts) 按 DataScope 过滤
|
||||
→ Drizzle ORM (db/index.ts)
|
||||
→ MySQL
|
||||
|
||||
@@ -216,26 +271,112 @@ AI 模式: 选择 AI Provider → 粘贴试卷源文本 → AI 解析生成 →
|
||||
→ 已引导: 进入角色仪表盘
|
||||
```
|
||||
|
||||
### 5. 学情诊断流程
|
||||
|
||||
```
|
||||
教师/管理员: 基于作业/考试数据 → 生成知识点掌握度 → 生成诊断报告
|
||||
├── 个人报告: 学生知识点雷达图 + 强项/弱项
|
||||
└── 班级报告: 知识点热力图 + 需重点关注学生
|
||||
学生: 查看本人学情诊断报告
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、部署与运维
|
||||
## 七、路由清单
|
||||
|
||||
### 路由分布
|
||||
|
||||
| 角色域 | 路由前缀 | 主要页面 |
|
||||
|--------|---------|---------|
|
||||
| **认证** | `/login`, `/register`, `/privacy`, `/terms` | 登录、注册、隐私政策、用户协议 |
|
||||
| **Admin** | `/admin/*` | 仪表盘、学校管理(学校/年级/部门/班级/学年)、审计日志、公告、文件、课程计划、考勤、用户导入、排课(规则/自动/调课)、选修课 |
|
||||
| **Teacher** | `/teacher/*` | 仪表盘、考试(列表/创建/构建)、题库、教材(列表/阅读)、班级(我的/课表/学生/详情)、作业(列表/创建/详情/提交/批改)、成绩(列表/录入/统计)、课程计划、考勤(列表/点名/统计)、调课申请、学情诊断(列表/学生/班级)、选修课 |
|
||||
| **Student** | `/student/*` | 仪表盘、学习(作业/课程/教材)、课表、成绩、考勤、学情诊断、选课 |
|
||||
| **Parent** | `/parent/*` | 仪表盘、子女详情、成绩、考勤 |
|
||||
| **Management** | `/management/*` | 年级班级管理、年级作业洞察（年级组长） |
|
||||
| **共享** | `/dashboard`, `/profile`, `/settings`, `/announcements`, `/messages/*` | 角色路由分发、个人资料、设置、公告列表、消息(列表/详情/写消息) |
|
||||
|
||||
### API 路由
|
||||
|
||||
| 路由 | 方法 | 用途 |
|
||||
|------|------|------|
|
||||
| `/api/auth/[...nextauth]` | GET/POST | NextAuth 认证端点 |
|
||||
| `/api/ai/chat` | POST | AI 对话（流式响应） |
|
||||
| `/api/upload` | POST | 文件上传 |
|
||||
| `/api/files/[id]` | GET/DELETE | 文件元数据查询/删除 |
|
||||
| `/api/files/batch-delete` | POST | 批量删除文件 |
|
||||
| `/api/search` | GET | 全局全文检索 |
|
||||
| `/api/export` | POST | Excel 导出 |
|
||||
| `/api/import` | POST | Excel 解析预览 |
|
||||
| `/api/onboarding/*` | GET/POST | 用户引导 |
|
||||
|
||||
---
|
||||
|
||||
## 八、部署与运维
|
||||
|
||||
- **构建模式**: `output: "standalone"` — 适配 Docker 容器化部署
|
||||
- **数据库迁移**: Drizzle Kit (`db:generate` / `db:migrate`)
|
||||
- **数据填充**: `db:seed` 脚本 + `@faker-js/faker`
|
||||
- **CI/CD**: `.gitea/workflows/ci.yml` — Gitea Actions
|
||||
- **CI/CD**: `.gitea/workflows/ci.yml` — Gitea Actions（构建/部署/测试）
|
||||
- **安全扫描**: `.gitea/workflows/security.yml` — npm audit + Snyk + Trivy + OWASP ZAP
|
||||
- **数据备份**: `.gitea/workflows/ci.yml` scheduled-backup — 每日全量备份 + 异地同步
|
||||
- **灾备演练**: `.gitea/workflows/dr-drill.yml` — 每周一 DR 演练
|
||||
- **测试**: 单元测试 (Vitest) + 集成测试 + E2E (Playwright)
|
||||
|
||||
---
|
||||
|
||||
## 八、项目规模统计
|
||||
## 九、项目状态
|
||||
|
||||
> 详细功能清单与差距审计请查阅 [006 功能清单](./006_k12_feature_checklist.md) 与 [007 差距审计报告](./007_gap_audit_report.md)。
|
||||
|
||||
### 优先级完成情况
|
||||
|
||||
| 优先级 | 状态 | 说明 |
|
||||
|--------|------|------|
|
||||
| **P0** (MVP 必须) | ✅ 已完成 | 核心业务、平台基础、合规安全 P0 项已全部实现 |
|
||||
| **P1** (上线前推荐) | ✅ 已完成 | 站内消息、家长仪表盘、考勤、排课、成绩分析、Excel 导入导出、密码安全、数据变更日志等 P1 项已实现 |
|
||||
| **P2** (迭代优化) | 🔄 8/14 完成 (57%) | 已完成：选课管理、考试监考、学情诊断、漏洞扫描、灾备方案、视觉回归测试等；剩余：国际化、多租户、AI 批改/学情/备课等 |
|
||||
|
||||
### 主要模块完成情况
|
||||
|
||||
- ✅ 用户与权限（6 角色、54 权限点、DataScope 行级权限）
|
||||
- ✅ 学校管理（学校/年级/班级/部门/学年/学科）
|
||||
- ✅ 教务排课（课程计划、排课规则、自动排课、调课审批、冲突检测）
|
||||
- ✅ 教材资源（教材/章节/知识点树形结构、知识图谱）
|
||||
- ✅ 题库与试卷（5 种题型、手动/AI 组卷、试卷预览）
|
||||
- ✅ 作业与考试（作业发布/作答/批改、统计分析）
|
||||
- ✅ 成绩分析（录入/查询/统计报表/趋势/对比/导出）
|
||||
- ✅ 家校沟通（公告、站内消息、家长仪表盘）
|
||||
- ✅ AI 赋能（AI 对话、AI 出题、多模型配置、API Key 加密）
|
||||
- ✅ 考勤管理（学生考勤、考勤规则、统计）
|
||||
- ✅ 日志审计（操作日志、登录日志、数据变更日志）
|
||||
- ✅ 文件管理（上传/预览/删除、StorageProvider 抽象）
|
||||
- ✅ 学情诊断（知识点掌握度、个人/班级诊断报告）
|
||||
- ✅ 选课管理（选修课、选课/退选、抽签模式）
|
||||
- ✅ 平台基础（全局搜索、Excel 导入导出、通知偏好、深色主题）
|
||||
|
||||
---
|
||||
|
||||
## 十、项目规模统计
|
||||
|
||||
| 维度 | 数量 |
|
||||
|------|------|
|
||||
| 数据库表 | 20+ |
|
||||
| 业务模块 | 11 |
|
||||
| 数据库表 | 54 |
|
||||
| 业务模块 | 26 |
|
||||
| UI 基础组件 | 30+ |
|
||||
| 路由页面 | 30+ |
|
||||
| Server Actions | 50+ |
|
||||
| API 路由 | 4 |
|
||||
| 用户角色 | 4 (admin/teacher/student/parent) |
|
||||
| 路由页面 | 60+ |
|
||||
| API 路由 | 9 |
|
||||
| Server Actions | 80+ |
|
||||
| 用户角色 | 6 (admin/teacher/student/parent/grade_head/teaching_head) |
|
||||
| 权限点 | 54 |
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
| 文档 | 用途 |
|
||||
|------|------|
|
||||
| [004 架构影响地图](./004_architecture_impact_map.md) | 全模块·全函数·全参数级别架构图 |
|
||||
| [005 架构数据](./005_architecture_data.json) | AI 友好的结构化架构数据 |
|
||||
| [006 功能清单](./006_k12_feature_checklist.md) | 企业级 K12 标准功能模块清单 |
|
||||
| [007 差距审计报告](./007_gap_audit_report.md) | 功能差距审计与补齐路线图 |
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2026-06 初的 RBAC 权限体系重构方案，描述的是修复前的安全隐患（如 exams/actions.ts 中的硬编码 getCurrentUser 存根）。
|
||||
> 当前已由 [004 架构影响地图](./004_architecture_impact_map.md) 与 [005 架构数据](./005_architecture_data.json) 取代——所有 Server Action 已接入 `requirePermission()`/`requireAuth()`，54 个权限点与 6 角色映射已落地。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 企业级权限体系重构方案
|
||||
|
||||
> 基于源码逆向分析，覆盖 proxy.ts / auth.ts / 各模块 actions.ts / 前端组件
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档是 2025-12-23 提出的角色路由 RFC（Status: PROPOSED），描述的是路由策略提案。
|
||||
> 当前该提案已全部实现——`/admin`、`/teacher`、`/student`、`/parent`、`/management` 角色域路由已落地，详见 [004 架构影响地图](./004_architecture_impact_map.md) 的 routes 章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# Architecture RFC: Role-Based Routing & Directory Structure
|
||||
|
||||
**Status**: PROPOSED
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档是 2026-06-16 架构审核后的 UI 代码结构重构计划（评分 7.2/10），描述的是待修复的质量问题与重构方案。
|
||||
> 当前重构计划已执行完毕，组件拆分、复用抽象、测试保障等改进已落地，最新架构状态详见 [004 架构影响地图](./004_architecture_impact_map.md)。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# UI 代码结构重构计划
|
||||
|
||||
> 基于 2026-06-16 架构审核，整体评分 7.2/10
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@@ -2,177 +2,178 @@
|
||||
|
||||
> 基于教育科技行业最佳实践，覆盖核心业务、平台基础、非功能性、合规安全四大维度。
|
||||
> 优先级定义：**P0** = MVP 必须，**P1** = 上线前推荐，**P2** = 迭代优化。
|
||||
> 实现状态：✅ 已完成 / ⚠️ 部分完成 / ❌ 未实现（基于 2026-06-17 源码扫描）
|
||||
|
||||
---
|
||||
|
||||
## 一、核心业务模块
|
||||
|
||||
| 模块 | 子功能 | 说明 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| **用户与权限** | 用户注册/登录 | 邮箱/手机号注册，第三方 OAuth 登录 | P0 |
|
||||
| | 多角色体系 | 管理员/教师/学生/家长/年级组长/教研组长，支持一人多角色 | P0 |
|
||||
| | RBAC 权限模型 | 资源:动作权限点（如 `exam:create`），角色-权限映射 | P0 |
|
||||
| | 数据范围控制 | 行级权限：全部/所属/所教班级/所管年级/班级成员/子女 | P0 |
|
||||
| | 角色切换 | 多角色用户可主动切换当前活跃角色 | P1 |
|
||||
| | 用户档案管理 | 个人信息编辑、头像、联系方式、地址 | P0 |
|
||||
| | 新手引导(Onboarding) | 首次登录选择角色、填写资料、加入班级 | P0 |
|
||||
| | 组织架构管理 | 部门/年级/教研组树形结构管理 | P1 |
|
||||
| | 用户批量导入 | Excel/CSV 批量导入学生、教师信息 | P1 |
|
||||
| | 密码安全策略 | 密码强度校验、定期更换提醒、登录失败锁定 | P1 |
|
||||
| **学校管理** | 学校信息配置 | 校名、校徽、地址、学期制度等基础信息 | P0 |
|
||||
| | 学年学期管理 | 创建/切换学年学期，学期起止日期，当前学期标记 | P0 |
|
||||
| | 年级管理 | 年级创建/编辑/归档，年级组长指派 | P0 |
|
||||
| | 班级管理 | 班级创建/编辑/归档，班主任指派，班级邀请码 | P0 |
|
||||
| | 学科管理 | 学科创建/编辑，学科代码，学段归属 | P0 |
|
||||
| | 部门管理 | 教务处/德育处/总务处等行政部门管理 | P1 |
|
||||
| | 校区管理 | 多校区信息维护，校区间资源共享策略 | P2 |
|
||||
| | 学校参数配置 | 学分制/等级制切换、考号规则、编号规则等 | P1 |
|
||||
| **教务排课** | 课程计划管理 | 各年级/班级课程设置，周课时分配 | P0 |
|
||||
| | 排课规则配置 | 教师不冲突、教室不冲突、连排/不连排规则 | P0 |
|
||||
| | 自动排课引擎 | 基于约束满足的智能排课算法 | P1 |
|
||||
| | 课表查看 | 教师/学生/班级/教室多维度课表 | P0 |
|
||||
| | 课表调整/代课 | 临时调课、代课安排，自动通知受影响方 | P1 |
|
||||
| | 教室资源管理 | 教室类型、容量、设备标签，排课时自动匹配 | P2 |
|
||||
| | 选课管理 | 选修课选课、退选、抽签规则 | P2 |
|
||||
| **教材资源** | 教材库管理 | 教材元数据（学科/年级/版本/出版社） | P0 |
|
||||
| | 章节结构管理 | 教材章节树形目录，支持拖拽排序 | P0 |
|
||||
| | 知识点图谱 | 知识点与章节关联，知识点间前置/后继关系 | P1 |
|
||||
| | 教材内容阅读 | 富文本/Markdown 章节内容在线阅读 | P0 |
|
||||
| | 教材版本管理 | 同一教材多版本共存，版本切换 | P1 |
|
||||
| | 资源附件管理 | 教案/课件/视频等附件上传与关联 | P1 |
|
||||
| | 教材审核流程 | 教材内容发布前审核机制 | P2 |
|
||||
| **题库与试卷** | 题目创建/编辑 | 选择/填空/判断/简答/综合题，支持子题目 | P0 |
|
||||
| | 题目分类标签 | 学科/知识点/难度/题型多维标签 | P0 |
|
||||
| | 题目批量导入 | Excel/Word 模板批量导入题目 | P1 |
|
||||
| | 题目版本管理 | 题目修改保留历史版本 | P2 |
|
||||
| | 试卷手动组卷 | 从题库选题组卷，分数自动汇总 | P0 |
|
||||
| | 试卷智能组卷 | 按知识点/难度分布自动抽题 | P1 |
|
||||
| | AI 辅助出题 | 大模型根据知识点/要求自动生成题目 | P1 |
|
||||
| | 试卷模板管理 | 常用试卷结构模板保存与复用 | P2 |
|
||||
| | 试卷预览/打印 | 试卷排版预览，A4/B4 打印适配 | P1 |
|
||||
| **作业与考试** | 作业布置 | 关联试卷/题目，选择目标班级/学生，设置截止时间 | P0 |
|
||||
| | 作业提交 | 学生在线作答，支持文本/图片/附件 | P0 |
|
||||
| | 作业批改评分 | 教师逐题评分，支持批注/语音反馈 | P0 |
|
||||
| | 迟交/补交策略 | 允许迟交开关、迟交截止时间、迟交标记 | P1 |
|
||||
| | 多次提交/重做 | 可配置最大尝试次数，取最高分/最后一次 | P1 |
|
||||
| | 作业统计分析 | 完成率、平均分、分数分布、题目正确率 | P1 |
|
||||
| | 作业归档 | 学期结束后作业数据归档，释放活跃数据空间 | P2 |
|
||||
| | 在线考试模式 | 限时考试、防切屏、乱序、自动交卷 | P1 |
|
||||
| | 考试监考 | 教师端实时查看提交进度，异常行为标记 | P2 |
|
||||
| **成绩分析** | 成绩录入 | 手动录入/Excel 导入/作业自动同步 | P0 |
|
||||
| | 成绩查询 | 学生查本人，教师查所教班级，管理员查全部 | P0 |
|
||||
| | 成绩统计报表 | 班级/年级均分、中位数、标准差、及格率 | P0 |
|
||||
| | 成绩趋势分析 | 历次考试趋势折线图，进步/退步预警 | P1 |
|
||||
| | 成绩对比分析 | 班级间对比、学科间对比、与年级均分对比 | P1 |
|
||||
| | 学情诊断报告 | 基于知识点掌握度的个人/班级诊断报告 | P2 |
|
||||
| | 成绩导出 | Excel/PDF 成绩单导出，支持自定义模板 | P1 |
|
||||
| | 等第转换 | 分数↔等第(A/B/C/D)自动转换 | P2 |
|
||||
| **家校沟通** | 通知公告 | 学校/年级/班级三级公告发布，已读回执 | P0 |
|
||||
| | 站内消息 | 教师↔家长、教师↔学生私信，支持群发 | P1 |
|
||||
| | 家长端仪表盘 | 子女成绩/作业/考勤/课表一站式查看 | P1 |
|
||||
| | 家长会/约谈预约 | 教师发起家长约谈，家长在线预约时段 | P2 |
|
||||
| | 请假审批 | 学生在线请假，教师/班主任审批 | P1 |
|
||||
| | 校园动态/班级圈 | 班级活动照片/视频分享，家长点赞评论 | P2 |
|
||||
| **AI 赋能** | AI 对话助手 | 通用教育场景问答（备课建议、教学策略） | P1 |
|
||||
| | AI 辅助出题 | 根据知识点/难度自动生成题目 | P1 |
|
||||
| | AI 批改辅助 | 简答题/作文 AI 预评分+建议，教师终审 | P2 |
|
||||
| | AI 学情分析 | 基于学习数据的个性化学习路径推荐 | P2 |
|
||||
| | AI 备课助手 | 根据教材章节自动生成教案/课件大纲 | P2 |
|
||||
| | AI 多模型配置 | 支持 Zhipu/OpenAI/Gemini 等多模型切换 | P1 |
|
||||
| | AI API Key 加密存储 | API Key AES 加密，按角色权限访问 | P1 |
|
||||
| **考勤管理** | 学生考勤 | 每日/每节课考勤登记，迟到/早退/缺勤标记 | P1 |
|
||||
| | 教师考勤 | 教师出勤/请假/代课记录 | P1 |
|
||||
| | 考勤统计 | 月度/学期考勤汇总，异常预警 | P2 |
|
||||
| | 考勤规则配置 | 迟到阈值、缺勤预警线、自动通知家长 | P2 |
|
||||
| 模块 | 子功能 | 说明 | 优先级 | 当前实现状态 |
|
||||
|------|--------|------|--------|-------------|
|
||||
| **用户与权限** | 用户注册/登录 | 邮箱/手机号注册，第三方 OAuth 登录 | P0 | ✅ |
|
||||
| | 多角色体系 | 管理员/教师/学生/家长/年级组长/教研组长，支持一人多角色 | P0 | ✅ |
|
||||
| | RBAC 权限模型 | 资源:动作权限点（如 `exam:create`），角色-权限映射 | P0 | ✅ |
|
||||
| | 数据范围控制 | 行级权限：全部/所属/所教班级/所管年级/班级成员/子女 | P0 | ✅ |
|
||||
| | 角色切换 | 多角色用户可主动切换当前活跃角色 | P1 | ❌ |
|
||||
| | 用户档案管理 | 个人信息编辑、头像、联系方式、地址 | P0 | ✅ |
|
||||
| | 新手引导(Onboarding) | 首次登录选择角色、填写资料、加入班级 | P0 | ✅ |
|
||||
| | 组织架构管理 | 部门/年级/教研组树形结构管理 | P1 | ⚠️ |
|
||||
| | 用户批量导入 | Excel/CSV 批量导入学生、教师信息 | P1 | ✅ |
|
||||
| | 密码安全策略 | 密码强度校验、定期更换提醒、登录失败锁定 | P1 | ⚠️ |
|
||||
| **学校管理** | 学校信息配置 | 校名、校徽、地址、学期制度等基础信息 | P0 | ✅ |
|
||||
| | 学年学期管理 | 创建/切换学年学期，学期起止日期，当前学期标记 | P0 | ✅ |
|
||||
| | 年级管理 | 年级创建/编辑/归档，年级组长指派 | P0 | ✅ |
|
||||
| | 班级管理 | 班级创建/编辑/归档，班主任指派，班级邀请码 | P0 | ✅ |
|
||||
| | 学科管理 | 学科创建/编辑，学科代码，学段归属 | P0 | ⚠️ |
|
||||
| | 部门管理 | 教务处/德育处/总务处等行政部门管理 | P1 | ✅ |
|
||||
| | 校区管理 | 多校区信息维护，校区间资源共享策略 | P2 | ❌ |
|
||||
| | 学校参数配置 | 学分制/等级制切换、考号规则、编号规则等 | P1 | ❌ |
|
||||
| **教务排课** | 课程计划管理 | 各年级/班级课程设置，周课时分配 | P0 | ✅ |
|
||||
| | 排课规则配置 | 教师不冲突、教室不冲突、连排/不连排规则 | P0 | ✅ |
|
||||
| | 自动排课引擎 | 基于约束满足的智能排课算法 | P1 | ✅ |
|
||||
| | 课表查看 | 教师/学生/班级/教室多维度课表 | P0 | ✅ |
|
||||
| | 课表调整/代课 | 临时调课、代课安排，自动通知受影响方 | P1 | ❌ |
|
||||
| | 教室资源管理 | 教室类型、容量、设备标签，排课时自动匹配 | P2 | ⚠️ |
|
||||
| | 选课管理 | 选修课选课、退选、抽签规则 | P2 | ✅ |
|
||||
| **教材资源** | 教材库管理 | 教材元数据（学科/年级/版本/出版社） | P0 | ✅ |
|
||||
| | 章节结构管理 | 教材章节树形目录，支持拖拽排序 | P0 | ✅ |
|
||||
| | 知识点图谱 | 知识点与章节关联，知识点间前置/后继关系 | P1 | ⚠️ |
|
||||
| | 教材内容阅读 | 富文本/Markdown 章节内容在线阅读 | P0 | ✅ |
|
||||
| | 教材版本管理 | 同一教材多版本共存，版本切换 | P1 | ❌ |
|
||||
| | 资源附件管理 | 教案/课件/视频等附件上传与关联 | P1 | ✅ |
|
||||
| | 教材审核流程 | 教材内容发布前审核机制 | P2 | ❌ |
|
||||
| **题库与试卷** | 题目创建/编辑 | 选择/填空/判断/简答/综合题，支持子题目 | P0 | ✅ |
|
||||
| | 题目分类标签 | 学科/知识点/难度/题型多维标签 | P0 | ✅ |
|
||||
| | 题目批量导入 | Excel/Word 模板批量导入题目 | P1 | ❌ |
|
||||
| | 题目版本管理 | 题目修改保留历史版本 | P2 | ❌ |
|
||||
| | 试卷手动组卷 | 从题库选题组卷，分数自动汇总 | P0 | ✅ |
|
||||
| | 试卷智能组卷 | 按知识点/难度分布自动抽题 | P1 | ❌ |
|
||||
| | AI 辅助出题 | 大模型根据知识点/要求自动生成题目 | P1 | ✅ |
|
||||
| | 试卷模板管理 | 常用试卷结构模板保存与复用 | P2 | ❌ |
|
||||
| | 试卷预览/打印 | 试卷排版预览，A4/B4 打印适配 | P1 | ⚠️ |
|
||||
| **作业与考试** | 作业布置 | 关联试卷/题目，选择目标班级/学生，设置截止时间 | P0 | ✅ |
|
||||
| | 作业提交 | 学生在线作答，支持文本/图片/附件 | P0 | ✅ |
|
||||
| | 作业批改评分 | 教师逐题评分，支持批注/语音反馈 | P0 | ✅ |
|
||||
| | 迟交/补交策略 | 允许迟交开关、迟交截止时间、迟交标记 | P1 | ⚠️ |
|
||||
| | 多次提交/重做 | 可配置最大尝试次数，取最高分/最后一次 | P1 | ⚠️ |
|
||||
| | 作业统计分析 | 完成率、平均分、分数分布、题目正确率 | P1 | ✅ |
|
||||
| | 作业归档 | 学期结束后作业数据归档，释放活跃数据空间 | P2 | ❌ |
|
||||
| | 在线考试模式 | 限时考试、防切屏、乱序、自动交卷 | P1 | ⚠️ |
|
||||
| | 考试监考 | 教师端实时查看提交进度，异常行为标记 | P2 | ✅ |
|
||||
| **成绩分析** | 成绩录入 | 手动录入/Excel 导入/作业自动同步 | P0 | ✅ |
|
||||
| | 成绩查询 | 学生查本人，教师查所教班级，管理员查全部 | P0 | ⚠️ |
|
||||
| | 成绩统计报表 | 班级/年级均分、中位数、标准差、及格率 | P0 | ✅ |
|
||||
| | 成绩趋势分析 | 历次考试趋势折线图，进步/退步预警 | P1 | ⚠️ |
|
||||
| | 成绩对比分析 | 班级间对比、学科间对比、与年级均分对比 | P1 | ❌ |
|
||||
| | 学情诊断报告 | 基于知识点掌握度的个人/班级诊断报告 | P2 | ✅ |
|
||||
| | 成绩导出 | Excel/PDF 成绩单导出，支持自定义模板 | P1 | ✅ |
|
||||
| | 等第转换 | 分数↔等第(A/B/C/D)自动转换 | P2 | ❌ |
|
||||
| **家校沟通** | 通知公告 | 学校/年级/班级三级公告发布，已读回执 | P0 | ✅ |
|
||||
| | 站内消息 | 教师↔家长、教师↔学生私信，支持群发 | P1 | ✅ |
|
||||
| | 家长端仪表盘 | 子女成绩/作业/考勤/课表一站式查看 | P1 | ⚠️ |
|
||||
| | 家长会/约谈预约 | 教师发起家长约谈，家长在线预约时段 | P2 | ❌ |
|
||||
| | 请假审批 | 学生在线请假，教师/班主任审批 | P1 | ❌ |
|
||||
| | 校园动态/班级圈 | 班级活动照片/视频分享，家长点赞评论 | P2 | ❌ |
|
||||
| **AI 赋能** | AI 对话助手 | 通用教育场景问答（备课建议、教学策略） | P1 | ✅ |
|
||||
| | AI 辅助出题 | 根据知识点/难度自动生成题目 | P1 | ✅ |
|
||||
| | AI 批改辅助 | 简答题/作文 AI 预评分+建议，教师终审 | P2 | ❌ |
|
||||
| | AI 学情分析 | 基于学习数据的个性化学习路径推荐 | P2 | ❌ |
|
||||
| | AI 备课助手 | 根据教材章节自动生成教案/课件大纲 | P2 | ❌ |
|
||||
| | AI 多模型配置 | 支持 Zhipu/OpenAI/Gemini 等多模型切换 | P1 | ✅ |
|
||||
| | AI API Key 加密存储 | API Key AES 加密，按角色权限访问 | P1 | ✅ |
|
||||
| **考勤管理** | 学生考勤 | 每日/每节课考勤登记，迟到/早退/缺勤标记 | P1 | ✅ |
|
||||
| | 教师考勤 | 教师出勤/请假/代课记录 | P1 | ✅ |
|
||||
| | 考勤统计 | 月度/学期考勤汇总，异常预警 | P2 | ✅ |
|
||||
| | 考勤规则配置 | 迟到阈值、缺勤预警线、自动通知家长 | P2 | ⚠️ |
|
||||
|
||||
---
|
||||
|
||||
## 二、平台基础能力
|
||||
|
||||
| 模块 | 子功能 | 说明 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| **消息通知** | 站内通知 | 系统事件推送（作业发布、成绩公布、审批结果） | P0 |
|
||||
| | 邮件通知 | 关键事件邮件推送，通知偏好设置 | P1 |
|
||||
| | 短信通知 | 紧急事件短信推送（需短信网关集成） | P2 |
|
||||
| | 微信/钉钉推送 | 企业微信/钉钉机器人消息推送 | P2 |
|
||||
| | 通知偏好管理 | 用户可按类型/渠道开关通知 | P1 |
|
||||
| **日志审计** | 操作日志 | 关键操作（增删改）记录，含操作人/时间/IP | P0 |
|
||||
| | 登录日志 | 登录/登出记录，异常登录检测 | P0 |
|
||||
| | 数据变更日志 | 重要数据修改前后对比快照 | P1 |
|
||||
| | 日志查询/导出 | 按时间/操作人/模块筛选，支持导出 | P1 |
|
||||
| **文件管理** | 文件上传 | 图片/文档/视频上传，格式与大小校验 | P0 |
|
||||
| | 文件预览 | 图片/PDF/Office 文档在线预览 | P1 |
|
||||
| | 文件存储策略 | 本地/OSS/S3 可切换存储后端 | P1 |
|
||||
| | 文件权限控制 | 文件访问需鉴权，防止未授权访问 | P0 |
|
||||
| **全局搜索** | 全文检索 | 题目/教材/通知/用户等全局搜索 | P1 |
|
||||
| | 搜索建议 | 输入联想、热门搜索、搜索历史 | P2 |
|
||||
| | 搜索过滤 | 按模块/时间/类型筛选搜索结果 | P2 |
|
||||
| **导入导出** | Excel 导入 | 学生/教师/成绩/题目批量导入，模板下载 | P1 |
|
||||
| | Excel/PDF 导出 | 成绩/报表/名单导出，自定义列选择 | P1 |
|
||||
| | 导入校验与错误报告 | 导入数据格式校验，错误行高亮与报告下载 | P1 |
|
||||
| **数据看板** | 管理员仪表盘 | 全校关键指标（师生数/班级数/作业完成率） | P0 |
|
||||
| | 教师仪表盘 | 待批改/今日课表/近期考试/班级动态 | P0 |
|
||||
| | 学生仪表盘 | 今日作业/即将考试/成绩趋势/课表 | P0 |
|
||||
| | 家长仪表盘 | 子女学习概况/待办事项/通知 | P1 |
|
||||
| | 自定义看板 | 用户可拖拽配置看板卡片 | P2 |
|
||||
| 模块 | 子功能 | 说明 | 优先级 | 当前实现状态 |
|
||||
|------|--------|------|--------|-------------|
|
||||
| **消息通知** | 站内通知 | 系统事件推送（作业发布、成绩公布、审批结果） | P0 | ✅ |
|
||||
| | 邮件通知 | 关键事件邮件推送，通知偏好设置 | P1 | ✅ |
|
||||
| | 短信通知 | 紧急事件短信推送（需短信网关集成） | P2 | ✅ |
|
||||
| | 微信/钉钉推送 | 企业微信/钉钉机器人消息推送 | P2 | ✅ |
|
||||
| | 通知偏好管理 | 用户可按类型/渠道开关通知 | P1 | ✅ |
|
||||
| **日志审计** | 操作日志 | 关键操作（增删改）记录，含操作人/时间/IP | P0 | ✅ |
|
||||
| | 登录日志 | 登录/登出记录，异常登录检测 | P0 | ✅ |
|
||||
| | 数据变更日志 | 重要数据修改前后对比快照 | P1 | ✅ |
|
||||
| | 日志查询/导出 | 按时间/操作人/模块筛选，支持导出 | P1 | ⚠️ |
|
||||
| **文件管理** | 文件上传 | 图片/文档/视频上传，格式与大小校验 | P0 | ✅ |
|
||||
| | 文件预览 | 图片/PDF/Office 文档在线预览 | P1 | ❌ |
|
||||
| | 文件存储策略 | 本地/OSS/S3 可切换存储后端 | P1 | ⚠️ |
|
||||
| | 文件权限控制 | 文件访问需鉴权，防止未授权访问 | P0 | ⚠️ |
|
||||
| **全局搜索** | 全文检索 | 题目/教材/通知/用户等全局搜索 | P1 | ⚠️ |
|
||||
| | 搜索建议 | 输入联想、热门搜索、搜索历史 | P2 | ⚠️ |
|
||||
| | 搜索过滤 | 按模块/时间/类型筛选搜索结果 | P2 | ❌ |
|
||||
| **导入导出** | Excel 导入 | 学生/教师/成绩/题目批量导入，模板下载 | P1 | ✅ |
|
||||
| | Excel/PDF 导出 | 成绩/报表/名单导出，自定义列选择 | P1 | ✅ |
|
||||
| | 导入校验与错误报告 | 导入数据格式校验，错误行高亮与报告下载 | P1 | ⚠️ |
|
||||
| **数据看板** | 管理员仪表盘 | 全校关键指标（师生数/班级数/作业完成率） | P0 | ✅ |
|
||||
| | 教师仪表盘 | 待批改/今日课表/近期考试/班级动态 | P0 | ✅ |
|
||||
| | 学生仪表盘 | 今日作业/即将考试/成绩趋势/课表 | P0 | ✅ |
|
||||
| | 家长仪表盘 | 子女学习概况/待办事项/通知 | P1 | ⚠️ |
|
||||
| | 自定义看板 | 用户可拖拽配置看板卡片 | P2 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 三、非功能性模块
|
||||
|
||||
| 模块 | 子功能 | 说明 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| **国际化(i18n)** | 多语言框架 | next-intl/i18next 集成，语言包管理 | P2 |
|
||||
| | 语言切换 | 用户偏好语言，URL 前缀策略 | P2 |
|
||||
| | 日期/数字本地化 | 日期格式、数字分隔符按地区适配 | P2 |
|
||||
| **多租户/多校区** | 租户隔离 | 数据库级/行级租户隔离策略 | P2 |
|
||||
| | 校区资源映射 | 跨校区教师/教室共享规则 | P2 |
|
||||
| | 统一管理后台 | 集团层面多校区数据汇总与对比 | P2 |
|
||||
| **深色主题** | 主题切换 | 亮色/暗色/跟随系统，CSS 变量驱动 | P1 |
|
||||
| | 主题色定制 | 学校品牌色自定义 | P2 |
|
||||
| **无障碍访问** | 键盘导航 | 所有交互可键盘操作，焦点管理 | P1 |
|
||||
| | ARIA 标注 | 语义化 HTML + ARIA 属性 | P1 |
|
||||
| | 屏幕阅读器兼容 | NVDA/VoiceOver 可正确朗读 | P2 |
|
||||
| | 跳转链接 | 跳过导航直达主内容 | P1 |
|
||||
| **性能优化** | 页面懒加载 | 路由级代码分割，组件级 lazy import | P0 |
|
||||
| | 图片优化 | next/image 自动 WebP/AVIF，响应式尺寸 | P0 |
|
||||
| | 缓存策略 | ISR/SSG 混合渲染，客户端缓存 | P1 |
|
||||
| | 性能监控 | Web Vitals 采集，LCP/FID/CLS 告警 | P2 |
|
||||
| **自动化测试** | 单元测试 | Vitest 覆盖工具函数/Hook/类型 | P0 |
|
||||
| | 集成测试 | Server Action + DB mock 端到端验证 | P0 |
|
||||
| | E2E 测试 | Playwright 关键业务流程回归 | P1 |
|
||||
| | 视觉回归测试 | Chromatic/Percy 组件截图对比 | P2 |
|
||||
| **CI/CD** | 持续集成 | Lint + TypeCheck + Test 自动运行 | P0 |
|
||||
| | 持续部署 | main 分支自动构建 Docker 镜像并部署 | P0 |
|
||||
| | 预览环境 | PR 自动创建预览部署 | P2 |
|
||||
| **数据备份** | 数据库定时备份 | 每日全量 + 增量备份策略 | P1 |
|
||||
| | 备份恢复演练 | 定期验证备份数据可恢复性 | P2 |
|
||||
| | 灾备方案 | 异地容灾，RTO/RPO 目标定义 | P2 |
|
||||
| 模块 | 子功能 | 说明 | 优先级 | 当前实现状态 |
|
||||
|------|--------|------|--------|-------------|
|
||||
| **国际化(i18n)** | 多语言框架 | next-intl/i18next 集成，语言包管理 | P2 | ❌ |
|
||||
| | 语言切换 | 用户偏好语言，URL 前缀策略 | P2 | ❌ |
|
||||
| | 日期/数字本地化 | 日期格式、数字分隔符按地区适配 | P2 | ⚠️ |
|
||||
| **多租户/多校区** | 租户隔离 | 数据库级/行级租户隔离策略 | P2 | ❌ |
|
||||
| | 校区资源映射 | 跨校区教师/教室共享规则 | P2 | ❌ |
|
||||
| | 统一管理后台 | 集团层面多校区数据汇总与对比 | P2 | ❌ |
|
||||
| **深色主题** | 主题切换 | 亮色/暗色/跟随系统，CSS 变量驱动 | P1 | ✅ |
|
||||
| | 主题色定制 | 学校品牌色自定义 | P2 | ❌ |
|
||||
| **无障碍访问** | 键盘导航 | 所有交互可键盘操作，焦点管理 | P1 | ⚠️ |
|
||||
| | ARIA 标注 | 语义化 HTML + ARIA 属性 | P1 | ⚠️ |
|
||||
| | 屏幕阅读器兼容 | NVDA/VoiceOver 可正确朗读 | P2 | ✅ |
|
||||
| | 跳转链接 | 跳过导航直达主内容 | P1 | ✅ |
|
||||
| **性能优化** | 页面懒加载 | 路由级代码分割，组件级 lazy import | P0 | ✅ |
|
||||
| | 图片优化 | next/image 自动 WebP/AVIF，响应式尺寸 | P0 | ✅ |
|
||||
| | 缓存策略 | ISR/SSG 混合渲染，客户端缓存 | P1 | ⚠️ |
|
||||
| | 性能监控 | Web Vitals 采集，LCP/FID/CLS 告警 | P2 | ❌ |
|
||||
| **自动化测试** | 单元测试 | Vitest 覆盖工具函数/Hook/类型 | P0 | ✅ |
|
||||
| | 集成测试 | Server Action + DB mock 端到端验证 | P0 | ✅ |
|
||||
| | E2E 测试 | Playwright 关键业务流程回归 | P1 | ⚠️ |
|
||||
| | 视觉回归测试 | Chromatic/Percy 组件截图对比 | P2 | ✅ |
|
||||
| **CI/CD** | 持续集成 | Lint + TypeCheck + Test 自动运行 | P0 | ✅ |
|
||||
| | 持续部署 | main 分支自动构建 Docker 镜像并部署 | P0 | ✅ |
|
||||
| | 预览环境 | PR 自动创建预览部署 | P2 | ❌ |
|
||||
| **数据备份** | 数据库定时备份 | 每日全量 + 增量备份策略 | P1 | ✅ |
|
||||
| | 备份恢复演练 | 定期验证备份数据可恢复性 | P2 | ✅ |
|
||||
| | 灾备方案 | 异地容灾，RTO/RPO 目标定义 | P2 | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 四、合规与安全
|
||||
|
||||
| 模块 | 子功能 | 说明 | 优先级 |
|
||||
|------|--------|------|--------|
|
||||
| **隐私合规** | 隐私政策与用户协议 | 注册时强制同意，版本更新通知 | P0 |
|
||||
| | 未成年人信息保护 | 14 周岁以下需监护人同意，信息最小化收集 | P0 |
|
||||
| | 数据保留策略 | 毕业生数据保留期限，过期自动匿名化 | P1 |
|
||||
| | 用户数据导出/删除 | GDPR 式数据可携带权与被遗忘权 | P2 |
|
||||
| **数据加密** | 传输加密 | HTTPS 强制，HSTS 头 | P0 |
|
||||
| | 存储加密 | 敏感字段（API Key/密码）AES 加密存储 | P0 |
|
||||
| | 密码哈希 | bcrypt/argon2 单向哈希，加盐存储 | P0 |
|
||||
| **操作安全** | CSRF 防护 | SameSite Cookie + CSRF Token | P0 |
|
||||
| | XSS 防护 | 输出编码 + CSP 策略 + rehype-sanitize | P0 |
|
||||
| | SQL 注入防护 | ORM 参数化查询，禁止拼接 SQL | P0 |
|
||||
| | 速率限制 | API 请求频率限制，防暴力破解 | P1 |
|
||||
| | 会话管理 | JWT 过期策略，单点登录/踢出，刷新令牌轮转 | P0 |
|
||||
| **敏感信息脱敏** | 日志脱敏 | 日志中手机号/身份证/邮箱自动掩码 | P1 |
|
||||
| | 前端脱敏 | 家长端/学生端敏感信息掩码显示 | P1 |
|
||||
| | 导出脱敏 | 批量导出时可选脱敏模式 | P2 |
|
||||
| **安全审计** | 漏洞扫描 | 定期 OWASP Top 10 安全扫描 | P1 |
|
||||
| | 依赖审计 | npm audit / Snyk 第三方依赖漏洞检测 | P1 |
|
||||
| | 渗透测试 | 上线前第三方渗透测试 | P2 |
|
||||
| 模块 | 子功能 | 说明 | 优先级 | 当前实现状态 |
|
||||
|------|--------|------|--------|-------------|
|
||||
| **隐私合规** | 隐私政策与用户协议 | 注册时强制同意，版本更新通知 | P0 | ❌ |
|
||||
| | 未成年人信息保护 | 14 周岁以下需监护人同意，信息最小化收集 | P0 | ❌ |
|
||||
| | 数据保留策略 | 毕业生数据保留期限，过期自动匿名化 | P1 | ❌ |
|
||||
| | 用户数据导出/删除 | GDPR 式数据可携带权与被遗忘权 | P2 | ❌ |
|
||||
| **数据加密** | 传输加密 | HTTPS 强制，HSTS 头 | P0 | ✅ |
|
||||
| | 存储加密 | 敏感字段（API Key/密码）AES 加密存储 | P0 | ✅ |
|
||||
| | 密码哈希 | bcrypt/argon2 单向哈希，加盐存储 | P0 | ✅ |
|
||||
| **操作安全** | CSRF 防护 | SameSite Cookie + CSRF Token | P0 | ✅ |
|
||||
| | XSS 防护 | 输出编码 + CSP 策略 + rehype-sanitize | P0 | ✅ |
|
||||
| | SQL 注入防护 | ORM 参数化查询，禁止拼接 SQL | P0 | ✅ |
|
||||
| | 速率限制 | API 请求频率限制，防暴力破解 | P1 | ❌ |
|
||||
| | 会话管理 | JWT 过期策略，单点登录/踢出，刷新令牌轮转 | P0 | ✅ |
|
||||
| **敏感信息脱敏** | 日志脱敏 | 日志中手机号/身份证/邮箱自动掩码 | P1 | ❌ |
|
||||
| | 前端脱敏 | 家长端/学生端敏感信息掩码显示 | P1 | ❌ |
|
||||
| | 导出脱敏 | 批量导出时可选脱敏模式 | P2 | ❌ |
|
||||
| **安全审计** | 漏洞扫描 | 定期 OWASP Top 10 安全扫描 | P1 | ✅ |
|
||||
| | 依赖审计 | npm audit / Snyk 第三方依赖漏洞检测 | P1 | ⚠️ |
|
||||
| | 渗透测试 | 上线前第三方渗透测试 | P2 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
@@ -180,26 +181,27 @@
|
||||
|
||||
| 优先级 | 数量 | 占比 | 定位 |
|
||||
|--------|------|------|------|
|
||||
| **P0** | 52 | 40% | MVP 必须，系统不可缺失的核心能力 |
|
||||
| **P1** | 48 | 37% | 上线前推荐，显著提升产品完整度 |
|
||||
| **P2** | 30 | 23% | 迭代优化，增强竞争力与用户体验 |
|
||||
| **P0** | 52 | 37% | MVP 必须，系统不可缺失的核心能力 |
|
||||
| **P1** | 53 | 38% | 上线前推荐，显著提升产品完整度 |
|
||||
| **P2** | 35 | 25% | 迭代优化，增强竞争力与用户体验 |
|
||||
|
||||
---
|
||||
|
||||
## 与当前项目实现对照
|
||||
## 与当前项目实现对照（2026-06-17 更新）
|
||||
|
||||
| 维度 | 清单 P0 项 | 当前已实现 | 覆盖率 |
|
||||
|------|-----------|-----------|--------|
|
||||
| 用户与权限 | 7 | 7 | 100% |
|
||||
| 学校管理 | 5 | 5 | 100% |
|
||||
| 教务排课 | 2 | 2 | 100% |
|
||||
| 用户与权限 | 6 | 6 | 100% |
|
||||
| 学校管理 | 5 | 4 | 80% |
|
||||
| 教务排课 | 3 | 3 | 100% |
|
||||
| 教材资源 | 3 | 3 | 100% |
|
||||
| 题库与试卷 | 3 | 3 | 100% |
|
||||
| 作业与考试 | 4 | 4 | 100% |
|
||||
| 成绩分析 | 3 | 1 | 33% |
|
||||
| 家校沟通 | 1 | 0 | 0% |
|
||||
| AI 赋能 | 1 | 1 | 100% |
|
||||
| 平台基础 | 5 | 3 | 60% |
|
||||
| 合规安全 | 8 | 8 | 100% |
|
||||
| 作业与考试 | 3 | 3 | 100% |
|
||||
| 成绩分析 | 3 | 2 | 67% |
|
||||
| 家校沟通 | 1 | 1 | 100% |
|
||||
| AI 赋能 | 0 | 0 | — |
|
||||
| 平台基础 | 8 | 7 | 88% |
|
||||
| 合规安全 | 8 | 6 | 75% |
|
||||
|
||||
> 当前项目 P0 覆盖率约 **80%**，主要缺口在成绩分析（统计报表/查询/录入）、家校沟通（通知公告）和平台基础（操作日志/文件权限）。
|
||||
> 当前项目 P0 覆盖率约 **92%**（严格）/ **96%**（含部分完成），主要缺口在隐私合规（隐私政策、未成年人保护）。
|
||||
> P2 新实现 8 项功能：选课管理、考试监考、学情诊断、屏幕阅读器兼容、视觉回归测试、短信/微信推送、漏洞扫描、灾备方案。
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Next_Edu 差距审计报告（v2 — 基于完整架构图）
|
||||
# Next_Edu 差距审计报告（v3 — 基于完整架构图 + 架构审查）
|
||||
|
||||
> 对照《企业级 K12 教务管理系统标准功能模块清单》(006)，基于完整架构影响地图(004/005)与源码全量扫描
|
||||
> 审计日期：2026-06-16（v2 更新）
|
||||
> v2 变更：架构图已全量补全（12 模块 + 46 路由 + 32 表 + 200+ 导出），安全漏洞已修复
|
||||
> 审计日期：2026-06-17（v3 更新）
|
||||
> v3 变更：P0 缺口大幅补齐、8 项 P2 功能新实现、新增架构审查发现（基于 audit/00_summary.md）
|
||||
|
||||
---
|
||||
|
||||
@@ -10,35 +10,65 @@
|
||||
|
||||
| 维度 | P0 子功能总数 | 已完成 | 部分完成 | 未实现 | 完成率 |
|
||||
|------|-------------|--------|---------|--------|--------|
|
||||
| 核心业务 | 31 | 23 | 5 | 3 | **74%** |
|
||||
| 平台基础 | 8 | 3 | 2 | 3 | **38%** |
|
||||
| 非功能性 | 8 | 5 | 2 | 1 | **63%** |
|
||||
| 合规安全 | 8 | 7 | 1 | 0 | **88%** |
|
||||
| **合计** | **55** | **38** | **10** | **7** | **69%** |
|
||||
| 核心业务 | 31 | 28 | 3 | 0 | **90%** |
|
||||
| 平台基础 | 8 | 6 | 2 | 0 | **75%** |
|
||||
| 非功能性 | 8 | 6 | 1 | 1 | **75%** |
|
||||
| 合规安全 | 8 | 6 | 1 | 1 | **75%** |
|
||||
| **合计** | **55** | **46** | **7** | **2** | **84%** |
|
||||
|
||||
> P1 完成率约 **25%**，P2 完成率约 **7%**。
|
||||
> P1 完成率约 **55%**，P2 完成率约 **33%**（总体）/ **57%**（Phase 3 路线图 8/14 项）。
|
||||
|
||||
### v2 修复项
|
||||
### v3 修复项（相对 v2）
|
||||
|
||||
| 修复项 | v1 状态 | v2 状态 | 说明 |
|
||||
| 修复项 | v2 状态 | v3 状态 | 说明 |
|
||||
|--------|---------|---------|------|
|
||||
| school/actions.ts 权限校验 | ❌ 12 个 Action 无权限 | ✅ 全部接入 requirePermission | SCHOOL_MANAGE / GRADE_MANAGE |
|
||||
| settings/actions.ts 权限校验 | ❌ 使用 ensureUser() | ✅ 接入 requirePermission(AI_CONFIGURE) | 移除 auth() 直接调用 |
|
||||
| users/actions.ts 权限校验 | ❌ 使用 auth() | ✅ 接入 requireAuth() | 自助操作用 requireAuth |
|
||||
| 架构图完整性 | ⚠️ 大量缺失 | ✅ 全量补全 | 12 模块 + 46 路由 + 200+ 导出 |
|
||||
| 通知公告系统 | ❌ 完全缺失 | ✅ 已实现 | announcements 模块 + 三级发布 |
|
||||
| 操作/登录日志 | ❌ 完全缺失 | ✅ 已实现 | audit 模块 + auditLogs/loginLogs/dataChangeLogs 表 |
|
||||
| 成绩录入/统计报表 | ❌ 缺失 | ✅ 已实现 | grades 模块 + data-access-analytics + export |
|
||||
| 文件上传 | ❌ 无 | ✅ 已实现 | files 模块 + /api/upload 路由 |
|
||||
| 课程计划管理 | ❌ 无 | ✅ 已实现 | course-plans 模块 |
|
||||
| 排课规则 + 自动排课 | ❌ 无 | ✅ 已实现 | scheduling 模块 + auto-scheduler.ts |
|
||||
| 站内消息 | ❌ 无 | ✅ 已实现 | messaging 模块 |
|
||||
| 站内通知系统 | ❌ 无 | ✅ 已实现 | notifications 模块 + 多渠道分发 |
|
||||
| 用户批量导入 | ❌ 无 | ✅ 已实现 | users/import-export.ts |
|
||||
| 学生/教师考勤 | ❌ 无 | ✅ 已实现 | attendance 模块 + 统计 |
|
||||
| 选课管理 | ❌ 无 | ✅ 已实现 | elective 模块（P2） |
|
||||
| 考试监考 | ❌ 无 | ✅ 已实现 | proctoring 模块（P2） |
|
||||
| 学情诊断报告 | ❌ 无 | ✅ 已实现 | diagnostic 模块（P2） |
|
||||
| 短信/微信推送 | ❌ 无 | ✅ 已实现 | notifications/channels（P2） |
|
||||
| 屏幕阅读器兼容 | ❌ 未测试 | ✅ 已实现 | shared/lib/a11y.ts + components/a11y（P2） |
|
||||
| 视觉回归测试 | ❌ 无 | ✅ 已实现 | tests/visual/ + Playwright（P2） |
|
||||
| 漏洞扫描 | ❌ 无 | ✅ 已实现 | scripts/security-scan.sh/ps1 |
|
||||
| 灾备方案 | ❌ 无 | ✅ 已实现 | scripts/backup-offsite-sync.sh 等 |
|
||||
| 幽灵导航路由 | ⚠️ 13 个 | ✅ 已修复 | navigation.ts 已清理无效路由 |
|
||||
|
||||
### 关键风险项（v2 更新后）
|
||||
### 关键风险项（v3 更新后）
|
||||
|
||||
1. **通知公告系统完全缺失** — P0 级功能，家校沟通核心载体，无任何代码实现
|
||||
2. **操作/登录日志完全缺失** — P0 级功能，合规审计基础，无 DB 表、无代码
|
||||
3. **成绩分析严重不足** — 仅有作业维度的分数趋势，缺少独立的成绩录入/统计报表/查询模块
|
||||
4. **文件上传/权限控制缺失** — 当前无文件上传能力，题目/教材无法关联附件
|
||||
5. **13 个幽灵导航路由** — navigation.ts 引用了 13 个不存在的页面（/admin/users/*, /courses/*, /reports, /finance, /parent/children, /parent/tuition, /messages），用户点击会 404
|
||||
> v2 的 5 个关键风险项中，4 个已修复，1 个仍存在。新增 5 个架构审查发现的风险。
|
||||
|
||||
**已修复的风险（v2 → v3）：**
|
||||
1. ~~通知公告系统完全缺失~~ → ✅ 已实现 announcements 模块
|
||||
2. ~~操作/登录日志完全缺失~~ → ✅ 已实现 audit 模块
|
||||
3. ~~成绩分析严重不足~~ → ✅ 已实现 grades 模块（录入/统计/导出）
|
||||
4. ~~文件上传/权限控制缺失~~ → ✅ 已实现 files 模块 + /api/upload
|
||||
5. ~~13 个幽灵导航路由~~ → ✅ 已修复
|
||||
|
||||
**当前关键风险项（v3）：**
|
||||
|
||||
1. **`classes/data-access.ts` 严重超标** — 2104 行，超出 1000 行硬上限 2 倍，混入 homework/scheduling/grades 三个业务领域逻辑，维护风险极高
|
||||
2. **`shared/lib` ↔ `auth` 循环依赖** — audit-logger/change-logger/auth-guard → @/auth → shared/lib/* 形成循环，影响构建稳定性
|
||||
3. **dashboard 跨模块直接查询 11 张表** — getAdminDashboardData 直查 sessions/users/classes/textbooks 等 11 张表，严重违反模块封装
|
||||
4. **messaging 绕过 notifications 直接写通知** — messaging/actions.ts 直接调用 createNotification，导致用户通知偏好失效
|
||||
5. **classSchedule 表三处写入口** — classes/scheduling 模块各自直接写入，数据完整性高风险
|
||||
6. **proctoring 死代码** — exam-mode-config.tsx 组件已创建但未集成到考试表单，DB schema 有 examMode 字段但表单不收集
|
||||
7. **隐私合规 P0 缺口** — 隐私政策与用户协议、未成年人信息保护仍未实现，K12 强制要求
|
||||
|
||||
---
|
||||
|
||||
## 二、功能差距明细表
|
||||
|
||||
> 图例：✅ 已完成 / ⚠️ 部分完成 / ❌ 未实现 / 🆕 v3 新实现
|
||||
|
||||
### 核心业务模块
|
||||
|
||||
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|
||||
@@ -48,62 +78,62 @@
|
||||
| | RBAC 权限模型 | ✅ | 30 个权限点，ROLE_PERMISSIONS 映射 | — |
|
||||
| | 数据范围控制 | ✅ | DataScope 6 种类型 | — |
|
||||
| | 角色切换 | ❌ | JWT 存 roles[]，但无主动切换 UI | 新增角色切换下拉组件 |
|
||||
| | 用户档案管理 | ✅ | users 模块 updateUserProfile + getUserProfile，profile 页可编辑 | — |
|
||||
| | 用户档案管理 | ✅ | users 模块 updateUserProfile + getUserProfile | — |
|
||||
| | 新手引导 | ✅ | OnboardingGate 组件 | — |
|
||||
| | 组织架构管理 | ⚠️ | 部门/年级 CRUD 已有，但无教研组管理 | 新增 teachingGroups 表 |
|
||||
| | 用户批量导入 | ❌ | 无导入功能 | Excel 解析 + 批量 insert |
|
||||
| | 密码安全策略 | ⚠️ | NextAuth 默认 bcrypt，但无强度校验、无锁定策略 | 前端强度校验 + 后端锁定 |
|
||||
| **学校管理** | 学校信息配置 | ✅ | schools 表 + CRUD，requirePermission(SCHOOL_MANAGE) | — |
|
||||
| | 用户批量导入 | 🆕 ✅ | users/import-export.ts 实现 Excel 导入 | — |
|
||||
| | 密码安全策略 | ⚠️ | NextAuth 默认 bcrypt，有锁定策略，但无强度校验 | 前端强度校验 |
|
||||
| **学校管理** | 学校信息配置 | ✅ | schools 表 + CRUD | — |
|
||||
| | 学年学期管理 | ✅ | academicYears 表 + CRUD | — |
|
||||
| | 年级管理 | ✅ | grades 表 + CRUD，requirePermission(GRADE_MANAGE) | — |
|
||||
| | 年级管理 | ✅ | grades 表 + CRUD | — |
|
||||
| | 班级管理 | ✅ | classes 表 + 17 个 actions，含邀请码 | — |
|
||||
| | 学科管理 | ⚠️ | subjects 表存在，但仅有 name/order/code | 扩展学段归属字段 |
|
||||
| | 部门管理 | ✅ | departments 表 + CRUD | — |
|
||||
| | 校区管理 | ❌ | 无校区概念 | 新增 campuses 表 |
|
||||
| | 学校参数配置 | ❌ | 无参数配置功能 | 新增 schoolSettings KV 表 |
|
||||
| **教务排课** | 课程计划管理 | ❌ | classSchedule 表仅存单条课表项 | 新增 coursePlans 表 |
|
||||
| | 排课规则配置 | ❌ | 无规则引擎 | 新增 schedulingRules 表 |
|
||||
| | 自动排课引擎 | ❌ | 无 | CSP 求解器 |
|
||||
| | 课表查看 | ✅ | 教师课表 + 学生课表 + 班级课表，含 ScheduleView/ScheduleFilters 组件 | — |
|
||||
| **教务排课** | 课程计划管理 | 🆕 ✅ | course-plans 模块已实现 | — |
|
||||
| | 排课规则配置 | 🆕 ✅ | scheduling 模块 + SchedulingRule 类型 | — |
|
||||
| | 自动排课引擎 | 🆕 ✅ | scheduling/auto-scheduler.ts 纯函数算法 | — |
|
||||
| | 课表查看 | ✅ | 教师课表 + 学生课表 + 班级课表 | — |
|
||||
| | 课表调整/代课 | ❌ | 仅 CRUD 课表项 | 新增 scheduleChanges 表 + 审批流 |
|
||||
| | 教室资源管理 | ⚠️ | classrooms 表(name/building/floor/capacity)，但无管理 UI | 增加 CRUD 页面 |
|
||||
| | 选课管理 | ❌ | 无 | 新增 electiveCourses 表 |
|
||||
| | 教室资源管理 | ⚠️ | classrooms 表存在，但无管理 UI | 增加 CRUD 页面 |
|
||||
| | 选课管理 | 🆕 ✅ | elective 模块（CRUD + 选课 + 抽签） | — |
|
||||
| **教材资源** | 教材库管理 | ✅ | textbooks 表 + createTextbookAction | — |
|
||||
| | 章节结构管理 | ✅ | chapters 树形结构 + reorderChaptersAction 拖拽排序 | — |
|
||||
| | 章节结构管理 | ✅ | chapters 树形结构 + reorderChaptersAction | — |
|
||||
| | 知识点图谱 | ⚠️ | knowledgePoints 有 CRUD + 章节关联，但无前置/后继关系 | 增加 prerequisiteEdges 表 |
|
||||
| | 教材内容阅读 | ✅ | TextbookContentPanel，Markdown + rehype-sanitize | — |
|
||||
| | 教材版本管理 | ❌ | 无版本概念 | 增加 version 字段 |
|
||||
| | 资源附件管理 | ❌ | 无文件上传能力 | 新增 attachments 表 |
|
||||
| | 资源附件管理 | 🆕 ✅ | files 模块 + fileAttachments 表 + /api/upload | — |
|
||||
| | 教材审核流程 | ❌ | 无审核机制 | 新增 reviewWorkflow 表 |
|
||||
| **题库与试卷** | 题目创建/编辑 | ✅ | 5 种题型，支持子题目，CreateQuestionDialog | — |
|
||||
| | 题目分类标签 | ✅ | 知识点关联 + difficulty + type 多维标签 | — |
|
||||
| | 题目批量导入 | ❌ | 无 | Excel 模板 + 批量解析 |
|
||||
| | 题目版本管理 | ❌ | 无 | 增加 questionVersions 表 |
|
||||
| | 试卷手动组卷 | ✅ | ExamAssembly 组件 + StructureEditor + QuestionBankList | — |
|
||||
| | 试卷手动组卷 | ✅ | ExamAssembly 组件 + StructureEditor | — |
|
||||
| | 试卷智能组卷 | ❌ | 无自动抽题 | 按知识点/难度分布随机抽题 |
|
||||
| | AI 辅助出题 | ✅ | ai-pipeline.ts：3 个 AI 生成函数 + generateAiExamDraft | — |
|
||||
| | AI 辅助出题 | ✅ | ai-pipeline.ts：3 个 AI 生成函数 | — |
|
||||
| | 试卷模板管理 | ❌ | 无 | 新增 examTemplates 表 |
|
||||
| | 试卷预览/打印 | ⚠️ | ExamPreviewDialog 可预览，但无打印适配 | 增加 @media print |
|
||||
| **作业与考试** | 作业布置 | ✅ | createHomeworkAssignmentAction + HomeworkAssignmentForm | — |
|
||||
| | 作业提交 | ✅ | startHomeworkSubmissionAction + saveHomeworkAnswerAction + submitHomeworkAction | — |
|
||||
| **作业与考试** | 作业布置 | ✅ | createHomeworkAssignmentAction | — |
|
||||
| | 作业提交 | ✅ | startHomeworkSubmissionAction + submitHomeworkAction | — |
|
||||
| | 作业批改评分 | ✅ | gradeHomeworkSubmissionAction + HomeworkGradingView | — |
|
||||
| | 迟交/补交策略 | ⚠️ | allowLate/lateDueAt 字段存在，前端未暴露配置 | 作业创建表单增加开关 |
|
||||
| | 多次提交/重做 | ⚠️ | maxAttempts 字段存在，有次数检查 | 前端暴露配置 + 重做入口 |
|
||||
| | 作业统计分析 | ✅ | getHomeworkAssignmentAnalytics + HomeworkAssignmentQuestionErrorOverviewCard | — |
|
||||
| | 作业统计分析 | ✅ | getHomeworkAssignmentAnalytics | — |
|
||||
| | 作业归档 | ❌ | 无归档机制 | 增加 archivedAt 字段 |
|
||||
| | 在线考试模式 | ❌ | 无限时/防切屏/乱序/自动交卷 | 新增 examMode + 前端计时器 |
|
||||
| | 考试监考 | ❌ | 无 | WebSocket 实时推送 |
|
||||
| **成绩分析** | 成绩录入 | ❌ | 无独立成绩录入功能 | 新增 gradeRecords 表 + 录入 UI |
|
||||
| | 成绩查询 | ⚠️ | 学生仪表盘有作业分数(getStudentDashboardGrades)，无独立查询页 | 新增成绩查询页面 |
|
||||
| | 成绩统计报表 | ❌ | 无班级/年级均分、中位数、标准差统计 | 新增聚合查询 + 图表 |
|
||||
| | 在线考试模式 | ⚠️ | examMode 字段存在，但 exam-mode-config.tsx 未集成 | 集成组件到考试表单 |
|
||||
| | 考试监考 | 🆕 ✅ | proctoring 模块（事件上报 + 监考面板 + 防作弊） | — |
|
||||
| **成绩分析** | 成绩录入 | 🆕 ✅ | grades 模块 + gradeRecords 表 + 批量录入 | — |
|
||||
| | 成绩查询 | ⚠️ | grades/data-access 有查询，但无独立查询页 | 新增成绩查询页面 |
|
||||
| | 成绩统计报表 | 🆕 ✅ | grades/data-access-analytics.ts 班级统计 + 排名 | — |
|
||||
| | 成绩趋势分析 | ⚠️ | getTeacherGradeTrends 提供教师维度趋势 | 扩展为多维度 |
|
||||
| | 成绩对比分析 | ❌ | 无班级间/学科间对比 | 新增对比查询 + 雷达图 |
|
||||
| | 学情诊断报告 | ❌ | 无 | 基于知识点掌握度生成诊断 |
|
||||
| | 成绩导出 | ❌ | 无导出功能 | ExcelJS/PDFKit 导出 |
|
||||
| | 学情诊断报告 | 🆕 ✅ | diagnostic 模块（个人/班级诊断报告） | — |
|
||||
| | 成绩导出 | 🆕 ✅ | grades/export.ts Excel 导出 | — |
|
||||
| | 等第转换 | ❌ | 无 | 新增 gradeScale 配置 |
|
||||
| **家校沟通** | 通知公告 | ❌ | 完全缺失 | 新增 announcements 表 + 三级发布 |
|
||||
| | 站内消息 | ❌ | 无 | 新增 messages 表 |
|
||||
| | 家长端仪表盘 | ⚠️ | /parent/dashboard 路由存在但组件为空壳 | 接入子女数据查询 |
|
||||
| **家校沟通** | 通知公告 | 🆕 ✅ | announcements 模块 + 三级发布 | — |
|
||||
| | 站内消息 | 🆕 ✅ | messaging 模块 + 通知偏好 | — |
|
||||
| | 家长端仪表盘 | ⚠️ | parent 模块有 data-access，但组件不完整 | 接入子女数据查询 |
|
||||
| | 家长会/约谈预约 | ❌ | 无 | 新增 appointments 表 |
|
||||
| | 请假审批 | ❌ | 无 | 新增 leaveRequests 表 |
|
||||
| | 校园动态/班级圈 | ❌ | 无 | 新增 posts 表 |
|
||||
@@ -112,40 +142,40 @@
|
||||
| | AI 批改辅助 | ❌ | 无 | 接入 AI 评分 prompt + 教师终审 |
|
||||
| | AI 学情分析 | ❌ | 无 | 基于作业数据生成学习路径 |
|
||||
| | AI 备课助手 | ❌ | 无 | 根据教材章节生成教案 |
|
||||
| | AI 多模型配置 | ✅ | aiProviders 表 + upsertAiProviderAction，requirePermission(AI_CONFIGURE) | — |
|
||||
| | AI 多模型配置 | ✅ | aiProviders 表 + upsertAiProviderAction | — |
|
||||
| | AI API Key 加密 | ✅ | AES 加密 | — |
|
||||
| **考勤管理** | 学生考勤 | ❌ | 无 | 新增 attendanceRecords 表 |
|
||||
| | 教师考勤 | ❌ | 无 | 同上 |
|
||||
| | 考勤统计 | ❌ | 无 | 聚合查询 + 报表 |
|
||||
| | 考勤规则配置 | ❌ | 无 | 新增 attendanceRules 配置 |
|
||||
| **考勤管理** | 学生考勤 | 🆕 ✅ | attendance 模块 + 考勤登记 | — |
|
||||
| | 教师考勤 | 🆕 ✅ | attendance 模块 | — |
|
||||
| | 考勤统计 | 🆕 ✅ | attendance/data-access-stats.ts 月度汇总 | — |
|
||||
| | 考勤规则配置 | ⚠️ | 有基础规则，但无完整配置 UI | 增加规则配置页面 |
|
||||
|
||||
### 平台基础能力
|
||||
|
||||
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|
||||
|----------|------------|------|-------------|----------|
|
||||
| **消息通知** | 站内通知 | ❌ | 无通知系统 | 新增 notifications 表 + 推送 |
|
||||
| | 邮件通知 | ❌ | 无 | 集成 nodemailer/Resend |
|
||||
| | 短信通知 | ❌ | 无 | 集成短信网关 |
|
||||
| | 微信/钉钉推送 | ❌ | 无 | 集成 webhook |
|
||||
| | 通知偏好管理 | ❌ | 无 | 新增 notificationPreferences 表 |
|
||||
| **日志审计** | 操作日志 | ❌ | 完全缺失 | 新增 auditLogs 表 + action 拦截器 |
|
||||
| | 登录日志 | ❌ | 无 | 新增 loginLogs 表 + NextAuth event |
|
||||
| | 数据变更日志 | ❌ | 无 | Drizzle middleware 或 trigger |
|
||||
| | 日志查询/导出 | ❌ | 无 | 管理员日志查询页面 |
|
||||
| **文件管理** | 文件上传 | ❌ | 无文件上传能力 | 新增 upload API + 存储 |
|
||||
| **消息通知** | 站内通知 | 🆕 ✅ | notifications 模块 + dispatcher 多渠道分发 | — |
|
||||
| | 邮件通知 | 🆕 ✅ | notifications/channels/email-channel.ts | — |
|
||||
| | 短信通知 | 🆕 ✅ | notifications/channels/sms-channel.ts | — |
|
||||
| | 微信/钉钉推送 | 🆕 ✅ | notifications/channels/wechat-channel.ts | — |
|
||||
| | 通知偏好管理 | 🆕 ✅ | messaging/notification-preferences.ts | — |
|
||||
| **日志审计** | 操作日志 | 🆕 ✅ | audit 模块 + auditLogs 表 + logAudit | — |
|
||||
| | 登录日志 | 🆕 ✅ | audit 模块 + loginLogs 表 + NextAuth event | — |
|
||||
| | 数据变更日志 | 🆕 ✅ | audit 模块 + dataChangeLogs 表 + change-logger | — |
|
||||
| | 日志查询/导出 | ⚠️ | audit/data-access 有分页查询，但无导出 | 增加导出功能 |
|
||||
| **文件管理** | 文件上传 | 🆕 ✅ | files 模块 + /api/upload + fileAttachments 表 | — |
|
||||
| | 文件预览 | ❌ | 无 | 集成文件预览服务 |
|
||||
| | 文件存储策略 | ❌ | 无 | 抽象 StorageProvider 接口 |
|
||||
| | 文件权限控制 | ❌ | 无 | 文件访问鉴权中间件 |
|
||||
| **全局搜索** | 全文检索 | ❌ | 无 | 集成 Meilisearch/Typesense |
|
||||
| | 搜索建议 | ❌ | 无 | 搜索 API + 前端联想 |
|
||||
| | 文件存储策略 | ⚠️ | 有本地存储，无 OSS/S3 抽象 | 抽象 StorageProvider 接口 |
|
||||
| | 文件权限控制 | ⚠️ | 有基础鉴权，但不完整 | 完善文件访问鉴权 |
|
||||
| **全局搜索** | 全文检索 | ⚠️ | global-search.tsx 组件 + /api/search 路由 | 集成 Meilisearch/Typesense |
|
||||
| | 搜索建议 | ⚠️ | 有基础联想 | 搜索 API + 前端联想 |
|
||||
| | 搜索过滤 | ❌ | 无 | 搜索结果筛选器 |
|
||||
| **导入导出** | Excel 导入 | ❌ | 无 | ExcelJS 解析 + 校验 |
|
||||
| | Excel/PDF 导出 | ❌ | 无 | ExcelJS/PDFKit 生成 |
|
||||
| | 导入校验与错误报告 | ❌ | 无 | 行级校验 + 错误报告 |
|
||||
| **导入导出** | Excel 导入 | 🆕 ✅ | users/import-export.ts 实现 | — |
|
||||
| | Excel/PDF 导出 | 🆕 ✅ | grades/export.ts + users/import-export.ts | — |
|
||||
| | 导入校验与错误报告 | ⚠️ | 有基础校验，无错误报告下载 | 行级校验 + 错误报告 |
|
||||
| **数据看板** | 管理员仪表盘 | ✅ | getAdminDashboardData + AdminDashboardView | — |
|
||||
| | 教师仪表盘 | ✅ | TeacherDashboardView + 9 个子组件 | — |
|
||||
| | 学生仪表盘 | ✅ | StudentDashboard + 5 个子组件 | — |
|
||||
| | 家长仪表盘 | ⚠️ | 路由存在但组件为空壳 | 接入子女数据 |
|
||||
| | 家长仪表盘 | ⚠️ | parent 模块有 data-access，组件不完整 | 接入子女数据 |
|
||||
| | 自定义看板 | ❌ | 无 | 拖拽布局 + localStorage |
|
||||
|
||||
### 非功能性模块
|
||||
@@ -162,7 +192,7 @@
|
||||
| | 主题色定制 | ❌ | 无 | CSS 变量动态注入 |
|
||||
| **无障碍访问** | 键盘导航 | ⚠️ | 部分组件支持，但非系统性 | 全面键盘测试 |
|
||||
| | ARIA 标注 | ⚠️ | icon 按钮 aria-label 已加，非全覆盖 | 系统性 ARIA 审计 |
|
||||
| | 屏幕阅读器兼容 | ❌ | 未测试 | NVDA/VoiceOver 测试 |
|
||||
| | 屏幕阅读器兼容 | 🆕 ✅ | shared/lib/a11y.ts + components/a11y/ 4 组件 | — |
|
||||
| | 跳转链接 | ✅ | layout.tsx 有 skip-link | — |
|
||||
| **性能优化** | 页面懒加载 | ✅ | Next.js App Router 自动代码分割 | — |
|
||||
| | 图片优化 | ✅ | next/image 使用 | — |
|
||||
@@ -171,13 +201,13 @@
|
||||
| **自动化测试** | 单元测试 | ✅ | Vitest 5 文件 19 用例 | 扩展覆盖率 |
|
||||
| | 集成测试 | ✅ | Vitest 7 文件 38 用例 | 扩展覆盖率 |
|
||||
| | E2E 测试 | ⚠️ | Playwright 3 个 spec，需数据库环境 | 完善 CI 环境配置 |
|
||||
| | 视觉回归测试 | ❌ | 无 | 集成 Chromatic |
|
||||
| | 视觉回归测试 | 🆕 ✅ | tests/visual/ 4 个 spec + 多视口/主题 | — |
|
||||
| **CI/CD** | 持续集成 | ✅ | .gitea/workflows/ci.yml | — |
|
||||
| | 持续部署 | ✅ | Dockerfile + CI 自动构建部署 | — |
|
||||
| | 预览环境 | ❌ | 无 | PR 预览部署 |
|
||||
| **数据备份** | 数据库定时备份 | ❌ | 无 | cron + mysqldump |
|
||||
| | 备份恢复演练 | ❌ | 无 | 定期恢复测试 |
|
||||
| | 灾备方案 | ❌ | 无 | 异地容灾规划 |
|
||||
| **数据备份** | 数据库定时备份 | 🆕 ✅ | scripts/backup-db.sh | — |
|
||||
| | 备份恢复演练 | 🆕 ✅ | scripts/backup-verify.sh + test-backup.sh | — |
|
||||
| | 灾备方案 | 🆕 ✅ | scripts/backup-offsite-sync.sh 异地同步 | — |
|
||||
|
||||
### 合规与安全
|
||||
|
||||
@@ -196,100 +226,195 @@
|
||||
| | 速率限制 | ❌ | 无 | 集成 upstash/ratelimit |
|
||||
| | 会话管理 | ✅ | JWT 过期策略 + NextAuth | — |
|
||||
| | **Server Action 权限校验** | ✅ | **v2 修复：全部 57+ Server Action 均使用 requirePermission/requireAuth** | — |
|
||||
| **敏感信息脱敏** | 日志脱敏 | ❌ | 无日志系统 | 日志框架内置脱敏 |
|
||||
| **敏感信息脱敏** | 日志脱敏 | ❌ | 无日志框架内置脱敏 | 日志框架内置脱敏 |
|
||||
| | 前端脱敏 | ❌ | 无 | 手机号/邮箱掩码组件 |
|
||||
| | 导出脱敏 | ❌ | 无导出功能 | 导出时可选脱敏 |
|
||||
| **安全审计** | 漏洞扫描 | ❌ | 无 | 集成 OWASP ZAP/Snyk |
|
||||
| | 导出脱敏 | ❌ | 无导出脱敏 | 导出时可选脱敏 |
|
||||
| **安全审计** | 漏洞扫描 | 🆕 ✅ | scripts/security-scan.sh + security-scan.ps1 | — |
|
||||
| | 依赖审计 | ⚠️ | npm audit 可用但未集成 CI | CI 增加 npm audit |
|
||||
| | 渗透测试 | ❌ | 无 | 上线前第三方测试 |
|
||||
|
||||
---
|
||||
|
||||
## 三、优先补齐路线图
|
||||
## 三、P2 实现进度表（Phase 3 路线图）
|
||||
|
||||
### Phase 1: P0 缺口补齐（MVP 必须项）
|
||||
> v3 新增章节：追踪 Phase 3 P2 迭代优化功能的实现进度
|
||||
|
||||
> 目标：将 P0 完成率从 69% 提升到 100%
|
||||
| P2 功能 | 状态 | 实现日期 | 实现模块/文件 |
|
||||
|---------|------|---------|-------------|
|
||||
| 选课管理 | ✅ | 2026-06-17 | src/modules/elective/ |
|
||||
| 考试监考 | ✅ | 2026-06-17 | src/modules/proctoring/ |
|
||||
| 学情诊断 | ✅ | 2026-06-17 | src/modules/diagnostic/ |
|
||||
| 屏幕阅读器 | ✅ | 2026-06-17 | src/shared/lib/a11y.ts + components/a11y/ |
|
||||
| 视觉回归 | ✅ | 2026-06-17 | tests/visual/ + visual.config.ts |
|
||||
| 通知渠道 | ✅ | 2026-06-17 | src/modules/notifications/channels/ |
|
||||
| 漏洞扫描 | ✅ | 2026-06-17 | scripts/security-scan.sh/ps1 |
|
||||
| 灾备方案 | ✅ | 2026-06-17 | scripts/backup-offsite-sync.sh 等 |
|
||||
| AI 批改辅助 | ❌ | - | — |
|
||||
| AI 学情分析 | ❌ | - | — |
|
||||
| AI 备课助手 | ❌ | - | — |
|
||||
| 国际化 | ❌ | - | — |
|
||||
| 多租户 | ❌ | - | — |
|
||||
| 主题色定制 | ❌ | - | — |
|
||||
|
||||
| 序号 | 功能 | 所属模块 | 工作量 | 理由 |
|
||||
|------|------|---------|--------|------|
|
||||
| 1 | **通知公告系统** | 家校沟通 | 大 | P0 缺失最严重项，学校运营核心需求 |
|
||||
| 2 | **操作日志 + 登录日志** | 日志审计 | 大 | P0 合规底线，无日志则无法追溯 |
|
||||
| 3 | **成绩录入 + 查询 + 统计报表** | 成绩分析 | 大 | P0 教务核心闭环缺失 |
|
||||
| 4 | **文件上传 + 权限控制** | 文件管理 | 中 | P0 基础能力，题目/教材/通知需附件 |
|
||||
| 5 | **课程计划管理** | 教务排课 | 中 | P0 排课前置条件 |
|
||||
| 6 | **隐私政策 + 用户同意** | 隐私合规 | 小 | P0 合规底线 |
|
||||
| 7 | **未成年人信息保护** | 隐私合规 | 小 | P0 K12 强制要求 |
|
||||
| 8 | **修复 13 个幽灵导航路由** | 布局 | 小 | 用户点击 404，影响体验 |
|
||||
|
||||
### Phase 2: P1 关键增强（上线前推荐）
|
||||
|
||||
| 序号 | 功能 | 所属模块 | 理由 |
|
||||
|------|------|---------|------|
|
||||
| 1 | 站内消息系统 | 家校沟通 | 教师与家长沟通核心渠道 |
|
||||
| 2 | 家长端仪表盘 | 家校沟通 | 家长核心入口，当前为空壳 |
|
||||
| 3 | Excel 批量导入 | 导入导出 | 开学季批量导入学生/教师 |
|
||||
| 4 | Excel/PDF 导出 | 导入导出 | 成绩单/名单导出 |
|
||||
| 5 | 排课规则 + 自动排课 | 教务排课 | 手动排课效率极低 |
|
||||
| 6 | 课表调整/代课 | 教务排课 | 日常调课高频操作 |
|
||||
| 7 | 速率限制 | 操作安全 | 防暴力破解 |
|
||||
| 8 | 成绩趋势 + 对比分析 | 成绩分析 | 教学质量分析核心 |
|
||||
| 9 | 成绩导出 | 成绩分析 | 家长会/教研会必备 |
|
||||
| 10 | 学生考勤 | 考勤管理 | 日常管理刚需 |
|
||||
| 11 | 用户批量导入 | 用户与权限 | 开学季批量注册 |
|
||||
| 12 | 密码安全策略 | 用户与权限 | 安全基线 |
|
||||
| 13 | 数据变更日志 | 日志审计 | 争议追溯 |
|
||||
| 14 | 日志查询/导出 | 日志审计 | 管理员日常使用 |
|
||||
| 15 | 文件预览 + 存储策略 | 文件管理 | 用户体验提升 |
|
||||
| 16 | 全文检索 | 全局搜索 | 题库/教材量大后必须 |
|
||||
| 17 | 依赖审计集成 CI | 安全审计 | 安全基线 |
|
||||
| 18 | 数据库定时备份 | 数据备份 | 数据安全底线 |
|
||||
| 19 | E2E 测试完善 | 自动化测试 | 上线前回归保障 |
|
||||
| 20 | 通知偏好管理 | 消息通知 | 用户体验 |
|
||||
|
||||
### Phase 3: P2 迭代优化（竞争力提升）
|
||||
|
||||
| 序号 | 功能 | 所属模块 | 理由 |
|
||||
|------|------|---------|------|
|
||||
| 1 | 国际化(i18n) | 非功能性 | 海外学校/国际学校市场 |
|
||||
| 2 | 多租户/多校区 | 非功能性 | 集团化办学市场 |
|
||||
| 3 | 主题色定制 | 深色主题 | 学校品牌化 |
|
||||
| 4 | 屏幕阅读器兼容 | 无障碍 | 合规 + 社会责任 |
|
||||
| 5 | 视觉回归测试 | 自动化测试 | UI 变更质量保障 |
|
||||
| 6 | AI 批改辅助 | AI 赋能 | 教师效率提升 |
|
||||
| 7 | AI 学情分析 | AI 赋能 | 个性化学习差异化 |
|
||||
| 8 | AI 备课助手 | AI 赋能 | 教师备课效率 |
|
||||
| 9 | 选课管理 | 教务排课 | 高中选修课场景 |
|
||||
| 10 | 考试监考 | 作业与考试 | 在线考试完整性 |
|
||||
| 11 | 学情诊断报告 | 成绩分析 | 精准教学 |
|
||||
| 12 | 短信/微信推送 | 消息通知 | 紧急事件触达 |
|
||||
| 13 | 漏洞扫描 + 渗透测试 | 安全审计 | 上线后安全验证 |
|
||||
| 14 | 灾备方案 | 数据备份 | 业务连续性 |
|
||||
**P2 路线图完成率：8/14 = 57%**
|
||||
|
||||
---
|
||||
|
||||
## 四、差距统计摘要
|
||||
## 四、架构技术债（基于架构审查 audit/00_summary.md）
|
||||
|
||||
> v3 新增章节：基于 2026-06-17 架构审查发现的 P0/P1 问题
|
||||
|
||||
### 4.1 P0 严重问题（必须修复）
|
||||
|
||||
| 序号 | 问题 | 文件/位置 | 严重程度 | 说明 |
|
||||
|------|------|----------|---------|------|
|
||||
| 1 | 文件超 1000 行硬上限 | `classes/data-access.ts` (2104 行) | 🔴 严重 | 混入 homework/scheduling/grades 三个业务领域逻辑，超出硬上限 2 倍 |
|
||||
| 2 | 文件超 1000 行硬上限 | `homework/data-access.ts` (1038 行) | 🔴 严重 | 混入排名计算业务逻辑，超出硬上限 |
|
||||
| 3 | 文件超 1000 行硬上限 | `shared/db/schema.ts` (1111 行) | 🟡 需改进 | 54 张表混合，可接受但需按业务域分节 |
|
||||
| 4 | 循环依赖 | `shared/lib` ↔ `@/auth` | 🔴 严重 | audit-logger/change-logger/auth-guard → @/auth → shared/lib/* 形成循环 |
|
||||
| 5 | dashboard 跨模块直查 11 张表 | `dashboard/data-access.ts` | 🔴 严重 | getAdminDashboardData 直查 sessions/users/classes 等 11 张表，违反模块封装 |
|
||||
| 6 | messaging 绕过 notifications | `messaging/actions.ts` 第 66-72 行 | 🔴 严重 | 直接调用 createNotification，导致通知偏好失效 |
|
||||
| 7 | classSchedule 三处写入口 | classes/scheduling 模块 | 🔴 严重 | 数据完整性高风险，无统一入口 |
|
||||
|
||||
### 4.2 P1 较严重问题
|
||||
|
||||
| 序号 | 问题 | 说明 |
|
||||
|------|------|------|
|
||||
| 8 | 跨模块直接 DB 查询普遍 | classes(8+)/classEnrollments(6+)/users(6+)/subjects(6+)/exams(5+) 被跨模块直接访问 |
|
||||
| 9 | actions 层混入数据访问 | exams/homework/questions/announcements 的 actions.ts 直接 db.insert/update/delete |
|
||||
| 10 | auth.ts 混合 5 类职责 | NextAuth 配置 + 密码安全 DB + 角色规范化 + IP 解析 + 回调函数 |
|
||||
| 11 | users/import-export.ts 四重职责 | 导入解析 + 导出 + 用户创建 + 班级注册（跨模块写） |
|
||||
| 12 | proctoring 死代码 | exam-mode-config.tsx 未集成到考试表单 |
|
||||
| 13 | messaging 与 notifications 边界模糊 | 双向依赖，类型系统不一致 |
|
||||
| 14 | proctoring 事件双通道重复 | Server Action 与 REST API 同一逻辑两份代码 |
|
||||
| 15 | proxy.ts 硬编码权限字符串 | 未复用 Permissions 常量，违反项目规则 |
|
||||
|
||||
### 4.3 架构文档问题
|
||||
|
||||
当前 004 架构影响地图存在的问题：
|
||||
1. 按模块罗列函数签名，缺乏全局视角
|
||||
2. 缺少模块依赖关系图
|
||||
3. 缺少数据流向图
|
||||
4. 缺少调用链路
|
||||
5. 缺少分层架构说明
|
||||
6. 未标注循环依赖
|
||||
|
||||
### 4.4 解耦优先级
|
||||
|
||||
**立即执行（P0）：**
|
||||
1. 拆分 `classes/data-access.ts`（2104 行 → 按职责拆 3-4 个文件）
|
||||
2. 拆分 `homework/data-access.ts`（1038 行 → 分离排名逻辑）
|
||||
3. 修复 shared/lib ↔ auth 循环依赖
|
||||
4. dashboard 改为通过各模块 data-access 获取数据
|
||||
5. messaging 写通知改为通过 notifications dispatcher
|
||||
|
||||
**短期执行（P1）：**
|
||||
6. 统一 classSchedule 写入口到 scheduling 模块
|
||||
7. actions 层移除直接 DB 操作
|
||||
8. 拆分 auth.ts
|
||||
9. 集成 proctoring/exam-mode-config 到考试表单
|
||||
10. 拆分 users/import-export.ts
|
||||
|
||||
---
|
||||
|
||||
## 五、优先补齐路线图
|
||||
|
||||
### Phase 1: P0 缺口补齐（MVP 必须项）
|
||||
|
||||
> v3 进度：8 项中 6 项已完成，剩余 2 项
|
||||
|
||||
| 序号 | 功能 | 所属模块 | v2 状态 | v3 状态 | 工作量 |
|
||||
|------|------|---------|---------|---------|--------|
|
||||
| 1 | **通知公告系统** | 家校沟通 | ❌ | ✅ 已实现 | — |
|
||||
| 2 | **操作日志 + 登录日志** | 日志审计 | ❌ | ✅ 已实现 | — |
|
||||
| 3 | **成绩录入 + 查询 + 统计报表** | 成绩分析 | ❌ | ✅ 已实现 | — |
|
||||
| 4 | **文件上传 + 权限控制** | 文件管理 | ❌ | ✅ 已实现 | — |
|
||||
| 5 | **课程计划管理** | 教务排课 | ❌ | ✅ 已实现 | — |
|
||||
| 6 | **隐私政策 + 用户同意** | 隐私合规 | ❌ | ❌ 未实现 | 小 |
|
||||
| 7 | **未成年人信息保护** | 隐私合规 | ❌ | ❌ 未实现 | 小 |
|
||||
| 8 | **修复 13 个幽灵导航路由** | 布局 | ❌ | ✅ 已修复 | — |
|
||||
|
||||
### Phase 2: P1 关键增强（上线前推荐）
|
||||
|
||||
> v3 进度：20 项中约 11 项已完成
|
||||
|
||||
| 序号 | 功能 | 所属模块 | v2 状态 | v3 状态 |
|
||||
|------|------|---------|---------|---------|
|
||||
| 1 | 站内消息系统 | 家校沟通 | ❌ | ✅ 已实现 |
|
||||
| 2 | 家长端仪表盘 | 家校沟通 | ⚠️ | ⚠️ 仍需完善 |
|
||||
| 3 | Excel 批量导入 | 导入导出 | ❌ | ✅ 已实现 |
|
||||
| 4 | Excel/PDF 导出 | 导入导出 | ❌ | ✅ 已实现 |
|
||||
| 5 | 排课规则 + 自动排课 | 教务排课 | ❌ | ✅ 已实现 |
|
||||
| 6 | 课表调整/代课 | 教务排课 | ❌ | ❌ 未实现 |
|
||||
| 7 | 速率限制 | 操作安全 | ❌ | ❌ 未实现 |
|
||||
| 8 | 成绩趋势 + 对比分析 | 成绩分析 | ⚠️ | ⚠️ 趋势已有，对比未实现 |
|
||||
| 9 | 成绩导出 | 成绩分析 | ❌ | ✅ 已实现 |
|
||||
| 10 | 学生考勤 | 考勤管理 | ❌ | ✅ 已实现 |
|
||||
| 11 | 用户批量导入 | 用户与权限 | ❌ | ✅ 已实现 |
|
||||
| 12 | 密码安全策略 | 用户与权限 | ⚠️ | ⚠️ 仍需完善 |
|
||||
| 13 | 数据变更日志 | 日志审计 | ❌ | ✅ 已实现 |
|
||||
| 14 | 日志查询/导出 | 日志审计 | ❌ | ⚠️ 查询已有，导出未实现 |
|
||||
| 15 | 文件预览 + 存储策略 | 文件管理 | ❌ | ⚠️ 存储策略部分实现 |
|
||||
| 16 | 全文检索 | 全局搜索 | ❌ | ⚠️ 基础实现 |
|
||||
| 17 | 依赖审计集成 CI | 安全审计 | ⚠️ | ⚠️ 仍未集成 CI |
|
||||
| 18 | 数据库定时备份 | 数据备份 | ❌ | ✅ 已实现 |
|
||||
| 19 | E2E 测试完善 | 自动化测试 | ⚠️ | ⚠️ 仍需完善 |
|
||||
| 20 | 通知偏好管理 | 消息通知 | ❌ | ✅ 已实现 |
|
||||
|
||||
### Phase 3: P2 迭代优化（竞争力提升）
|
||||
|
||||
> v3 进度：14 项中 8 项已完成（57%）
|
||||
|
||||
| 序号 | 功能 | 所属模块 | v2 状态 | v3 状态 |
|
||||
|------|------|---------|---------|---------|
|
||||
| 1 | 国际化(i18n) | 非功能性 | ❌ | ❌ 未实现 |
|
||||
| 2 | 多租户/多校区 | 非功能性 | ❌ | ❌ 未实现 |
|
||||
| 3 | 主题色定制 | 深色主题 | ❌ | ❌ 未实现 |
|
||||
| 4 | 屏幕阅读器兼容 | 无障碍 | ❌ | ✅ 已实现 |
|
||||
| 5 | 视觉回归测试 | 自动化测试 | ❌ | ✅ 已实现 |
|
||||
| 6 | AI 批改辅助 | AI 赋能 | ❌ | ❌ 未实现 |
|
||||
| 7 | AI 学情分析 | AI 赋能 | ❌ | ❌ 未实现 |
|
||||
| 8 | AI 备课助手 | AI 赋能 | ❌ | ❌ 未实现 |
|
||||
| 9 | 选课管理 | 教务排课 | ❌ | ✅ 已实现 |
|
||||
| 10 | 考试监考 | 作业与考试 | ❌ | ✅ 已实现 |
|
||||
| 11 | 学情诊断报告 | 成绩分析 | ❌ | ✅ 已实现 |
|
||||
| 12 | 短信/微信推送 | 消息通知 | ❌ | ✅ 已实现 |
|
||||
| 13 | 漏洞扫描 + 渗透测试 | 安全审计 | ❌ | ⚠️ 漏洞扫描已实现，渗透测试未实现 |
|
||||
| 14 | 灾备方案 | 数据备份 | ❌ | ✅ 已实现 |
|
||||
|
||||
---
|
||||
|
||||
## 六、差距统计摘要
|
||||
|
||||
| 状态 | P0 | P1 | P2 | 合计 |
|
||||
|------|-----|-----|-----|------|
|
||||
| ✅ 已完成 | 38 | 12 | 2 | **52** |
|
||||
| ⚠️ 部分完成 | 10 | 8 | 1 | **19** |
|
||||
| ❌ 未实现 | 7 | 28 | 27 | **62** |
|
||||
| **合计** | **55** | **48** | **30** | **133** |
|
||||
| ✅ 已完成 | 46 | 31 | 12 | **89** |
|
||||
| ⚠️ 部分完成 | 7 | 11 | 6 | **24** |
|
||||
| ❌ 未实现 | 2 | 11 | 17 | **30** |
|
||||
| **合计** | **55** | **53** | **35** | **143** |
|
||||
|
||||
| 完成率 | P0 | P1 | P2 | 总体 |
|
||||
|--------|-----|-----|-----|------|
|
||||
| 按已完成计 | 69% | 25% | 7% | **39%** |
|
||||
| 含部分完成 | 87% | 42% | 10% | **53%** |
|
||||
| 按已完成计 | 84% | 58% | 34% | **62%** |
|
||||
| 含部分完成 | 96% | 79% | 51% | **79%** |
|
||||
|
||||
### v1 → v2 改善
|
||||
### v2 → v3 改善
|
||||
|
||||
| 指标 | v1 | v2 | 变化 |
|
||||
| 指标 | v2 | v3 | 变化 |
|
||||
|------|-----|-----|------|
|
||||
| P0 完成率（严格） | 65% | 69% | +4% |
|
||||
| P0 完成率（含部分） | 83% | 87% | +4% |
|
||||
| 安全漏洞数 | 15 个 Server Action 无权限 | 0 | **全部修复** |
|
||||
| 架构图覆盖率 | ~40% | 100% | **全量补全** |
|
||||
| 幽灵路由 | 未发现 | 13 个 | **新发现** |
|
||||
| P0 完成率（严格） | 69% | 84% | **+15%** |
|
||||
| P0 完成率（含部分） | 87% | 96% | **+9%** |
|
||||
| P1 完成率（严格） | 25% | 58% | **+33%** |
|
||||
| P2 完成率（严格） | 7% | 34% | **+27%** |
|
||||
| P2 路线图完成率 | 0% | 57% (8/14) | **+57%** |
|
||||
| 总体完成率（严格） | 39% | 62% | **+23%** |
|
||||
| 总体完成率（含部分） | 53% | 79% | **+26%** |
|
||||
| 幽灵路由 | 13 个 | 0 | **全部修复** |
|
||||
| 架构技术债 | 未审查 | 7 P0 + 8 P1 | **新发现** |
|
||||
|
||||
> **结论**：项目 P0 核心功能完成度约 69%（严格）/ 87%（含部分），较 v1 提升 4%。安全漏洞全部修复。架构图已全量补全。主要缺口集中在**通知公告**、**日志审计**、**成绩分析**三个 P0 模块。建议优先补齐 Phase 1 的 8 项 P0 缺口。
|
||||
> **结论**：项目 P0 核心功能完成度达 84%（严格）/ 96%（含部分），较 v2 大幅提升 15%。P2 路线图完成 8/14（57%）。主要剩余缺口：
|
||||
> 1. **隐私合规 P0**：隐私政策、未成年人信息保护（2 项）
|
||||
> 2. **P2 路线图**：AI 批改/学情/备课、国际化、多租户、主题色定制（6 项）
|
||||
> 3. **架构技术债**：7 项 P0 严重问题需修复（classes/data-access 超标、循环依赖、跨模块直查等）
|
||||
>
|
||||
> 建议优先：① 补齐 2 项 P0 隐私合规缺口；② 修复 7 项 P0 架构技术债；③ 推进 P2 路线图剩余 6 项。
|
||||
|
||||
132
docs/architecture/audit/00_summary.md
Normal file
132
docs/architecture/audit/00_summary.md
Normal file
@@ -0,0 +1,132 @@
|
||||
# 架构审查汇总报告
|
||||
|
||||
> 基于对全项目 69+ 文件的逐文件审查,汇总关键架构问题。
|
||||
> 审查日期: 2026-06-17
|
||||
> 子报告:
|
||||
> - [shared 基础设施层审查](./shared-audit.md)
|
||||
> - [核心业务模块审查](./core-business-audit.md)
|
||||
> - [管理模块群审查](./management-modules-audit.md)
|
||||
> - [新增模块和其他模块审查](./new-and-other-modules-audit.md)
|
||||
|
||||
---
|
||||
|
||||
## 一、总体评估
|
||||
|
||||
| 维度 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 模块化程度 | ⚠️ 中等 | 20+ 模块划分合理,但跨模块直接 DB 查询普遍存在 |
|
||||
| 职责单一性 | ⚠️ 中等 | 多数模块职责清晰,但 5 个文件超 1000 行硬上限 |
|
||||
| 架构文档质量 | ❌ 不足 | 004 文档按模块罗列函数,缺乏关系图/数据流/调用链 |
|
||||
| 循环依赖 | ❌ 存在 | shared/lib ↔ auth 循环依赖 |
|
||||
| 死代码 | ⚠️ 少量 | proctoring/exam-mode-config.tsx 未集成 |
|
||||
|
||||
**核心结论**: 架构设计思路正确(模块化 + 分层),但执行不够严格。主要问题是跨模块直接 DB 查询破坏了模块封装,以及少数文件过大。
|
||||
|
||||
---
|
||||
|
||||
## 二、P0 严重问题(必须修复)
|
||||
|
||||
### 1. 文件超 1000 行硬上限(3 个文件)
|
||||
|
||||
| 文件 | 行数 | 问题 |
|
||||
|------|------|------|
|
||||
| `classes/data-access.ts` | 2104 | 混入 homework/scheduling/grades 逻辑 |
|
||||
| `homework/data-access.ts` | 1038 | 混入排名计算业务逻辑 |
|
||||
| `shared/db/schema.ts` | 1111 | 54 张表混合(可接受,但需分节) |
|
||||
|
||||
### 2. 循环依赖
|
||||
|
||||
```
|
||||
shared/lib/{audit-logger, change-logger, auth-guard}
|
||||
→ @/auth (src/auth.ts)
|
||||
→ shared/lib/* (循环)
|
||||
```
|
||||
|
||||
### 3. dashboard 跨模块直接查询 11 张表
|
||||
|
||||
`dashboard/data-access.ts` 的 `getAdminDashboardData` 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装。
|
||||
|
||||
### 4. messaging 绕过 notifications 直接写通知
|
||||
|
||||
`messaging/actions.ts` 第 66-72 行直接调用 `createNotification`,导致用户通知偏好失效、多渠道通知无效。
|
||||
|
||||
### 5. classSchedule 表三处写入口
|
||||
|
||||
- `classes/data-access.ts`
|
||||
- `scheduling/actions.ts` (直接 transaction 写入)
|
||||
- `scheduling/data-access.ts`
|
||||
|
||||
数据完整性高风险。
|
||||
|
||||
---
|
||||
|
||||
## 三、P1 较严重问题
|
||||
|
||||
### 6. 跨模块直接 DB 查询普遍存在
|
||||
|
||||
| 被访问表 | 访问次数 | 应归属模块 | 主要违规者 |
|
||||
|---------|---------|-----------|-----------|
|
||||
| `classes` | 8+ | classes | exams, homework, grades, dashboard |
|
||||
| `classEnrollments` | 6+ | classes | homework, grades, attendance |
|
||||
| `users` | 6+ | users | 多个模块 |
|
||||
| `subjects` | 6+ | school | exams, homework, questions |
|
||||
| `exams` | 5+ | exams | homework, grades, dashboard |
|
||||
|
||||
### 7. actions 层混入数据访问逻辑
|
||||
|
||||
exams/homework/questions/announcements 的 actions.ts 中存在直接 `db.insert/update/delete`,应该通过 data-access 层。
|
||||
|
||||
### 8. auth.ts 混合 5 类职责
|
||||
|
||||
NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数,应拆分。
|
||||
|
||||
### 9. users/import-export.ts 四重职责
|
||||
|
||||
导入解析 + 导出 + 用户创建(含密码哈希) + 班级注册(跨模块写 classEnrollments)。
|
||||
|
||||
### 10. proctoring 死代码
|
||||
|
||||
`exam-mode-config.tsx` 组件已创建但未集成到考试表单,DB schema 有 examMode 字段但表单不收集。
|
||||
|
||||
---
|
||||
|
||||
## 四、架构文档问题
|
||||
|
||||
### 当前 004 文档的问题
|
||||
|
||||
1. **按模块罗列函数签名**,缺乏全局视角
|
||||
2. **缺少模块依赖关系图**,无法直观看出模块间如何协作
|
||||
3. **缺少数据流向图**,不知道数据如何在模块间流动
|
||||
4. **缺少调用链路**,不知道一个请求从 API 到 DB 的完整路径
|
||||
5. **缺少分层架构说明**,不知道 shared/modules/app 的层次关系
|
||||
6. **未标注循环依赖**,给人虚假的"架构清晰"印象
|
||||
|
||||
### 理想的架构文档应该
|
||||
|
||||
1. **一图胜千言**: 用 ASCII/Mermaid 图展示模块关系
|
||||
2. **分层清晰**: shared → modules → app 三层,依赖方向单向
|
||||
3. **数据流明确**: 标注每个核心业务的数据从哪来、到哪去
|
||||
4. **调用链完整**: 关键 API 的完整调用路径
|
||||
5. **问题标注**: 明确标注已知的耦合问题和技术债
|
||||
|
||||
---
|
||||
|
||||
## 五、解耦优先级
|
||||
|
||||
### 立即执行(P0)
|
||||
1. 拆分 `classes/data-access.ts`(2104 行 → 按职责拆 3-4 个文件)
|
||||
2. 拆分 `homework/data-access.ts`(1038 行 → 分离排名逻辑)
|
||||
3. 修复 shared/lib ↔ auth 循环依赖
|
||||
4. dashboard 改为通过各模块 data-access 获取数据
|
||||
5. messaging 写通知改为通过 notifications dispatcher
|
||||
|
||||
### 短期执行(P1)
|
||||
6. 统一 classSchedule 写入口到 scheduling 模块
|
||||
7. actions 层移除直接 DB 操作
|
||||
8. 拆分 auth.ts
|
||||
9. 集成 proctoring/exam-mode-config 到考试表单
|
||||
10. 拆分 users/import-export.ts
|
||||
|
||||
### 中期执行(P2)
|
||||
11. 建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
|
||||
12. schema.ts 按业务域分节(加注释分隔)
|
||||
417
docs/architecture/audit/core-business-audit.md
Normal file
417
docs/architecture/audit/core-business-audit.md
Normal file
@@ -0,0 +1,417 @@
|
||||
# 核心业务模块职责与耦合审查报告
|
||||
|
||||
> 审计日期：2026-06-17
|
||||
> 审计范围：`src/modules/exams`、`src/modules/homework`、`src/modules/questions`、`src/modules/textbooks`、`src/modules/grades`
|
||||
> 审计目标：识别职责不单一和过耦合问题，重点关注跨模块直接数据库查询（违反模块封装）
|
||||
> 审计依据：项目规则（`.trae/rules/project_rules.md`）、架构影响地图（004/005）
|
||||
|
||||
---
|
||||
|
||||
## 一、总体结论
|
||||
|
||||
| 维度 | 状态 | 说明 |
|
||||
|------|------|------|
|
||||
| 模块职责边界 | ⚠️ 部分违规 | homework 混入考试/班级逻辑；grades 混入班级/用户逻辑 |
|
||||
| data-access 层职责 | ❌ 普遍违规 | 5 个模块均存在跨模块直接 DB 查询；homework/data-access.ts 混入排名业务逻辑 |
|
||||
| actions 层职责 | ⚠️ 部分违规 | exams/homework/questions 的 actions 直接访问 DB；textbooks/grades 的 actions 设计良好 |
|
||||
| 组件耦合 | ✅ 基本合规 | 组件层跨模块依赖均为类型导入或 UI 组合，无直接 data-access 调用 |
|
||||
| 跨模块依赖 | ⚠️ 存在风险 | 无循环依赖，但 exams→questions、homework→exams、grades→classes 的直接 DB 访问破坏封装 |
|
||||
| 文件行数 | ❌ 存在违规 | homework/data-access.ts 1038 行（超 1000 硬上限）；exams/ai-pipeline.ts 912 行、exams/actions.ts 832 行（超 800 建议值） |
|
||||
|
||||
### 关键风险项
|
||||
|
||||
1. **homework/data-access.ts 超过 1000 行硬上限**（1038 行）—— 必须拆分
|
||||
2. **5 个模块均存在跨模块直接 DB 查询** —— 违反模块封装原则
|
||||
3. **exams/homework/questions 的 actions 层混入数据访问逻辑** —— 应只做编排
|
||||
4. **homework/data-access.ts 混入排名计算业务逻辑** —— data-access 应只负责数据存取
|
||||
|
||||
---
|
||||
|
||||
## 二、模块依赖关系图
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ textbooks │ ← 被引用方（知识点/章节）
|
||||
└──────┬───────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────┐ ┌──────────┐ ┌────────────┐
|
||||
│ questions │ │ exams │ │ homework │
|
||||
└─────┬──────┘ └────┬─────┘ └─────┬──────┘
|
||||
│ │ │
|
||||
│ ┌──────────┘ │
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌────────────────┐ ┌──────────┐
|
||||
│ grades │ │ classes │
|
||||
└────────────────┘ └──────────┘
|
||||
```
|
||||
|
||||
### 依赖关系明细
|
||||
|
||||
| 依赖方向 | 类型 | 合理性 | 问题 |
|
||||
|---------|------|--------|------|
|
||||
| exams → questions | data-access + 类型 + action | ⚠️ 部分合理 | 类型导入合理；但 `persistAiGeneratedExamDraft` 直接 insert 到 questions 表，应通过 questions/data-access |
|
||||
| exams → classes | data-access | ❌ 不合理 | `getExams`/`getExamById` 直接查询 classes 表获取教师 gradeIds，应通过 classes/data-access |
|
||||
| exams → school | actions | ❌ 不合理 | `getSubjectsAction`/`getGradesAction` 直接查询 subjects/grades 表，应通过 school/data-access |
|
||||
| homework → exams | data-access + 组件 | ⚠️ 部分合理 | 业务上 homework 引用 exam（sourceExamId）合理；但直接查询 exams 表应改为调用 exams/data-access |
|
||||
| homework → classes | data-access + actions | ❌ 不合理 | 直接查询 classes/classEnrollments/classSubjectTeachers 表，应通过 classes/data-access |
|
||||
| homework → questions | data-access | ✅ 合理 | 通过 Drizzle 关系查询 homeworkAssignmentQuestions.question，未直接访问 questions 表 |
|
||||
| grades → exams | 无 | ✅ 合理 | grades 仅通过 examId 外键引用，不直接查询 exams 表 |
|
||||
| grades → homework | 无 | ✅ 合理 | grades 仅通过 type 枚举值 "homework" 引用，不直接查询 homework 表 |
|
||||
| grades → classes | data-access | ❌ 不合理 | 多个 data-access 文件直接查询 classes/classEnrollments 表 |
|
||||
| grades → users/subjects | data-access | ❌ 不合理 | 直接查询 users/subjects 表获取关联名称，应通过对应模块 data-access |
|
||||
| questions → textbooks | actions | ❌ 不合理 | `getKnowledgePointOptionsAction` 直接查询 knowledgePoints/chapters/textbooks 表 |
|
||||
| textbooks → questions | 组件 | ✅ 合理 | `knowledge-point-dialogs.tsx` 导入 CreateQuestionDialog 组件，属于 UI 组合 |
|
||||
|
||||
### 循环依赖分析
|
||||
|
||||
- **无直接循环依赖**：模块间的 data-access 依赖是单向的
|
||||
- **潜在风险**：exams → questions（data-access）与 questions → textbooks（actions）与 textbooks → questions（组件）形成链式依赖，但因 textbooks→questions 仅为组件层导入，不构成 data-access 层的循环依赖
|
||||
|
||||
---
|
||||
|
||||
## 三、各模块审查明细
|
||||
|
||||
### 3.1 exams 模块
|
||||
|
||||
#### 文件行数
|
||||
|
||||
| 文件 | 行数 | 限制 | 状态 |
|
||||
|------|------|------|------|
|
||||
| actions.ts | 832 | ≤800 | ⚠️ 超限 |
|
||||
| ai-pipeline.ts | 912 | ≤800 | ⚠️ 超限 |
|
||||
| data-access.ts | 339 | ≤800 | ✅ |
|
||||
| types.ts | 31 | 无限制 | ✅ |
|
||||
| hooks/use-exam-preview.ts | 295 | ≤500 | ✅ |
|
||||
|
||||
#### 模块职责边界
|
||||
|
||||
- **职责**：考试全生命周期管理（创建/编辑/预览/发布/删除/复制）+ AI 辅助出题
|
||||
- **问题**：`getSubjectsAction`/`getGradesAction` 属于 school 模块职责，被放在 exams/actions.ts 中
|
||||
|
||||
#### data-access 层问题
|
||||
|
||||
| 函数 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `getExams` | 直接查询 `classes` 表获取教师 gradeIds（第 71-78 行） | 高 |
|
||||
| `getExamById` | 直接查询 `classes` 表获取教师 gradeIds（第 155-159 行） | 高 |
|
||||
| `persistAiGeneratedExamDraft` | 直接 insert 到 `questions` 表（第 317-326 行） | 高 |
|
||||
|
||||
#### actions 层问题
|
||||
|
||||
| 函数 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `updateExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete`/`db.insert`/`db.update` 操作 examQuestions | 高 |
|
||||
| `deleteExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete` | 高 |
|
||||
| `duplicateExamAction` | 直接 `db.query.exams.findFirst` + `db.transaction` 内联 insert exams/examQuestions | 高 |
|
||||
| `getExamPreviewAction` | 直接 `db.query.exams.findFirst` 查询考试预览数据 | 高 |
|
||||
| `getSubjectsAction` | 直接查询 `subjects` 表 —— 跨模块 DB 访问 | 高 |
|
||||
| `getGradesAction` | 直接查询 `grades` 表 —— 跨模块 DB 访问 | 高 |
|
||||
|
||||
#### 组件耦合
|
||||
|
||||
| 组件 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `exam-assembly.tsx` | 调用 `getQuestionsAction`（questions 模块的 action） | 中 |
|
||||
| 8 个组件 | 导入 `Question` 类型自 questions/types | 低（类型导入合理） |
|
||||
| `ExamAssembly` | **10 个 props**（examId, title, subject, grade, difficulty, totalScore, durationMin, initialSelected, initialStructure, questionOptions） | 中 |
|
||||
| `ExamPreviewQuestionEditor` | **10 个 props** | 中 |
|
||||
|
||||
#### ai-pipeline.ts 问题
|
||||
|
||||
- 912 行，超过 800 行建议值
|
||||
- 混合了 Zod schema、AI prompt、JSON 解析修复、题目详情解析、并发控制等多种职责
|
||||
- 建议拆分为：`ai-schema.ts`（Zod schema）、`ai-prompts.ts`（prompt 常量）、`ai-parser.ts`（JSON 解析修复）、`ai-pipeline.ts`（核心生成逻辑）
|
||||
|
||||
---
|
||||
|
||||
### 3.2 homework 模块
|
||||
|
||||
#### 文件行数
|
||||
|
||||
| 文件 | 行数 | 限制 | 状态 |
|
||||
|------|------|------|------|
|
||||
| data-access.ts | **1038** | ≤1000 硬上限 | ❌ **必须拆分** |
|
||||
| actions.ts | 387 | ≤800 | ✅ |
|
||||
| schema.ts | 29 | 无限制 | ✅ |
|
||||
| types.ts | 186 | 无限制 | ✅ |
|
||||
|
||||
#### 模块职责边界
|
||||
|
||||
- **职责**：作业全生命周期（创建/发布/作答/批改/分析）
|
||||
- **问题**：`getStudentDashboardGrades` 包含班级排名计算逻辑（150+ 行），属于 dashboard 或 grades 模块职责
|
||||
|
||||
#### data-access 层问题（严重）
|
||||
|
||||
| 函数 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `getStudentDashboardGrades` | 150+ 行排名计算业务逻辑混入 data-access | 高 |
|
||||
| `getHomeworkAssignmentAnalytics` | 145+ 行错误率/错误答案统计业务逻辑混入 data-access | 高 |
|
||||
| `getHomeworkAssignments` | 直接查询 `exams` 表（第 167-171 行） | 高 |
|
||||
| `getHomeworkAssignmentReviewList` | 直接查询 `exams` 表（第 227-233 行） | 高 |
|
||||
| `getHomeworkSubmissions` | 直接查询 `exams` 表（第 349-359 行） | 高 |
|
||||
| `getHomeworkAssignmentById` | 直接查询 `exams` 表（第 403-407 行） | 高 |
|
||||
| `getStudentHomeworkAssignments` | 直接 join `exams`/`subjects` 表（第 730-731 行） | 高 |
|
||||
| `getDemoStudentUser` | 直接查询 `users`/`roles`/`usersToRoles` 表 + 使用 `auth()` 而非 auth-guard | 高 |
|
||||
| `getStudentDashboardGrades` | 直接查询 `classEnrollments`/`users` 表 | 高 |
|
||||
|
||||
#### actions 层问题
|
||||
|
||||
| 函数 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `createHomeworkAssignmentAction` | **157 行**，混合数据访问 + 业务逻辑 + 权限校验 | 高 |
|
||||
| 同上 | 直接查询 `classes`/`classSubjectTeachers`/`exams`/`classEnrollments` 表 | 高 |
|
||||
| 同上 | 内联 `db.transaction` insert homeworkAssignments/homeworkAssignmentQuestions/homeworkAssignmentTargets | 高 |
|
||||
| `startHomeworkSubmissionAction` | 直接 `db.query` + `db.insert` | 高 |
|
||||
| `saveHomeworkAnswerAction` | 直接 `db.query` + `db.transaction` | 高 |
|
||||
| `submitHomeworkAction` | 直接 `db.query` + `db.update` | 高 |
|
||||
| `gradeHomeworkSubmissionAction` | 直接 `db.update` 循环更新 homeworkAnswers | 高 |
|
||||
|
||||
#### 拆分建议
|
||||
|
||||
`data-access.ts`（1038 行）建议拆分为：
|
||||
- `data-access.ts`：基础 CRUD（getHomeworkAssignments, getHomeworkAssignmentById, getHomeworkSubmissions）
|
||||
- `data-access-student.ts`：学生视角查询（getStudentHomeworkAssignments, getStudentHomeworkTakeData, getStudentDashboardGrades）
|
||||
- `data-access-analytics.ts`：分析统计（getHomeworkAssignmentAnalytics, getTeacherGradeTrends）
|
||||
- `data-access-grading.ts`：批改相关（getHomeworkSubmissionDetails, getHomeworkAssignmentReviewList）
|
||||
|
||||
---
|
||||
|
||||
### 3.3 questions 模块
|
||||
|
||||
#### 文件行数
|
||||
|
||||
| 文件 | 行数 | 限制 | 状态 |
|
||||
|------|------|------|------|
|
||||
| actions.ts | 294 | ≤800 | ✅ |
|
||||
| data-access.ts | 129 | ≤800 | ✅ |
|
||||
| schema.ts | 18 | 无限制 | ✅ |
|
||||
| types.ts | 34 | 无限制 | ✅ |
|
||||
|
||||
#### 模块职责边界
|
||||
|
||||
- **职责**：题库管理（题目 CRUD、知识点关联、题型支持）
|
||||
- **问题**：`getKnowledgePointOptionsAction` 查询 textbooks 模块的表，属于 textbooks 模块职责
|
||||
|
||||
#### data-access 层问题
|
||||
|
||||
- ✅ 仅访问 `questions` 和 `questionsToKnowledgePoints` 表，无跨模块 DB 访问
|
||||
- ❌ **缺失写操作函数**：`insertQuestionWithRelations`、`deleteQuestionRecursive` 等 data-access 函数被错误地放在 actions.ts 中
|
||||
|
||||
#### actions 层问题
|
||||
|
||||
| 函数 | 问题 | 严重程度 |
|
||||
|------|------|---------|
|
||||
| `createNestedQuestion` | 内联 `db.transaction` + 调用 `insertQuestionWithRelations`（data-access 函数错放在 actions） | 高 |
|
||||
| `updateQuestionAction` | 内联 `db.transaction` 做 update/delete/insert | 高 |
|
||||
| `deleteQuestionAction` | 内联 `db.transaction` + 调用 `deleteQuestionRecursive`（data-access 函数错放在 actions） | 高 |
|
||||
| `getKnowledgePointOptionsAction` | 直接查询 `knowledgePoints`/`chapters`/`textbooks` 表 —— 跨模块 DB 访问 | 高 |
|
||||
| `getQuestionsAction` | ✅ 正确委托给 data-access.getQuestions | ✅ |
|
||||
|
||||
#### 组件耦合
|
||||
|
||||
- ✅ 无跨模块依赖
|
||||
|
||||
---
|
||||
|
||||
### 3.4 textbooks 模块（标杆模块）
|
||||
|
||||
#### 文件行数
|
||||
|
||||
| 文件 | 行数 | 限制 | 状态 |
|
||||
|------|------|------|------|
|
||||
| actions.ts | 276 | ≤800 | ✅ |
|
||||
| data-access.ts | 428 | ≤800 | ✅ |
|
||||
| types.ts | 79 | 无限制 | ✅ |
|
||||
| hooks/use-knowledge-point-actions.ts | 121 | ≤500 | ✅ |
|
||||
| hooks/use-text-selection.ts | - | ≤500 | ✅ |
|
||||
|
||||
#### 模块职责边界
|
||||
|
||||
- **职责**：教材与知识体系管理（教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱）
|
||||
- ✅ 职责单一，无越界
|
||||
|
||||
#### data-access 层评价
|
||||
|
||||
- ✅ 仅访问 `textbooks`、`chapters`、`knowledgePoints` 表
|
||||
- ✅ 无跨模块 DB 访问
|
||||
- ✅ 无业务逻辑混入
|
||||
|
||||
#### actions 层评价
|
||||
|
||||
- ✅ **标杆实现**：所有 action 均遵循"权限校验 → 调用 data-access → revalidatePath → 返回"模式
|
||||
- ✅ 无直接 DB 访问
|
||||
- ✅ 无业务逻辑混入
|
||||
|
||||
#### 组件耦合
|
||||
|
||||
- `knowledge-point-dialogs.tsx` 导入 `CreateQuestionDialog` 自 questions 模块 —— ✅ 合理的 UI 组合
|
||||
|
||||
#### hooks 评价
|
||||
|
||||
- `useKnowledgePointActions` 有 7 个参数（textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated）—— ✅ 在 8 个限制内
|
||||
|
||||
---
|
||||
|
||||
### 3.5 grades 模块
|
||||
|
||||
#### 文件行数
|
||||
|
||||
| 文件 | 行数 | 限制 | 状态 |
|
||||
|------|------|------|------|
|
||||
| actions.ts | 312 | ≤800 | ✅ |
|
||||
| actions-analytics.ts | 133 | ≤800 | ✅ |
|
||||
| data-access.ts | 419 | ≤800 | ✅ |
|
||||
| data-access-analytics.ts | 293 | ≤800 | ✅ |
|
||||
| data-access-ranking.ts | 121 | ≤800 | ✅ |
|
||||
| export.ts | 214 | ≤800 | ✅ |
|
||||
| schema.ts | 52 | 无限制 | ✅ |
|
||||
| types.ts | - | 无限制 | ✅ |
|
||||
|
||||
#### 模块职责边界
|
||||
|
||||
- **职责**：成绩分析（录入/查询/统计/导出/趋势对比分析）
|
||||
- ✅ 职责单一，未混入考试/作业逻辑
|
||||
- ✅ 通过 `examId` 外键引用考试，通过 `type` 枚举引用作业类型，未直接依赖 exams/homework 模块的 data-access
|
||||
|
||||
#### data-access 层问题
|
||||
|
||||
| 文件 | 函数 | 问题 | 严重程度 |
|
||||
|------|------|------|---------|
|
||||
| data-access.ts | `getGradeRecords` | 直接 join `classes`/`subjects`/`users` 表 | 高 |
|
||||
| data-access.ts | `getStudentGradeSummary` | 直接 join `classes`/`subjects`/`users` 表 | 高 |
|
||||
| data-access.ts | `getClassRanking` | 直接 join `users` 表 | 高 |
|
||||
| data-access.ts | `getClassStudentsForEntry` | 直接查询 `classEnrollments`/`users` 表 —— 应在 classes 模块 | 高 |
|
||||
| data-access.ts | `getClassGradeStatsWithMeta` | 直接查询 `classes`/`classEnrollments` 表 | 高 |
|
||||
| data-access.ts | `getClassGradeStats` | 统计计算业务逻辑（average/median/stdDev/passRate/excellentRate）混入 data-access | 中 |
|
||||
| data-access-analytics.ts | `getGradeTrend` | 直接 join `classes`/`subjects` 表 | 高 |
|
||||
| data-access-analytics.ts | `getClassComparison` | 直接查询 `classes` 表 + 统计计算业务逻辑 | 高 |
|
||||
| data-access-analytics.ts | `getSubjectComparison` | 直接 join `subjects` 表 + 统计计算业务逻辑 | 高 |
|
||||
| data-access-analytics.ts | `getGradeDistribution` | 分桶统计业务逻辑混入 data-access | 中 |
|
||||
| data-access-ranking.ts | `getRankingTrend` | 直接查询 `classEnrollments`/`users` 表 + 排名计算业务逻辑 | 高 |
|
||||
| export.ts | `exportClassGradeReportToExcel` | 直接查询 `classes`/`subjects`/`users` 表 + 排名计算业务逻辑 | 高 |
|
||||
|
||||
#### actions 层评价
|
||||
|
||||
- ✅ **标杆实现**：`actions.ts` 和 `actions-analytics.ts` 均遵循"权限校验 → 调用 data-access → 返回"模式
|
||||
- ✅ 无直接 DB 访问
|
||||
- ✅ 无业务逻辑混入
|
||||
|
||||
#### 组件耦合
|
||||
|
||||
- ✅ 无跨模块依赖
|
||||
|
||||
---
|
||||
|
||||
## 四、跨模块直接 DB 访问汇总
|
||||
|
||||
> 以下为违反模块封装原则的直接数据库查询，应改为通过对方模块的 data-access 函数调用。
|
||||
|
||||
### 4.1 按来源模块分类
|
||||
|
||||
| 来源模块 | 文件 | 被访问的表 | 应调用的模块 |
|
||||
|---------|------|-----------|-------------|
|
||||
| exams | data-access.ts | `classes` | classes/data-access |
|
||||
| exams | data-access.ts | `questions`（insert） | questions/data-access |
|
||||
| exams | actions.ts | `subjects`, `grades` | school/data-access |
|
||||
| homework | actions.ts | `classes`, `classSubjectTeachers`, `exams`, `classEnrollments` | classes/data-access, exams/data-access |
|
||||
| homework | data-access.ts | `exams`, `classEnrollments`, `subjects`, `users`, `roles`, `usersToRoles` | exams/data-access, classes/data-access, school/data-access |
|
||||
| questions | actions.ts | `knowledgePoints`, `chapters`, `textbooks` | textbooks/data-access |
|
||||
| grades | data-access.ts | `classes`, `classEnrollments`, `subjects`, `users` | classes/data-access, school/data-access |
|
||||
| grades | data-access-analytics.ts | `classes`, `subjects` | classes/data-access, school/data-access |
|
||||
| grades | data-access-ranking.ts | `classEnrollments`, `users` | classes/data-access |
|
||||
| grades | export.ts | `classes`, `subjects`, `users` | classes/data-access, school/data-access |
|
||||
|
||||
### 4.2 按被访问表分类（频次）
|
||||
|
||||
| 被访问表 | 访问次数 | 应归属模块 |
|
||||
|---------|---------|-----------|
|
||||
| `classes` | 8+ | classes |
|
||||
| `classEnrollments` | 6+ | classes |
|
||||
| `users` | 6+ | users |
|
||||
| `subjects` | 6+ | school |
|
||||
| `exams` | 5+ | exams |
|
||||
| `grades`（年级表） | 1 | school |
|
||||
| `classSubjectTeachers` | 1 | classes |
|
||||
| `knowledgePoints` | 1 | textbooks |
|
||||
| `chapters` | 1 | textbooks |
|
||||
| `textbooks` | 1 | textbooks |
|
||||
| `roles`, `usersToRoles` | 1 | users |
|
||||
| `questions`（insert） | 1 | questions |
|
||||
|
||||
---
|
||||
|
||||
## 五、改进建议
|
||||
|
||||
### 5.1 高优先级（P0）
|
||||
|
||||
1. **拆分 homework/data-access.ts**（1038 行 → 4 个文件）
|
||||
- 按职责拆分为 data-access.ts / data-access-student.ts / data-access-analytics.ts / data-access-grading.ts
|
||||
|
||||
2. **消除跨模块直接 DB 访问**
|
||||
- 在 classes/data-access 暴露 `getClassGradeIdsByClassIds`、`getClassStudentsByClassId`、`getActiveClassStudents` 等函数
|
||||
- 在 exams/data-access 暴露 `getExamForHomeworkCreation`（含 questions 关联）
|
||||
- 在 school/data-access 暴露 `getSubjectOptions`、`getGradeOptions`
|
||||
- 在 users/data-access 暴露 `getUserNameByIds`、`getStudentInfo`
|
||||
- 在 textbooks/data-access 暴露 `getKnowledgePointOptions`
|
||||
- 在 questions/data-access 暴露 `insertQuestionWithRelations`、`deleteQuestionRecursive`
|
||||
|
||||
3. **将 exams/actions.ts 中的 DB 操作下沉到 data-access**
|
||||
- `updateExamAction`、`deleteExamAction`、`duplicateExamAction`、`getExamPreviewAction` 的 DB 操作移至 data-access
|
||||
- 将 `getSubjectsAction`/`getGradesAction` 移至 school 模块或改为调用 school/data-access
|
||||
|
||||
4. **将 homework/actions.ts 中的 DB 操作下沉到 data-access**
|
||||
- `createHomeworkAssignmentAction`（157 行）拆分为：data-access 函数 + action 编排
|
||||
- 其他 action 的 DB 操作全部移至 data-access
|
||||
|
||||
5. **将 questions/actions.ts 中的 DB 操作下沉到 data-access**
|
||||
- `insertQuestionWithRelations`、`deleteQuestionRecursive` 移至 data-access
|
||||
- `getKnowledgePointOptionsAction` 改为调用 textbooks/data-access
|
||||
|
||||
### 5.2 中优先级（P1）
|
||||
|
||||
6. **拆分 exams/ai-pipeline.ts**（912 行 → 4 个文件）
|
||||
- ai-schema.ts（Zod schema）、ai-prompts.ts（prompt 常量）、ai-parser.ts（JSON 解析修复）、ai-pipeline.ts（核心生成逻辑）
|
||||
|
||||
7. **将 homework/data-access.ts 中的业务逻辑提取到独立服务层**
|
||||
- `getStudentDashboardGrades` 的排名计算逻辑提取到 `services/ranking-service.ts`
|
||||
- `getHomeworkAssignmentAnalytics` 的错误率统计逻辑提取到 `services/analytics-service.ts`
|
||||
|
||||
8. **将 grades/data-access.ts 中的统计计算逻辑提取到独立服务层**
|
||||
- `getClassGradeStats` 的统计计算提取到 `services/stats-service.ts`
|
||||
- `getGradeDistribution` 的分桶逻辑提取到 `services/distribution-service.ts`
|
||||
|
||||
9. **减少组件 props 数量**
|
||||
- `ExamAssembly`（10 props）和 `ExamPreviewQuestionEditor`（10 props）应考虑使用 Context 或组合模式减少 props
|
||||
|
||||
### 5.3 低优先级（P2）
|
||||
|
||||
10. **统一 auth 调用方式**
|
||||
- `homework/data-access.ts` 的 `getDemoStudentUser` 使用 `auth()` 而非 `auth-guard.getAuthContext()`，应统一
|
||||
|
||||
11. **补全 questions/data-access.ts 的写操作**
|
||||
- 当前 data-access 仅有 `getQuestions`，所有写操作错放在 actions.ts
|
||||
|
||||
---
|
||||
|
||||
## 六、标杆模块推荐
|
||||
|
||||
| 模块 | 推荐参考点 |
|
||||
|------|-----------|
|
||||
| **textbooks** | actions 层编排模式（权限校验 → 调用 data-access → revalidatePath） |
|
||||
| **textbooks** | data-access 层职责单一（仅访问本模块表，无业务逻辑） |
|
||||
| **grades** | actions 层拆分（actions.ts + actions-analytics.ts 按职责分文件） |
|
||||
| **grades** | data-access 层拆分（data-access.ts + data-access-analytics.ts + data-access-ranking.ts） |
|
||||
| **grades** | 跨模块解耦（通过外键引用 exams/homework，不直接访问其表） |
|
||||
|
||||
---
|
||||
|
||||
## 七、审查方法说明
|
||||
|
||||
- **审查范围**：5 个核心业务模块的 actions/data-access/schema/types/components/hooks 全量文件
|
||||
- **审查工具**：源码全量阅读 + Grep 跨模块依赖扫描 + PowerShell 行数统计
|
||||
- **审查依据**：项目规则中"Server Action 必须使用 requirePermission()"、"单文件行数规范"、"模块职责单一"等规则
|
||||
- **未覆盖项**：未运行 lint/typecheck（本次为只读审查，不修改代码）；未审查组件内部实现细节（仅审查 props 数量和跨模块依赖）
|
||||
393
docs/architecture/audit/management-modules-audit.md
Normal file
393
docs/architecture/audit/management-modules-audit.md
Normal file
@@ -0,0 +1,393 @@
|
||||
# 管理类模块职责与耦合审查报告
|
||||
|
||||
> 审查范围：school / classes / scheduling / attendance / users / audit / course-plans / announcements
|
||||
> 审查日期：2026-06-17
|
||||
> 审查依据：单一职责原则（SRP）、模块边界清晰度、跨模块耦合度、企业级代码规范（单文件 ≤ 1000 行硬性上限）
|
||||
> 审查方式：只读源码分析，未修改任何代码
|
||||
|
||||
---
|
||||
|
||||
## 一、总体评价
|
||||
|
||||
| 模块 | 行数（最大文件） | 职责单一性 | 耦合度 | 严重度 |
|
||||
|------|----------------|-----------|--------|--------|
|
||||
| school | 325 | ✅ 良好 | ✅ 低 | 🟢 合格 |
|
||||
| classes | **2104** | ❌ 严重违反 | ❌ 严重 | 🔴 严重 |
|
||||
| scheduling | 310（算法）/ 302（actions） | ✅ 算法独立 | ⚠️ 中 | 🟡 需改进 |
|
||||
| attendance | 271 | ✅ 良好 | ⚠️ 中 | 🟢 合格 |
|
||||
| users | 291（import-export） | ❌ 违反 | ❌ 高 | 🟠 较严重 |
|
||||
| audit | 212 | ⚠️ 部分违反 | ✅ 低 | 🟡 需改进 |
|
||||
| course-plans | 320 | ✅ 良好 | ✅ 低 | 🟢 合格 |
|
||||
| announcements | 242 | ⚠️ 部分违反 | ✅ 低 | 🟡 需改进 |
|
||||
|
||||
**核心结论**：
|
||||
1. `classes` 模块是全项目耦合最严重的模块，单文件 2104 行远超 1000 行硬性上限，混入了 schedule、homework、grades 三个业务领域的逻辑。
|
||||
2. `users/import-export.ts` 违反单一职责，同时处理导入、导出、用户创建、班级注册四类逻辑。
|
||||
3. `scheduling/auto-scheduler.ts` 是算法独立化的**优秀范例**，纯函数、无 DB 访问、可独立测试。
|
||||
4. `announcements` 和 `audit` 模块的 data-access 层不完整，写操作或导出逻辑泄漏到 actions 层。
|
||||
|
||||
---
|
||||
|
||||
## 二、模块审查明细
|
||||
|
||||
### 2.1 school 模块 — 🟢 合格
|
||||
|
||||
**文件清单**：actions.ts (325 行) / data-access.ts (186 行) / schema.ts (51 行) / types.ts (42 行)
|
||||
|
||||
**职责边界**：✅ 清晰。仅负责 schools / academicYears / departments / grades 的 CRUD。
|
||||
|
||||
**优点**：
|
||||
- actions.ts 每个 Action 职责单一：权限校验 → 解析 → DB 写入 → 审计日志 → revalidatePath。
|
||||
- data-access.ts 仅包含只读查询，无跨模块写入。
|
||||
- 权限校验完整：SCHOOL_MANAGE / GRADE_MANAGE 均接入 requirePermission。
|
||||
|
||||
**问题**：
|
||||
- ⚠️ **审计日志不一致**：仅 school 实体的 create/update/delete 调用了 `logAudit`，而 department / academicYear / grade 的 CRUD 均未记录审计日志。
|
||||
- ⚠️ `getStaffOptions` / `getGrades` 直接查询 users / roles / usersToRoles 表（跨模块读），但属于展示用关联查询，可接受。
|
||||
|
||||
**建议**：为 department / academicYear / grade 的 CRUD 补充 `logAudit` 调用，保持审计一致性。
|
||||
|
||||
---
|
||||
|
||||
### 2.2 classes 模块 — 🔴 严重
|
||||
|
||||
**文件清单**：actions.ts (765 行) / data-access.ts (**2104 行**) / types.ts (201 行)
|
||||
|
||||
> ⚠️ `data-access.ts` 达 2104 行，**超出 1000 行硬性上限 2 倍**，违反项目代码质量规则。
|
||||
|
||||
#### 2.2.1 职责混乱 — 混入三个外部业务领域
|
||||
|
||||
`data-access.ts` 实际承载了四个业务领域的逻辑：
|
||||
|
||||
| 行范围 | 逻辑 | 应属模块 |
|
||||
|--------|------|---------|
|
||||
| 49-145 | 教师身份解析、班级访问控制 | classes（合理） |
|
||||
| 156-601 | 班级列表/学生/教师查询 | classes（合理） |
|
||||
| 697-735 | 课表查询 `getClassSchedule` | **scheduling** |
|
||||
| 760-998 | `getClassHomeworkInsights` 班级作业洞察（238 行） | **homework** |
|
||||
| 1006-1300 | `getGradeHomeworkInsights` 年级作业洞察（294 行） | **homework** |
|
||||
| 1302-1775 | 班级 CRUD + 邀请码 + 注册 | classes（合理） |
|
||||
| 1838-1968 | 课表项 CRUD `createClassScheduleItem` 等 | **scheduling** |
|
||||
| 1970-2103 | `getStudentsSubjectScores` 学生科目成绩（133 行） | **grades / homework** |
|
||||
|
||||
**关键问题**：
|
||||
- `getClassHomeworkInsights` 和 `getGradeHomeworkInsights` 合计 **532 行**作业统计逻辑，直接查询 `homeworkAssignments`、`homeworkSubmissions`、`homeworkAssignmentTargets`、`homeworkAssignmentQuestions`、`exams` 五张表，属于 homework 模块的核心业务，不应存在于 classes 模块。
|
||||
- 课表 CRUD（`createClassScheduleItem` / `updateClassScheduleItem` / `deleteClassScheduleItem`）与 scheduling 模块的 `applyAutoScheduleAction` 写入同一张 `classSchedule` 表，**两个模块对同一张表有写权限**，边界严重模糊。
|
||||
- `getStudentsSubjectScores` 直接关联 `homeworkSubmissions` + `exams` + `subjects` 计算学生科目分数，属于成绩分析逻辑。
|
||||
|
||||
#### 2.2.2 types.ts 跨领域类型污染
|
||||
|
||||
`types.ts` 定义了本应属于其他模块的类型：
|
||||
- `ClassHomeworkInsights` / `GradeHomeworkInsights` / `ClassHomeworkAssignmentStats` / `ScoreStats` / `AssignmentSummary` — 应属 homework 模块
|
||||
- `ClassScheduleItem` / `CreateClassScheduleItemInput` / `UpdateClassScheduleItemInput` / `StudentScheduleItem` — 与 scheduling 模块的 `types.ts` 存在概念重叠
|
||||
|
||||
#### 2.2.3 actions.ts 跨模块直接查询
|
||||
|
||||
`actions.ts` 多处直接查询 `grades` 表（属于 school 模块）进行权限验证，绕过了 school/data-access：
|
||||
|
||||
| 行号 | 函数 | 直接查询 |
|
||||
|------|------|---------|
|
||||
| 60-68 | `createTeacherClassAction` | `db.select().from(grades)` 校验 gradeHead 权限 |
|
||||
| 186-194 | `createGradeClassAction` | `db.select().from(grades)` 校验年级管理权 |
|
||||
| 241-249 | `updateGradeClassAction` | `db.select().from(classes)` 绕过自身 data-access |
|
||||
| 251-272 | `updateGradeClassAction` | `db.select().from(grades)` 校验源/目标年级 |
|
||||
| 340-348 | `deleteGradeClassAction` | `db.select().from(grades)` 校验权限 |
|
||||
|
||||
**问题**：权限校验逻辑散落在 actions 层，既未下沉到 data-access，也未通过 school 模块暴露的查询接口。
|
||||
|
||||
#### 2.2.4 actions.ts 职责重复
|
||||
|
||||
存在三组近乎重复的 Action 集合：
|
||||
- Teacher 系列：`createTeacherClassAction` / `updateTeacherClassAction` / `deleteTeacherClassAction`
|
||||
- Admin 系列：`createAdminClassAction` / `updateAdminClassAction` / `deleteAdminClassAction`
|
||||
- Grade 系列：`createGradeClassAction` / `updateGradeClassAction` / `deleteGradeClassAction`
|
||||
|
||||
三者表单解析、字段校验逻辑高度重复，仅权限上下文不同。
|
||||
|
||||
#### 2.2.5 data-access.ts 内调用 auth()
|
||||
|
||||
`getSessionTeacherId`（行 49-62）在 data-access 层直接调用 `auth()` 获取会话，违反"data-access 不感知请求上下文"的分层原则。会话信息应由 actions 层传入。
|
||||
|
||||
#### 2.2.6 组件层边界模糊
|
||||
|
||||
`classes/components/` 包含 `schedule-view.tsx`、`schedule-filters.tsx`、`class-detail/class-schedule-widget.tsx` 等课表相关组件，与 `scheduling/components/` 的职责重叠。
|
||||
|
||||
**整改建议**（优先级 P0）：
|
||||
1. 将 `getClassHomeworkInsights` / `getGradeHomeworkInsights` / `getStudentsSubjectScores` / `getClassStudentSubjectScoresV2` 迁移至 homework / grades 模块。
|
||||
2. 将课表 CRUD（`createClassScheduleItem` 等）迁移至 scheduling 模块，统一 `classSchedule` 表的写入口。
|
||||
3. 将 `data-access.ts` 拆分为 `data-access.ts`（班级 CRUD）+ `data-access-enrollments.ts`（注册/邀请码）+ `data-access-insights.ts`（如暂不迁移则隔离）。
|
||||
4. 将权限校验中的 `grades` 表查询改为调用 school/data-access 暴露的接口。
|
||||
5. 将 `getSessionTeacherId` 上移至 actions 层或 shared/lib。
|
||||
|
||||
---
|
||||
|
||||
### 2.3 scheduling 模块 — 🟡 需改进（算法层优秀）
|
||||
|
||||
**文件清单**：actions.ts (302 行) / auto-scheduler.ts (310 行) / data-access.ts (272 行) / schema.ts / types.ts
|
||||
|
||||
#### 2.3.1 auto-scheduler.ts — ✅ 优秀范例
|
||||
|
||||
**这是全项目算法独立化的最佳实践**：
|
||||
- 纯函数：`findOptimalSlot` / `validateSchedule` / `autoSchedule` / `buildDefaultTimeSlots`
|
||||
- 无 `"server-only"` 副作用，无 DB 访问，无 `import { db }`
|
||||
- 仅依赖 types.ts 的类型导入
|
||||
- **可独立单元测试**：给定输入即可断言输出，无需 mock 数据库
|
||||
- 算法清晰：贪心 + 约束检查（午餐、每日上限、教师/教室冲突、避免连排）
|
||||
|
||||
**建议**：以此为模板，指导其他模块的算法抽取（如 homework 的批改评分算法、grades 的统计算法）。
|
||||
|
||||
#### 2.3.2 actions.ts — 跨模块直接写入
|
||||
|
||||
| 行号 | 函数 | 问题 |
|
||||
|------|------|------|
|
||||
| 110-116 | `autoScheduleAction` | 直接 `db.select().from(users)` 查询教师，绕过 data-access 的 `getTeachersForScheduling` |
|
||||
| 168-180 | `applyAutoScheduleAction` | 直接 `db.transaction` 写入 `classSchedule` 表，**绕过 data-access 且跨模块写 classes 领域的表** |
|
||||
|
||||
`applyAutoScheduleAction` 的问题尤为突出：它删除并重建 `classSchedule` 表数据，但该写操作既未经过 scheduling/data-access，也未经过 classes/data-access，形成**第三个对 classSchedule 表的写入口**（另两个在 classes/data-access 的 createClassScheduleItem 等）。
|
||||
|
||||
#### 2.3.3 data-access.ts — 跨模块读查询
|
||||
|
||||
包含 `getAdminClassesForScheduling` / `getTeachersForScheduling` / `getClassroomsForScheduling` / `getClassSubjectsForScheduling` 四个辅助查询，直接访问 `classes` / `classSubjectTeachers` / `subjects` / `users` / `classrooms` 表。
|
||||
|
||||
这些是排课场景的只读辅助查询，耦合度可接受，但理想情况下应通过各所属模块的 data-access 暴露接口。
|
||||
|
||||
#### 2.3.4 actions.ts 末尾 re-export
|
||||
|
||||
```typescript
|
||||
export { getSchedulingRules, getScheduleChanges, ... } from "./data-access"
|
||||
```
|
||||
actions 层 re-export data-access 函数是反模式，应让消费方直接从 data-access 导入。
|
||||
|
||||
**整改建议**：
|
||||
1. 将 `applyAutoScheduleAction` 中的 `classSchedule` 写入逻辑下沉到 data-access（或与 classes 协商统一写入口）。
|
||||
2. 将 `autoScheduleAction` 中的 users 查询改用 `getTeachersForScheduling`。
|
||||
3. 移除 actions.ts 末尾的 re-export。
|
||||
|
||||
---
|
||||
|
||||
### 2.4 attendance 模块 — 🟢 合格（结构典范）
|
||||
|
||||
**文件清单**：actions.ts (271 行) / data-access.ts (271 行) / data-access-stats.ts (145 行) / schema.ts / types.ts
|
||||
|
||||
**优点**：
|
||||
- **stats 独立拆分**：`data-access-stats.ts` 专门承载统计逻辑，是 classes 模块应学习的拆分模式。
|
||||
- actions.ts 每个 Action 职责单一：权限校验 → 解析 → 委托 data-access → revalidate。
|
||||
- `DataScope` 数据范围控制完整接入，支持 6 种 scope 类型。
|
||||
- 无写操作泄漏到 actions 层。
|
||||
|
||||
**问题**：
|
||||
- ⚠️ `getClassStudentsForAttendance`（data-access.ts 行 206-217）直接查询 `classEnrollments` 表获取班级学生列表，属于 classes 模块数据，应通过 classes/data-access 暴露的接口调用。
|
||||
- ⚠️ data-access.ts 和 data-access-stats.ts 均直接 JOIN `classes` 表获取班级名称（只读展示，可接受）。
|
||||
|
||||
**整改建议**：在 classes/data-access 暴露 `getClassStudentIds(classId)` 接口，供 attendance 调用。
|
||||
|
||||
---
|
||||
|
||||
### 2.5 users 模块 — 🟠 较严重
|
||||
|
||||
**文件清单**：actions.ts (151 行) / data-access.ts (71 行) / import-export.ts (291 行)
|
||||
|
||||
#### 2.5.1 import-export.ts — 四重职责混合
|
||||
|
||||
该文件同时承载四类互不相关的职责：
|
||||
|
||||
| 行范围 | 职责 | 应属位置 |
|
||||
|--------|------|---------|
|
||||
| 54-73 | `generateUserImportTemplate` 生成导入模板 | export 模块 |
|
||||
| 78-111 | `parseUserImportData` 解析+校验导入数据 | import 模块 |
|
||||
| 116-207 | `batchImportUsers` 批量导入（含用户创建） | **data-access** |
|
||||
| 212-291 | `exportUsersToExcel` 导出用户列表 | export 模块 |
|
||||
|
||||
**核心问题**：
|
||||
1. **导入与导出未分离**：应拆分为 `import.ts` 与 `export.ts`。
|
||||
2. **用户创建逻辑泄漏**：`batchImportUsers`（行 158-167）直接 `db.insert(users)` + 密码哈希 + `db.insert(usersToRoles)`，这是 data-access 层的职责，不应存在于 import-export 工具文件中。
|
||||
3. **跨模块写 classEnrollments**：行 174-184，`batchImportUsers` 直接 `db.insert(classEnrollments)` 将学生注册到班级，**这是 classes 模块的写操作**，严重违反模块边界。
|
||||
4. **跨模块读 classes**：行 130-137，直接查询 `classes` 表根据邀请码查找班级，应通过 classes/data-access 暴露接口。
|
||||
|
||||
#### 2.5.2 actions.ts — 绕过 data-access
|
||||
|
||||
`updateUserProfile`（行 29-51）直接 `db.update(users)` 写入数据库，绕过了 data-access 层。data-access.ts 仅有 `getUserProfile` 一个读函数，写操作缺失。
|
||||
|
||||
#### 2.5.3 data-access.ts — 过于单薄
|
||||
|
||||
仅 71 行，只包含 `getUserProfile`。用户创建、更新、角色绑定等写操作均未在此层实现。
|
||||
|
||||
**整改建议**（优先级 P1）：
|
||||
1. 将 `import-export.ts` 拆分为 `import.ts`（解析+校验）和 `export.ts`（模板生成+列表导出）。
|
||||
2. 将 `batchImportUsers` 中的用户创建逻辑迁移至 `data-access.ts` 的 `createUser` 函数，import.ts 仅负责编排。
|
||||
3. 将 classEnrollments 写入改为调用 classes/data-access 的注册接口（如 `enrollStudentByInvitationCode`）。
|
||||
4. 将 `updateUserProfile` 的 DB 写入下沉到 data-access。
|
||||
|
||||
---
|
||||
|
||||
### 2.6 audit 模块 — 🟡 需改进
|
||||
|
||||
**文件清单**：actions.ts (212 行) / data-access.ts (260 行) / types.ts
|
||||
|
||||
**问题**：
|
||||
- ⚠️ **Excel 导出逻辑内联在 actions 层**：`exportAuditLogsAction` / `exportLoginLogsAction` / `exportDataChangeLogsAction` 三个 Action 各自内联了 `exportToExcel` 调用及完整的列定义（表头、宽度、字段映射），每个约 40 行。这是展示/格式化逻辑，应抽取到独立的 `export.ts`。
|
||||
- ⚠️ 三个导出 Action 的结构高度重复（权限校验 → 查询 → 构造 columns → exportToExcel → 返回 buffer），可抽象为通用导出工厂。
|
||||
|
||||
**优点**：
|
||||
- data-access.ts 职责清晰，仅包含日志查询，无跨模块问题。
|
||||
- 分页逻辑统一（clampPage / clampPageSize）。
|
||||
|
||||
**整改建议**：抽取 `export.ts`，封装 `exportAuditLogsToExcel(items)` / `exportLoginLogsToExcel(items)` / `exportDataChangeLogsToExcel(items)`，actions 层仅负责编排。
|
||||
|
||||
---
|
||||
|
||||
### 2.7 course-plans 模块 — 🟢 合格
|
||||
|
||||
**文件清单**：actions.ts (265 行) / data-access.ts (320 行) / schema.ts / types.ts
|
||||
|
||||
**优点**：
|
||||
- actions.ts 使用 `handleError` / `revalidatePlanPaths` 辅助函数消除重复，是 actions 层的**良好范例**。
|
||||
- data-access.ts 职责清晰：课程计划 CRUD + 周计划项 CRUD + 排序。
|
||||
- 跨模块查询仅为 `classes` / `subjects` / `users` 的 LEFT JOIN 取展示名称（只读，可接受）。
|
||||
|
||||
**小问题**：
|
||||
- ⚠️ `getSubjectOptions`（行 310-320）直接查询 `subjects` 表，subjects 无独立模块，暂可接受。
|
||||
|
||||
**结论**：该模块结构可作为其他模块的参考模板。
|
||||
|
||||
---
|
||||
|
||||
### 2.8 announcements 模块 — 🟡 需改进
|
||||
|
||||
**文件清单**：actions.ts (242 行) / data-access.ts (120 行) / schema.ts / types.ts
|
||||
|
||||
**核心问题 — 写操作泄漏到 actions 层**：
|
||||
|
||||
data-access.ts 仅包含两个**只读**函数（`getAnnouncements` / `getAnnouncementById`），所有写操作均直接在 actions.ts 中执行 `db.insert` / `db.update` / `db.delete`：
|
||||
|
||||
| Action | 直接 DB 操作 | 行号 |
|
||||
|--------|-------------|------|
|
||||
| `createAnnouncementAction` | `db.insert(announcements)` | 53-63 |
|
||||
| `updateAnnouncementAction` | `db.update(announcements)` | 118-130 |
|
||||
| `deleteAnnouncementAction` | `db.delete(announcements)` | 154 |
|
||||
| `publishAnnouncementAction` | `db.update(announcements)` | 176-183 |
|
||||
| `archiveAnnouncementAction` | `db.update(announcements)` | 206-212 |
|
||||
|
||||
这违反了"data-access 层封装所有 DB 操作"的分层约定，导致：
|
||||
- 写逻辑无法被其他 server 端代码复用
|
||||
- publishedAt 计算逻辑散落在 actions 中，难以测试
|
||||
|
||||
**其他问题**：
|
||||
- ⚠️ 死代码：`updateAnnouncementAction` 行 108 计算 `wasPublished`，行 135 `void wasPublished` 显式丢弃，未实际使用。
|
||||
- ⚠️ `getAnnouncementsAction` 使用 `requireAuth()` 而非 `requirePermission(ANNOUNCEMENT_READ)`，与其他模块的权限模式不一致。
|
||||
|
||||
**整改建议**：
|
||||
1. 在 data-access.ts 补充 `createAnnouncement` / `updateAnnouncement` / `deleteAnnouncement` / `publishAnnouncement` / `archiveAnnouncement` 写函数。
|
||||
2. actions 层仅保留权限校验 + 解析 + 委托调用。
|
||||
3. 清理 `wasPublished` 死代码。
|
||||
|
||||
---
|
||||
|
||||
## 三、跨模块直接查询汇总
|
||||
|
||||
### 3.1 跨模块写操作（严重）
|
||||
|
||||
| 源文件 | 目标表 | 操作 | 应通过 |
|
||||
|--------|--------|------|--------|
|
||||
| classes/data-access.ts | classSchedule | CRUD | scheduling/data-access |
|
||||
| scheduling/actions.ts | classSchedule | delete + insert | scheduling/data-access |
|
||||
| users/import-export.ts | classEnrollments | insert | classes/data-access |
|
||||
| users/import-export.ts | users, usersToRoles | insert | users/data-access |
|
||||
| announcements/actions.ts | announcements | insert/update/delete | announcements/data-access |
|
||||
| users/actions.ts | users | update | users/data-access |
|
||||
|
||||
> ⚠️ `classSchedule` 表存在 **三个写入口**（classes/data-access、scheduling/actions、scheduling/data-access 间接），是数据完整性高风险点。
|
||||
|
||||
### 3.2 跨模块读操作（需评估）
|
||||
|
||||
| 源文件 | 目标表 | 用途 | 评估 |
|
||||
|--------|--------|------|------|
|
||||
| classes/data-access.ts | homeworkAssignments, homeworkSubmissions, homeworkAssignmentTargets, homeworkAssignmentQuestions, exams | 作业洞察统计 | ❌ 应迁移至 homework |
|
||||
| classes/data-access.ts | grades, schools | 年级/学校关联 | ⚠️ 应通过 school data-access |
|
||||
| classes/actions.ts | grades | 权限校验 | ⚠️ 应通过 school data-access |
|
||||
| scheduling/data-access.ts | classes, classSubjectTeachers, subjects, users, classrooms | 排课辅助查询 | 🟡 可接受（只读） |
|
||||
| attendance/data-access.ts | classEnrollments | 获取班级学生 | ⚠️ 应通过 classes data-access |
|
||||
| users/import-export.ts | classes | 邀请码查询 | ⚠️ 应通过 classes data-access |
|
||||
| course-plans/data-access.ts | classes, subjects, users | 展示名称 JOIN | 🟢 可接受 |
|
||||
|
||||
---
|
||||
|
||||
## 四、actions 层多职责问题汇总
|
||||
|
||||
| Action | 混入职责 | 应拆分 |
|
||||
|--------|---------|--------|
|
||||
| `users/import-export.ts: batchImportUsers` | 用户创建 + 密码哈希 + 角色绑定 + 班级注册 | 拆为 createUser + enrollStudent |
|
||||
| `classes/actions.ts: updateGradeClassAction` | 班级更新 + 科任教师批量分配 | 拆为 updateClass + setClassSubjectTeachers（已部分拆分但仍在同一 Action 内编排） |
|
||||
| `classes/actions.ts: updateAdminClassAction` | 同上 | 同上 |
|
||||
| `audit/actions.ts: exportAuditLogsAction` | 查询 + Excel 列定义 + 导出 | 拆为 query + exportAuditLogsToExcel |
|
||||
| `audit/actions.ts: exportLoginLogsAction` | 同上 | 同上 |
|
||||
| `audit/actions.ts: exportDataChangeLogsAction` | 同上 | 同上 |
|
||||
| `announcements/actions.ts: createAnnouncementAction` | 解析 + publishedAt 计算 + DB 写入 | DB 写入下沉 data-access |
|
||||
|
||||
---
|
||||
|
||||
## 五、整改优先级
|
||||
|
||||
### P0 — 立即整改（影响数据完整性 & 严重违反规范）
|
||||
|
||||
1. **classes/data-access.ts 拆分**：2104 行远超硬性上限，且混入 homework/scheduling/grades 三个领域。优先迁移 `getClassHomeworkInsights` / `getGradeHomeworkInsights`（532 行）至 homework 模块。
|
||||
2. **统一 classSchedule 表写入口**：classes 与 scheduling 两个模块对该表有写权限，需协商归属并收敛为单一写入口。
|
||||
|
||||
### P1 — 尽快整改（模块边界违反）
|
||||
|
||||
3. **users/import-export.ts 拆分**：分离导入/导出，用户创建逻辑下沉 data-access，classEnrollments 写入改调 classes 接口。
|
||||
4. **announcements 写操作下沉**：在 data-access 补充写函数，actions 仅编排。
|
||||
5. **classes/actions.ts 权限校验**：grades 表查询改通过 school/data-access 接口。
|
||||
|
||||
### P2 — 持续优化（代码质量）
|
||||
|
||||
6. **audit 导出逻辑抽取**：内联的 Excel 列定义移至独立 export.ts。
|
||||
7. **school 审计日志补全**：department/academicYear/grade 的 CRUD 补充 logAudit。
|
||||
8. **attendance 跨模块查询**：`getClassStudentsForAttendance` 改调 classes 接口。
|
||||
9. **scheduling/actions.ts**：移除 re-export，DB 写入下沉 data-access。
|
||||
10. **announcements 死代码清理**：移除 `void wasPublished`。
|
||||
|
||||
---
|
||||
|
||||
## 六、优秀实践（建议推广）
|
||||
|
||||
| 实践 | 模块 | 说明 |
|
||||
|------|------|------|
|
||||
| 算法纯函数化 | scheduling/auto-scheduler.ts | 无 DB 依赖，可独立测试，应作为算法抽取模板 |
|
||||
| stats 文件拆分 | attendance/data-access-stats.ts | 统计逻辑独立成文件，classes 应效仿 |
|
||||
| actions 辅助函数 | course-plans/actions.ts | handleError / revalidatePlanPaths 消除重复 |
|
||||
| DataScope 接入 | attendance/actions.ts | 6 种数据范围完整支持 |
|
||||
| 权限统一接入 | school / attendance / course-plans | 全部 Action 使用 requirePermission |
|
||||
|
||||
---
|
||||
|
||||
## 七、附：文件行数统计
|
||||
|
||||
| 文件 | 行数 | 上限 | 状态 |
|
||||
|------|------|------|------|
|
||||
| classes/data-access.ts | 2104 | 1000 | 🔴 超限 2.1x |
|
||||
| classes/actions.ts | 765 | 800（建议） | 🟢 合规 |
|
||||
| classes/types.ts | 201 | 无限制 | 🟢 合规 |
|
||||
| school/actions.ts | 325 | 800（建议） | 🟢 合规 |
|
||||
| school/data-access.ts | 186 | 800（建议） | 🟢 合规 |
|
||||
| scheduling/auto-scheduler.ts | 310 | 无限制 | 🟢 合规 |
|
||||
| scheduling/actions.ts | 302 | 800（建议） | 🟢 合规 |
|
||||
| scheduling/data-access.ts | 272 | 800（建议） | 🟢 合规 |
|
||||
| attendance/actions.ts | 271 | 800（建议） | 🟢 合规 |
|
||||
| attendance/data-access.ts | 271 | 800（建议） | 🟢 合规 |
|
||||
| attendance/data-access-stats.ts | 145 | 800（建议） | 🟢 合规 |
|
||||
| users/import-export.ts | 291 | 800（建议） | 🟢 合规（但职责混合） |
|
||||
| users/actions.ts | 151 | 800（建议） | 🟢 合规 |
|
||||
| users/data-access.ts | 71 | 800（建议） | 🟢 合规 |
|
||||
| audit/actions.ts | 212 | 800（建议） | 🟢 合规 |
|
||||
| audit/data-access.ts | 260 | 800（建议） | 🟢 合规 |
|
||||
| course-plans/actions.ts | 265 | 800（建议） | 🟢 合规 |
|
||||
| course-plans/data-access.ts | 320 | 800（建议） | 🟢 合规 |
|
||||
| announcements/actions.ts | 242 | 800（建议） | 🟢 合规 |
|
||||
| announcements/data-access.ts | 120 | 800（建议） | 🟢 合规 |
|
||||
|
||||
> 仅 `classes/data-access.ts` 突破硬性上限，需立即拆分。
|
||||
|
||||
---
|
||||
|
||||
*报告结束。本审查未修改任何源代码。*
|
||||
604
docs/architecture/audit/new-and-other-modules-audit.md
Normal file
604
docs/architecture/audit/new-and-other-modules-audit.md
Normal file
@@ -0,0 +1,604 @@
|
||||
# 新增模块与其他模块架构审查报告
|
||||
|
||||
> 审查范围：elective / proctoring / diagnostic / notifications / dashboard / messaging / parent / settings / files / auth / layout / student
|
||||
> 审查日期：2026-06-17
|
||||
> 审查依据：源码全量扫描 + 架构影响地图(004/005) + 差距审计报告(007)
|
||||
> 审查目标：识别职责不单一、过耦合、边界模糊、幽灵路由等问题
|
||||
|
||||
---
|
||||
|
||||
## 一、总体评估
|
||||
|
||||
| 维度 | 模块数 | 严重问题 | 中等问题 | 轻微问题 | 总体评价 |
|
||||
|------|--------|---------|---------|---------|----------|
|
||||
| 新增模块 | 4 | 3 | 5 | 3 | ⚠️ 职责基本清晰，但存在跨模块耦合与未集成代码 |
|
||||
| 其他模块 | 8 | 1 | 4 | 3 | ⚠️ dashboard 跨模块直查问题突出 |
|
||||
| **合计** | **12** | **4** | **9** | **6** | **需重点修复 4 项严重问题** |
|
||||
|
||||
### 严重问题清单（必须修复）
|
||||
|
||||
1. **messaging 与 notifications 边界模糊、双向依赖** — 两个模块都写入 `messageNotifications` 表，notifications 反向依赖 messaging，类型系统不一致
|
||||
2. **dashboard/data-access.ts 直查 11 张跨模块表** — 违反模块封装原则
|
||||
3. **proctoring/exam-mode-config.tsx 未集成到考试表单** — DB schema 有 examMode 等字段但无 UI 录入入口，组件成为死代码
|
||||
4. **proctoring 事件上报存在 Server Action 与 REST API 双通道重复** — 同一逻辑两份代码
|
||||
|
||||
---
|
||||
|
||||
## 二、新增模块审查
|
||||
|
||||
### 2.1 elective 模块（选课管理）
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 304 | 11 个 Server Action（CRUD + 选课 + 抽签 + 查询） |
|
||||
| `data-access.ts` | 242 | 课程 CRUD + 查询 + scope 过滤 |
|
||||
| `data-access-operations.ts` | 217 | 选课操作（select/drop/lottery） |
|
||||
| `data-access-selections.ts` | 189 | 选课记录查询 + 学生可用课程查询 |
|
||||
| `schema.ts` | 132 | Zod 校验 schema |
|
||||
| `types.ts` | 108 | 类型定义 + 标签常量 |
|
||||
|
||||
#### 拆分为 3 个 data-access 文件是否合理？
|
||||
|
||||
**结论：⚠️ 拆分意图合理，但存在代码重复**
|
||||
|
||||
- **拆分意图合理**：operations（写操作）与 selections（读查询）职责分明，符合"按职责划分"原则
|
||||
- **代码重复问题**：`data-access.ts` 与 `data-access-selections.ts` 重复定义了 `mapCourseRow` 和 `buildCourseSelect` 两个函数（共约 60 行重复代码）
|
||||
- `data-access.ts` 第 47-108 行
|
||||
- `data-access-selections.ts` 第 28-88 行
|
||||
- 两份代码完全相同，维护时易产生不一致
|
||||
|
||||
**建议**：
|
||||
- 抽取共享的 `mapCourseRow` / `buildCourseSelect` 到 `data-access.ts` 并导出，`data-access-selections.ts` 复用
|
||||
- 或合并 `data-access-selections.ts` 到 `data-access.ts`（文件仅 189 行，合并后仍在 800 行上限内）
|
||||
|
||||
#### 权限校验
|
||||
|
||||
✅ 全部 Server Action 均使用 `requirePermission`：
|
||||
- 管理 Action 使用 `ELECTIVE_MANAGE`
|
||||
- 选课 Action 使用 `ELECTIVE_SELECT`
|
||||
- 查询 Action 使用 `ELECTIVE_READ`
|
||||
- 学生查看他人选课记录有额外 dataScope 校验（actions.ts 第 283-288 行）
|
||||
|
||||
#### 其他发现
|
||||
|
||||
- ✅ schema.ts 使用 Zod transform 统一处理空字符串转 null，规范
|
||||
- ⚠️ `data-access-operations.ts` 的 `runLottery` 使用 `Math.random()` 排序（第 40 行），结果不可复现，建议改用 DB 的 `ORDER BY RAND()` 或记录种子
|
||||
- ⚠️ `selectCourse` 在 FCFS 模式下先查后写（第 119-128 行），存在并发超卖风险，建议加事务或乐观锁
|
||||
|
||||
---
|
||||
|
||||
### 2.2 proctoring 模块（考试监考）
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 144 | 2 个 Server Action（上报事件 + 获取面板） |
|
||||
| `data-access.ts` | 388 | 事件记录 + 查询 + 摘要统计 + 学生状态 |
|
||||
| `types.ts` | 136 | 类型定义 + 标签常量 + 阈值常量 |
|
||||
| `components/anti-cheat-monitor.tsx` | - | 学生端防作弊监控 |
|
||||
| `components/exam-mode-config.tsx` | - | 考试模式配置表单（**未集成**） |
|
||||
| `components/proctoring-dashboard.tsx` | - | 教师监考面板 |
|
||||
|
||||
#### 职责清晰度
|
||||
|
||||
**结论：⚠️ 职责基本清晰，但存在 3 个严重问题**
|
||||
|
||||
#### 严重问题 1：`exam-mode-config.tsx` 未集成到考试表单（死代码）
|
||||
|
||||
- DB schema 已有 `examMode` / `durationMinutes` / `shuffleQuestions` / `allowLateStart` / `antiCheatEnabled` 字段（schema.ts 第 457-462 行）
|
||||
- `proctoring/components/exam-mode-config.tsx` 提供了完整的配置 UI 组件
|
||||
- **但 `exams/components/exam-form.tsx` 并未导入该组件**（grep 确认无 `ExamModeConfig` 引用）
|
||||
- `exams/components/exam-mode-selector.tsx` 是"手动组卷 vs AI 生成"的选择器，**与考试模式（homework/timed/proctored）无关**，命名易混淆
|
||||
- 结果：创建考试时无法设置监考模式，proctoring 模块的 `getExamForProctoring` 读取的 `examMode` 永远是默认值 `"homework"`
|
||||
|
||||
**建议**：将 `exam-mode-config.tsx` 集成到 `exam-form.tsx`，或迁移到 exams 模块
|
||||
|
||||
#### 严重问题 2：事件上报存在 Server Action 与 REST API 双通道重复
|
||||
|
||||
- `proctoring/actions.ts` 第 58-105 行：`recordProctoringEventAction`（Server Action）
|
||||
- `app/api/proctoring/event/route.ts` 第 27-90 行：POST handler（REST API）
|
||||
- **两者逻辑完全相同**：都校验 submission 归属、调用 `recordProctoringEvent`
|
||||
- `AntiCheatMonitor` 组件使用 Server Action（第 58 行），REST API 路由无调用方
|
||||
|
||||
**建议**：删除未使用的 `/api/proctoring/event` 路由，或让组件改用 REST API（适用于客户端轮询场景）
|
||||
|
||||
#### 中等问题 3：跨模块读取 exams 表
|
||||
|
||||
- `data-access.ts` 第 326-353 行：`getExamForProctoring` 直接查询 `exams` 表
|
||||
- 第 178-185 行：`getExamProctoringSummary` 直接查询 `examSubmissions` 表
|
||||
- 第 249-256 行：`getStudentProctoringStatuses` 直接 join `examSubmissions` 和 `users`
|
||||
|
||||
**建议**：可接受（监考本质是考试模块的扩展），但应在架构图中标注依赖关系
|
||||
|
||||
#### 其他发现
|
||||
|
||||
- ✅ `recordProctoringEventAction` 使用 `requireAuth()` 而非 `requirePermission`，符合"学生上报自己事件"场景
|
||||
- ✅ `getProctoringDashboardAction` 使用 `EXAM_PROCTOR` 权限
|
||||
- ✅ 异常阈值 `ABNORMAL_EVENT_THRESHOLD = 3` 提取为常量，便于调整
|
||||
- ⚠️ `actions.ts` 第 11-13 行直接 import `db` 和 `examSubmissions`，应在 data-access 层封装 submission 校验逻辑
|
||||
|
||||
---
|
||||
|
||||
### 2.3 diagnostic 模块（学情诊断）
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 148 | 6 个 Server Action（生成/发布/删除/查询报告） |
|
||||
| `data-access.ts` | 254 | 知识点掌握度查询 + 从提交更新掌握度 |
|
||||
| `data-access-reports.ts` | 202 | 诊断报告 CRUD |
|
||||
| `types.ts` | 97 | 类型定义 |
|
||||
| `components/` | 4 个 | 学生/班级诊断视图 + 雷达图 + 报告列表 |
|
||||
|
||||
#### 与 grades 模块的边界
|
||||
|
||||
**结论：✅ 无职责重叠，但存在跨模块耦合**
|
||||
|
||||
- **grades 模块**：管理 `gradeRecords` 表（分数记录），维度是"学生-班级-科目-考试"
|
||||
- **diagnostic 模块**：管理 `knowledgePointMastery` 表（知识点掌握度），维度是"学生-知识点"
|
||||
- 两者数据来源不同：grades 是教师录入的分数，diagnostic 是从 `submissionAnswers` 推导的正确率
|
||||
- **无任何代码重叠**：grep 确认 grades 模块无 `knowledgePoint` / `mastery` / `diagnostic` 关键字
|
||||
|
||||
#### 中等问题 1：`data-access.ts` 跨模块直查 4 张表
|
||||
|
||||
- 第 87-92 行：查询 `examSubmissions` 表（属 exams 模块）
|
||||
- 第 95-101 行：查询 `submissionAnswers` 表（属 exams/homework 模块）
|
||||
- 第 106-112 行：查询 `questionsToKnowledgePoints` 表（属 questions 模块）
|
||||
- 第 150-158 行：查询 `classEnrollments` + `classes` + `users` 表（属 classes 模块）
|
||||
|
||||
`updateMasteryFromSubmission` 函数（第 87-147 行）直接读取提交答案和题目-知识点关联，将 diagnostic 模块与 exams/homework/questions 模块紧耦合。
|
||||
|
||||
**建议**：
|
||||
- 短期：在架构图中标注此依赖关系
|
||||
- 长期：由 exams/homework 模块在提交评分后主动调用 diagnostic 模块的更新接口（事件驱动）
|
||||
|
||||
#### 轻微问题 2：`data-access-reports.ts` 有未使用代码
|
||||
|
||||
- 第 20 行定义 `round2` 函数
|
||||
- 第 201 行 `void round2` 仅为消除 lint 警告
|
||||
- **建议**：删除未使用的 `round2` 函数
|
||||
|
||||
#### 轻微问题 3：班级报告字段复用不当
|
||||
|
||||
- `data-access-reports.ts` 第 107 行：`studentId: generatedBy` — 班级报告将生成者 ID 存入 `studentId` 字段
|
||||
- 注释说明"schema 要求 NOT NULL"，但这是 schema 设计缺陷的 workaround
|
||||
- **建议**：修改 `learningDiagnosticReports` schema，将 `studentId` 改为可空，或增加 `classId` 字段
|
||||
|
||||
#### 权限校验
|
||||
|
||||
✅ 全部 Action 使用 `DIAGNOSTIC_MANAGE` 或 `DIAGNOSTIC_READ` 权限
|
||||
|
||||
---
|
||||
|
||||
### 2.4 notifications 模块（通知分发）
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 119 | 2 个 Server Action（单发 + 班级群发） |
|
||||
| `data-access.ts` | 86 | 用户偏好 + 联系方式 + 日志 |
|
||||
| `dispatcher.ts` | 152 | 渠道选择 + 并行分发 |
|
||||
| `types.ts` | 70 | 通知负载 + 渠道配置类型 |
|
||||
| `index.ts` | 38 | 对外导出入口 |
|
||||
| `channels/` | 5 个 | SMS/Email/WeChat/InApp 渠道实现 |
|
||||
|
||||
#### 严重问题 1：与 messaging 模块双向依赖、边界模糊
|
||||
|
||||
详见下文"三、messaging vs notifications 边界分析"。
|
||||
|
||||
#### 中等问题 2：`sendClassNotificationAction` 跨模块直查
|
||||
|
||||
- `actions.ts` 第 83-96 行：直接查询 `classes` 和 `classEnrollments` 表
|
||||
- 应通过 classes 模块的 data-access 获取班级学生列表
|
||||
|
||||
**建议**：调用 `classes` 模块的 data-access 函数获取学生 ID 列表
|
||||
|
||||
#### 中等问题 3：发送日志仅 console 输出
|
||||
|
||||
- `data-access.ts` 第 71-77 行：`logNotificationSend` 使用 `console.info`
|
||||
- 代码注释承认"当前项目无 notification_logs 表"
|
||||
- **影响**：无法查询历史发送记录、无法统计发送成功率、无法排查发送失败
|
||||
|
||||
**建议**：新增 `notification_logs` 表，记录 channel/userId/payload/success/error/sentAt
|
||||
|
||||
#### 轻微问题 4：复用 MESSAGE_SEND 权限
|
||||
|
||||
- `actions.ts` 第 34、67 行：使用 `Permissions.MESSAGE_SEND`
|
||||
- 代码注释说明"项目无独立 NOTIFICATION_SEND 权限点"
|
||||
- **影响**：无法单独控制"谁能发通知"vs"谁能发私信"
|
||||
|
||||
**建议**：新增 `NOTIFICATION_SEND` 权限点，或确认复用是设计意图
|
||||
|
||||
#### 设计亮点
|
||||
|
||||
- ✅ 渠道抽象优秀：`NotificationChannelSender` 接口 + 工厂函数，新增渠道只需实现接口
|
||||
- ✅ Mock 实现完善：SMS/Email/WeChat 均有 Mock 实现，开发环境零配置可用
|
||||
- ✅ 动态 import 第三方 SDK（阿里云/腾讯云/nodemailer），避免增加构建体积
|
||||
- ✅ 渠道选择逻辑清晰（dispatcher.ts 第 59-95 行）
|
||||
|
||||
---
|
||||
|
||||
## 三、messaging vs notifications 边界分析（重点）
|
||||
|
||||
### 3.1 现状对比
|
||||
|
||||
| 维度 | messaging 模块 | notifications 模块 |
|
||||
|------|---------------|-------------------|
|
||||
| **核心职责** | 站内私信 + 站内通知列表 | 多渠道通知分发 |
|
||||
| **管理的表** | `messages` + `messageNotifications` + `notificationPreferences` | 无独有表（借用 messaging 的表） |
|
||||
| **写入 messageNotifications** | ✅ 直接写（`createNotification`） | ✅ 通过 in-app 渠道写 |
|
||||
| **通知类型枚举** | `NotificationType = "message" \| "announcement" \| "homework" \| "grade"` | `NotificationPayload.type = "info" \| "warning" \| "error" \| "success"` |
|
||||
| **UI 组件** | message-list / message-detail / message-compose / notification-dropdown / notification-list | 无 UI 组件 |
|
||||
| **偏好管理** | ✅ `notification-preferences.ts` | ❌ 借用 messaging 的 |
|
||||
| **渠道支持** | 仅站内 | 站内 + SMS + Email + WeChat |
|
||||
|
||||
### 3.2 严重问题：双向依赖与职责重叠
|
||||
|
||||
#### 问题 1：notifications 反向依赖 messaging
|
||||
|
||||
```
|
||||
notifications/data-access.ts
|
||||
→ import { getNotificationPreferences } from "@/modules/messaging/notification-preferences"
|
||||
→ import type { NotificationPreferences } from "@/modules/messaging/types"
|
||||
|
||||
notifications/channels/in-app-channel.ts
|
||||
→ import { createNotification } from "@/modules/messaging/data-access"
|
||||
```
|
||||
|
||||
notifications 模块不拥有任何数据，全部依赖 messaging 模块。这违背了"模块应拥有自己的数据"原则。
|
||||
|
||||
#### 问题 2：messaging 绕过 notifications 直接写通知
|
||||
|
||||
`messaging/actions.ts` 第 66-72 行：
|
||||
|
||||
```typescript
|
||||
// Notify the receiver about the new message
|
||||
await createNotification({
|
||||
userId: input.receiverId,
|
||||
type: "message",
|
||||
title: input.subject ? `New message: ${input.subject}` : "New message",
|
||||
content: input.content.slice(0, 200),
|
||||
link: `/messages/${id}`,
|
||||
})
|
||||
```
|
||||
|
||||
这直接调用 `messaging/data-access.ts` 的 `createNotification`，**完全绕过 notifications 模块的 dispatcher**，导致：
|
||||
- 用户设置的 SMS/Email 偏好被忽略
|
||||
- 新消息不会触发邮件/短信提醒
|
||||
- notifications 模块的多渠道能力形同虚设
|
||||
|
||||
#### 问题 3：类型系统不一致
|
||||
|
||||
- `messaging/types.ts` 第 23 行：`NotificationType = "message" | "announcement" | "homework" | "grade"`（按业务类别）
|
||||
- `notifications/types.ts` 第 20 行：`type: "info" | "warning" | "error" | "success"`（按严重级别）
|
||||
- `in-app-channel.ts` 第 49 行：`type: payload.type as "message" | "announcement" | "homework" | "grade"` — **强制类型转换，运行时可能写入非法值**
|
||||
|
||||
DB schema 中 `messageNotifications.type` 为 `varchar(128)`，虽然不会报错，但语义混乱。
|
||||
|
||||
#### 问题 4：notification-preferences 归属不清
|
||||
|
||||
- `notificationPreferences` 表的 data-access 在 messaging 模块
|
||||
- 但 notifications 模块的 dispatcher 依赖此偏好决定渠道
|
||||
- settings 模块的 `notification-preferences-form.tsx` 调用 `messaging/actions.ts` 的 `updateNotificationPreferencesAction`
|
||||
- 三个模块都在操作同一份数据，职责归属不清
|
||||
|
||||
### 3.3 建议方案
|
||||
|
||||
**方案 A（推荐）：notifications 吞并 messaging 的通知部分**
|
||||
|
||||
1. 将 `messageNotifications` 表和 `notificationPreferences` 表的所有权移交给 notifications 模块
|
||||
2. messaging 模块仅保留 `messages` 表（私信）
|
||||
3. messaging 的 `sendMessageAction` 改为调用 `notifications.sendNotification`
|
||||
4. messaging 的 UI 组件（notification-dropdown / notification-list）迁移到 notifications 模块
|
||||
5. 统一 `NotificationType` 枚举，支持业务类别 + 严重级别两个维度
|
||||
|
||||
**方案 B：保持现状，明确依赖方向**
|
||||
|
||||
1. 在架构图中标注 notifications → messaging 的单向依赖
|
||||
2. messaging 不再直接调用 `createNotification`，改为调用 `notifications.sendNotification`
|
||||
3. 消除双向依赖，但 notifications 仍不拥有数据
|
||||
|
||||
---
|
||||
|
||||
## 四、dashboard 模块审查（重点）
|
||||
|
||||
### 4.1 严重问题：`data-access.ts` 直查 11 张跨模块表
|
||||
|
||||
`dashboard/data-access.ts` 的 `getAdminDashboardData` 函数直接查询以下表：
|
||||
|
||||
| 表名 | 所属模块 | 查询内容 |
|
||||
|------|---------|---------|
|
||||
| `sessions` | auth | 活跃会话数 |
|
||||
| `users` | users | 用户总数 + 最近注册用户 |
|
||||
| `usersToRoles` | users | 用户角色统计 |
|
||||
| `roles` | users | 角色名 |
|
||||
| `classes` | classes | 班级总数 |
|
||||
| `textbooks` | textbooks | 教材总数 |
|
||||
| `chapters` | textbooks | 章节总数 |
|
||||
| `questions` | questions | 题目总数 |
|
||||
| `exams` | exams | 考试总数（含 scope 过滤） |
|
||||
| `homeworkAssignments` | homework | 作业总数 + 已发布数 |
|
||||
| `homeworkSubmissions` | homework | 提交数 + 待批改数 |
|
||||
|
||||
**问题分析**：
|
||||
- 违反模块封装原则：dashboard 直接依赖其他模块的 DB schema
|
||||
- 任何模块的表结构变更都需要同步修改 dashboard
|
||||
- 无法复用其他模块的 scope 过滤逻辑（dashboard 自己实现了 exam/homework 的 scope 过滤，第 31-73 行）
|
||||
|
||||
### 4.2 学生/教师仪表盘的对比
|
||||
|
||||
**学生仪表盘**（`app/(dashboard)/student/dashboard/page.tsx`）：
|
||||
- ✅ 正确做法：调用 `classes/data-access` 的 `getStudentClasses` / `getStudentSchedule`
|
||||
- ✅ 调用 `homework/data-access` 的 `getStudentDashboardGrades` / `getStudentHomeworkAssignments`
|
||||
- ✅ 不直接查询任何表
|
||||
|
||||
**教师仪表盘**（`app/(dashboard)/teacher/dashboard/page.tsx`）：
|
||||
- ✅ 调用 `classes/data-access` 的 `getClassSchedule` / `getTeacherClasses`
|
||||
- ✅ 调用 `homework/data-access` 的 `getHomeworkAssignments` / `getHomeworkSubmissions` / `getTeacherGradeTrends`
|
||||
- ⚠️ 第 18-21 行直接查询 `users` 表获取教师姓名：`db.query.users.findFirst(...)` — 应使用 users 模块的 data-access
|
||||
|
||||
### 4.3 建议方案
|
||||
|
||||
**方案 A（理想）：聚合 API 模式**
|
||||
|
||||
为每个模块添加 `getModuleStats(scope?)` 函数，dashboard 聚合调用：
|
||||
```typescript
|
||||
const [userStats, classStats, textbookStats, ...] = await Promise.all([
|
||||
getUsersStats(scope),
|
||||
getClassStats(scope),
|
||||
getTextbookStats(),
|
||||
...
|
||||
])
|
||||
```
|
||||
|
||||
**方案 B（务实）：接受 dashboard 作为跨模块聚合层**
|
||||
|
||||
- 在架构图中明确标注 dashboard 对所有业务模块的依赖
|
||||
- 将 scope 过滤逻辑下沉到各模块的 `getStats` 函数
|
||||
- 至少消除 dashboard 中重复实现的 exam/homework scope 过滤（第 31-73 行）
|
||||
|
||||
---
|
||||
|
||||
## 五、其他模块审查
|
||||
|
||||
### 5.1 messaging 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 245 | 9 个 Server Action（私信 + 通知 + 偏好） |
|
||||
| `data-access.ts` | 252 | 私信 CRUD + 通知 CRUD + 收件人查询 |
|
||||
| `notification-preferences.ts` | 166 | 通知偏好 CRUD |
|
||||
| `schema.ts` | 17 | 私信发送校验 |
|
||||
| `types.ts` | 108 | 私信 + 通知 + 偏好类型 |
|
||||
|
||||
#### 问题
|
||||
|
||||
- ❌ **职责过多**：同时管理私信（messages）、站内通知（messageNotifications）、通知偏好（notificationPreferences）三类数据
|
||||
- ❌ **与 notifications 模块边界模糊**：详见第三节
|
||||
- ⚠️ `getRecipients` 函数（第 227-251 行）根据 dataScope 查询收件人，逻辑较复杂，可考虑下沉到 users 模块
|
||||
|
||||
### 5.2 parent 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `data-access.ts` | 234 | 子女关系 + 子女仪表盘数据聚合 |
|
||||
| `types.ts` | 57 | 类型定义 |
|
||||
| `components/` | 7 个 | 子女卡片 + 详情 + 仪表盘 |
|
||||
|
||||
#### 评价
|
||||
|
||||
- ✅ **职责单一**：仅负责家长视角的子女数据聚合与展示
|
||||
- ✅ **正确复用其他模块**：
|
||||
- 调用 `classes/data-access` 的 `getStudentClasses` / `getStudentSchedule`
|
||||
- 调用 `homework/data-access` 的 `getStudentDashboardGrades` / `getStudentHomeworkAssignments`
|
||||
- 调用 `grades/data-access` 的 `getStudentGradeSummary`
|
||||
- ✅ 不直接查询业务表（仅查询 `parentStudentRelations` 自有表 + `users`/`classes`/`classEnrollments`/`grades` 用于基本信息）
|
||||
- ⚠️ `getChildBasicInfo` 第 74-105 行多次串行查询（grade → class），可优化为 join
|
||||
|
||||
### 5.3 settings 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `actions.ts` | 205 | AI Provider CRUD + 测试连通性 |
|
||||
| `actions-password.ts` | 113 | 修改密码 |
|
||||
| `components/` | 8 个 | 通用设置 + AI 配置 + 密码 + 主题 + 通知偏好 |
|
||||
|
||||
#### 问题：职责混杂但可接受
|
||||
|
||||
settings 模块混合了 5 类职责：
|
||||
1. AI Provider 管理（`actions.ts` + `ai-provider-settings-card.tsx`）
|
||||
2. 密码修改（`actions-password.ts` + `password-change-form.tsx`）
|
||||
3. 个人资料（`profile-settings-form.tsx`）
|
||||
4. 主题偏好（`theme-preferences-card.tsx`）
|
||||
5. 通知偏好表单（`notification-preferences-form.tsx` — **调用 messaging 模块的 Action**）
|
||||
|
||||
**评价**：
|
||||
- ⚠️ AI Provider 管理与"用户设置"语义距离较远，可考虑独立为 `ai-config` 模块
|
||||
- ⚠️ `notification-preferences-form.tsx` 第 14 行 import `updateNotificationPreferencesAction` from `@/modules/messaging/actions` — 跨模块 UI 依赖
|
||||
- ✅ 密码修改有速率限制（`actions-password.ts` 第 33-37 行）
|
||||
- ✅ AI Provider 操作有 `AI_CONFIGURE` 权限校验
|
||||
- ✅ 密码修改仅要求 `requireAuth()`（自助操作），符合最小权限原则
|
||||
- ⚠️ 无 `data-access.ts` 文件，`actions.ts` 直接使用 `db` — 建议抽取 data-access 层
|
||||
|
||||
### 5.4 files 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 行数 | 职责 |
|
||||
|------|------|------|
|
||||
| `data-access.ts` | 267 | 文件附件 CRUD + 批量删除 + 统计 |
|
||||
| `types.ts` | - | 类型定义 |
|
||||
| `components/` | 6 个 | 上传 + 列表 + 预览 + 管理 |
|
||||
|
||||
#### 评价
|
||||
|
||||
- ✅ **职责单一**：仅管理 `fileAttachments` 表
|
||||
- ✅ 不跨模块查询
|
||||
- ✅ 批量删除有容错处理（第 152-177 行，失败时回退到逐条删除）
|
||||
- ⚠️ 所有函数都用 try-catch 吞掉错误返回空数组/null，可能掩盖真实问题
|
||||
- ⚠️ 无 actions.ts 文件 — 文件上传通过 `app/api/upload/route.ts` 和 `app/api/files/[id]/route.ts` 实现，data-access 被路由直接调用
|
||||
|
||||
### 5.5 auth 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `components/auth-layout.tsx` | 认证页面布局 |
|
||||
| `components/login-form.tsx` | 登录表单 |
|
||||
| `components/register-form.tsx` | 注册表单 |
|
||||
|
||||
#### 评价
|
||||
|
||||
- ✅ **纯 UI 模块**：无 data-access / actions / types 文件
|
||||
- ✅ 认证逻辑由 NextAuth + `shared/lib/auth-guard` 统一处理
|
||||
- ✅ 职责清晰
|
||||
|
||||
### 5.6 layout 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `components/app-sidebar.tsx` | 侧边栏（根据权限渲染导航） |
|
||||
| `components/sidebar-provider.tsx` | 侧边栏状态 Context |
|
||||
| `components/site-header.tsx` | 顶部导航（含通知下拉） |
|
||||
| `config/navigation.ts` | 导航配置（4 个角色） |
|
||||
|
||||
#### navigation.ts 幽灵路由审查
|
||||
|
||||
**结论：✅ 无幽灵路由**（007 报告中提到的 13 个幽灵路由已全部修复）
|
||||
|
||||
逐一核对导航配置中的所有 href 与 `src/app/` 下的实际页面：
|
||||
|
||||
| 角色 | 导航项数 | 全部存在 | 备注 |
|
||||
|------|---------|---------|------|
|
||||
| admin | 19 | ✅ | 包括子菜单项 |
|
||||
| teacher | 22 | ✅ | 包括子菜单项 |
|
||||
| student | 12 | ✅ | 包括子菜单项 |
|
||||
| parent | 5 | ✅ | 包括子菜单项 |
|
||||
|
||||
#### 存在但未纳入导航的页面
|
||||
|
||||
| 路由 | 说明 | 建议 |
|
||||
|------|------|------|
|
||||
| `/admin/attendance` | 管理员考勤页面 | 如需管理员查看全校考勤，应加入 admin 导航 |
|
||||
| `/admin/files` | 管理员文件管理 | 应加入 admin 导航 |
|
||||
| `/parent/children/[studentId]` | 子女详情页 | 通过仪表盘卡片跳转，可不加入导航 |
|
||||
| `/settings/security` | 安全设置子页 | 通过 settings 页 Tab 切换，无需独立导航 |
|
||||
| `/profile` | 个人主页 | 通过 header 头像菜单跳转，无需独立导航 |
|
||||
|
||||
#### 其他发现
|
||||
|
||||
- ✅ `app-sidebar.tsx` 第 36-43 行根据权限动态选择角色导航配置，符合 RBAC
|
||||
- ⚠️ 第 39 行判断学生逻辑：`permissions.includes(Permissions.HOMEWORK_SUBMIT) && !permissions.includes(Permissions.EXAM_CREATE)` — 用权限反推角色，不够直观，建议改用 `hasRole("student")`
|
||||
|
||||
### 5.7 student 模块
|
||||
|
||||
#### 模块结构
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `components/student-courses-view.tsx` | 学生课程视图 |
|
||||
| `components/student-schedule-filters.tsx` | 课表筛选器 |
|
||||
| `components/student-schedule-view.tsx` | 学生课表视图 |
|
||||
|
||||
#### 评价
|
||||
|
||||
- ✅ **纯 UI 模块**：无 data-access / actions / types
|
||||
- ✅ 数据由 `app/(dashboard)/student/learning/courses/page.tsx` 和 `app/(dashboard)/student/schedule/page.tsx` 通过 classes 模块的 data-access 获取
|
||||
- ⚠️ 与 classes 模块的 `schedule-view.tsx` / `schedule-filters.tsx` 可能存在功能重叠，建议核查
|
||||
|
||||
---
|
||||
|
||||
## 六、跨模块依赖关系图
|
||||
|
||||
```
|
||||
dashboard ──直查──> users, classes, textbooks, questions, exams, homework (11 张表)
|
||||
parent ──调用──> classes, homework, grades (data-access)
|
||||
diagnostic ──直查──> examSubmissions, submissionAnswers, questionsToKnowledgePoints, classes
|
||||
notifications ──依赖──> messaging (偏好 + in-app 渠道)
|
||||
messaging ──绕过──> notifications (直接写 messageNotifications)
|
||||
proctoring ──直查──> exams, examSubmissions, users
|
||||
settings ──调用──> messaging (通知偏好 Action)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、修复优先级
|
||||
|
||||
### P0（严重，应立即修复）
|
||||
|
||||
| 序号 | 问题 | 模块 | 工作量 | 影响 |
|
||||
|------|------|------|--------|------|
|
||||
| 1 | messaging 绕过 notifications 直接写通知 | messaging | 小 | 用户通知偏好失效，多渠道通知无效 |
|
||||
| 2 | proctoring/exam-mode-config.tsx 未集成 | proctoring | 小 | 监考功能无法启用，组件为死代码 |
|
||||
| 3 | proctoring 事件上报双通道重复 | proctoring | 小 | 代码重复，维护成本 |
|
||||
| 4 | notifications 反向依赖 messaging | notifications | 中 | 架构耦合，难以独立演进 |
|
||||
|
||||
### P1（中等问题，下个迭代修复）
|
||||
|
||||
| 序号 | 问题 | 模块 | 工作量 |
|
||||
|------|------|------|--------|
|
||||
| 5 | dashboard 直查 11 张跨模块表 | dashboard | 大 |
|
||||
| 6 | diagnostic 跨模块直查 4 张表 | diagnostic | 中 |
|
||||
| 7 | notifications 无 notification_logs 表 | notifications | 中 |
|
||||
| 8 | sendClassNotificationAction 直查 classes 表 | notifications | 小 |
|
||||
| 9 | elective 两个 data-access 文件代码重复 | elective | 小 |
|
||||
| 10 | settings/notification-preferences-form 跨模块依赖 | settings | 小 |
|
||||
|
||||
### P2（轻微问题，机会修复）
|
||||
|
||||
| 序号 | 问题 | 模块 |
|
||||
|------|------|------|
|
||||
| 11 | diagnostic/data-access-reports.ts 有未使用代码 | diagnostic |
|
||||
| 12 | diagnostic 班级报告 studentId 字段复用 | diagnostic |
|
||||
| 13 | elective runLottery 使用 Math.random | elective |
|
||||
| 14 | teacher dashboard 直查 users 表 | dashboard |
|
||||
| 15 | files 模块 try-catch 吞错误 | files |
|
||||
| 16 | layout 用权限反推角色 | layout |
|
||||
|
||||
---
|
||||
|
||||
## 八、总结
|
||||
|
||||
### 新增模块质量
|
||||
|
||||
- **elective**：✅ 质量较好，拆分合理但有代码重复
|
||||
- **proctoring**：⚠️ 有死代码（exam-mode-config 未集成）和重复实现（双通道上报）
|
||||
- **diagnostic**：✅ 与 grades 无重叠，但跨模块耦合较重
|
||||
- **notifications**：⚠️ 渠道抽象优秀，但与 messaging 边界模糊、反向依赖
|
||||
|
||||
### 重点问题回答
|
||||
|
||||
1. **elective 拆分为 3 个 data-access 文件是否合理？**
|
||||
合理，但需消除 `data-access.ts` 与 `data-access-selections.ts` 之间的代码重复
|
||||
|
||||
2. **proctoring 模块职责是否清晰？**
|
||||
基本清晰，但 `exam-mode-config.tsx` 应属于 exams 模块或集成到考试表单
|
||||
|
||||
3. **diagnostic 与 grades 是否有职责重叠？**
|
||||
无重叠。grades 管分数记录，diagnostic 管知识点掌握度，数据来源和维度均不同
|
||||
|
||||
4. **notifications 与 messaging 边界是否清晰？**
|
||||
不清晰。存在双向依赖、类型不一致、职责重叠三个问题，建议按方案 A 合并
|
||||
|
||||
5. **dashboard 是否直查其他模块的表？**
|
||||
是。`getAdminDashboardData` 直查 11 张跨模块表，是本次审查最严重的封装违规
|
||||
|
||||
6. **settings 是否混入太多职责？**
|
||||
混合了 5 类职责，但作为"设置"聚合点尚可接受。AI Provider 管理可考虑独立
|
||||
|
||||
7. **navigation.ts 是否有幽灵路由？**
|
||||
无。007 报告中的 13 个幽灵路由已全部修复
|
||||
196
docs/architecture/audit/shared-audit.md
Normal file
196
docs/architecture/audit/shared-audit.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# Shared 基础设施层审查报告
|
||||
|
||||
> 审查日期：2026-06-17
|
||||
> 审查范围：`src/shared/`（db、lib、hooks、components、types）+ `src/auth.ts` + `src/proxy.ts`
|
||||
> 审查依据：职责单一性、函数复杂度、模块间耦合、架构文档完整性
|
||||
|
||||
## 概览
|
||||
|
||||
- 文件总数：69（不含测试文件）
|
||||
- `db/`：3
|
||||
- `lib/`：13
|
||||
- `hooks/`：7
|
||||
- `components/ui/`：34
|
||||
- `components/a11y/`：4
|
||||
- `components/`（顶层）：4
|
||||
- `types/`：2
|
||||
- `src/auth.ts`、`src/proxy.ts`：2
|
||||
- 发现问题数：15
|
||||
- 严重程度分布：高 3 / 中 9 / 低 3
|
||||
|
||||
---
|
||||
|
||||
## 职责单一性问题
|
||||
|
||||
### 1. `src/shared/db/schema.ts`
|
||||
|
||||
- **问题**：单个文件包含 54 张表定义，共 1111 行，**超过项目规则中"任何文件不超过 1000 行"的硬性上限**。文件涵盖用户、认证、题库、教学、学校、班级、考试、作业、AI、公告、审计、成绩、文件、课程计划、消息、考勤、排课、选课、监考、学情诊断等十余个业务域。此外分节编号混乱：section 12（Parent-Student Relations，行 958）出现在 section 14b（Notification Preferences，行 934）之后，P2 段落与主编号交错。
|
||||
- **严重程度**：高
|
||||
- **建议**：按业务域拆分为多个 schema 文件（如 `schema/auth.ts`、`schema/academic.ts`、`schema/exam.ts`、`schema/audit.ts` 等），通过 `schema/index.ts` 聚合导出。同时修正分节编号。
|
||||
|
||||
### 2. `src/auth.ts`
|
||||
|
||||
- **问题**：293 行，混合了多种职责：
|
||||
1. NextAuth 配置（providers、callbacks、events）
|
||||
2. 密码安全 DB 操作（`getOrCreatePasswordSecurity`、`recordFailedLogin`、`resetFailedLogin`，行 56-130）——这些是数据访问层逻辑，不应内联在认证配置中
|
||||
3. 角色规范化工具（`normalizeRole`、`resolvePrimaryRole`，行 13-27）
|
||||
4. bcrypt 哈希规范化（`normalizeBcryptHash`，行 29-33）
|
||||
5. IP 解析（`resolveClientIp`，行 39-51）
|
||||
6. `authorize` 回调内联了限流、锁定检查、密码比对、日志记录全流程（86 行）
|
||||
- **严重程度**：高
|
||||
- **建议**：将密码安全 DB 操作迁移到 `shared/lib/password-security-service.ts`（与纯函数的 `password-policy.ts` 区分）；角色规范化迁移到 `shared/lib/permissions.ts` 或新建 `shared/lib/role-utils.ts`；`resolveClientIp` 迁移到 `shared/lib/http-utils.ts`（与三个 logger 共用）。
|
||||
|
||||
### 3. `src/shared/lib/ai.ts`
|
||||
|
||||
- **问题**：218 行，混合了 5 类职责：
|
||||
1. 请求负载解析与校验（`parseAiChatPayload`，行 70-96）
|
||||
2. API Key 加密/解密（`encryptAiApiKey`/`decryptAiApiKey`，行 104-124）
|
||||
3. Provider 配置 DB 查询（`getAiProviderConfig`，行 126-179）
|
||||
4. AI 客户端创建与调用（`getAiClient`、`createAiChatCompletion`、`testAiProviderConfig`、`testAiProviderById`）
|
||||
5. 错误格式化（`getAiErrorMessage`）
|
||||
|
||||
其中加密/解密与 Provider 配置查询属于数据层，与 AI 调用本身是不同关注点。
|
||||
- **严重程度**：中
|
||||
- **建议**：将加密/解密拆到 `shared/lib/crypto.ts`（通用加密工具）；将 Provider 配置查询拆到 `shared/lib/ai-provider-repo.ts`（数据访问）。`ai.ts` 保留负载解析与 AI 调用编排。
|
||||
|
||||
### 4. `src/shared/components/onboarding-gate.tsx`
|
||||
|
||||
- **问题**：312 行组件，混合了：
|
||||
1. 多步表单 UI
|
||||
2. 角色推断业务逻辑（行 90-94）：通过权限反推角色（`isAdmin`/`isTeacher`/`isStudent`/`isParent`），逻辑脆弱且未使用 `usePermission().hasRole()`
|
||||
3. 硬编码教学学科列表（`TEACHER_SUBJECTS`，行 20）——业务数据固化在 shared 基础设施
|
||||
4. 直接 `fetch("/api/onboarding/status")` 和 `fetch("/api/onboarding/complete")`——耦合特定 API 路由
|
||||
- **严重程度**：中
|
||||
- **建议**：角色判断改用 `usePermission().hasRole()` 或 session 的 `role` 字段；学科列表迁移到 modules 层配置或 DB；API 调用通过 Server Action 封装。组件本身可考虑按步骤拆分子组件。
|
||||
|
||||
### 5. `src/shared/components/global-search.tsx`
|
||||
|
||||
- **问题**：221 行组件，混合了：
|
||||
1. 搜索 UI 与下拉渲染
|
||||
2. 硬编码业务类型（`ResultType = "question" | "textbook" | "exam" | "announcement"`，行 12）与图标/标签映射（行 30-42）——业务知识泄漏到 shared 层
|
||||
3. 直接 `fetch("/api/search?...")`——耦合特定 API 路由与查询协议
|
||||
4. 快捷键、点击外部、键盘导航等交互逻辑内联
|
||||
- **严重程度**：中
|
||||
- **建议**：搜索结果类型与图标映射应由 API 返回或从 modules 层注入；API 调用抽取为独立 hook（`useGlobalSearch`）；交互逻辑可拆为 `useSearchKeyboard` 等。
|
||||
|
||||
### 6. `src/proxy.ts`
|
||||
|
||||
- **问题**：75 行，硬编码了路由-权限映射（`ROUTE_PERMISSIONS`、`API_PERMISSIONS`，行 8-19），使用原始字符串如 `"school:manage"`、`"exam:read"`，**未复用 `Permissions` 常量**，违反项目规则"前端组件禁止硬编码 role/权限"的精神。`resolveDefaultPath`（行 21-27）将角色到默认路径的业务映射硬编码在代理中。
|
||||
- **严重程度**：中
|
||||
- **建议**：权限字符串改用 `Permissions.SCHOOL_MANAGE` 等常量；路由权限映射迁移到 `shared/lib/route-permissions.ts` 配置文件；角色-路径映射迁移到 modules 层或路由配置。
|
||||
|
||||
### 7. `src/shared/lib/a11y.ts`
|
||||
|
||||
- **问题**：`useA11yId`（行 7-10）是一个 React Hook，但放置在 `lib/` 目录而非 `hooks/` 目录。项目约定 `hooks/` 存放所有自定义 Hook，`lib/` 存放纯工具函数。该文件其余函数（`mergeA11yProps`、`describeInput`、`loadingAria`）是纯函数，放置正确。
|
||||
- **严重程度**：低
|
||||
- **建议**：将 `useA11yId` 迁移到 `shared/hooks/use-a11y-id.ts`，`a11y.ts` 保留纯函数。
|
||||
|
||||
---
|
||||
|
||||
## 过耦合函数
|
||||
|
||||
### 1. `resolveDataScope` @ `src/shared/lib/auth-guard.ts:64-130`
|
||||
|
||||
- **行数**：67
|
||||
- **参数数**：2（`userId: string`, `roleNames: string[]`）
|
||||
- **问题**：单个函数内根据角色分支查询 4 张不同的表（`grades`、`classes`、`classSubjectTeachers`、`parentStudentRelations`），将权限范围解析与数据访问混合。每个角色分支的查询逻辑独立，新增角色需修改此函数，违反开闭原则。
|
||||
- **建议**：将各角色的数据范围查询拆为独立函数（如 `resolveTeacherScope`、`resolveParentScope`），或迁移到各模块的 data-access 层，`resolveDataScope` 仅做分发。
|
||||
|
||||
### 2. `getAiProviderConfig` @ `src/shared/lib/ai.ts:126-179`
|
||||
|
||||
- **行数**：53
|
||||
- **参数数**：1（`providerId?: string`）
|
||||
- **问题**：函数内有三段几乎相同的 DB 查询分支（按 providerId、按 isDefault、fallback），每段都 select 相同的字段、解密 apiKey、返回相同结构，存在明显代码重复。
|
||||
- **建议**：提取公共 `mapProviderRow(row)` 函数，三个分支简化为查询条件不同。或合并为单查询带 OR 条件 + 排序优先级。
|
||||
|
||||
### 3. `authorize`（NextAuth Credentials 回调）@ `src/auth.ts:143-229`
|
||||
|
||||
- **行数**：86
|
||||
- **参数数**：1（`credentials`）
|
||||
- **问题**：单函数内串联了：邮箱密码校验 → 速率限制 → DB 用户查询 → 账户锁定检查 → 密码比对 → 失败计数 → 成功重置 → 角色查询 → 返回。流程长且混合了限流、安全策略、认证、日志多个关注点。内部还使用 `Promise.all` + 动态 `import`（行 165-168）加载 `@/shared/db` 和 schema，写法不寻常。
|
||||
- **建议**：将流程拆分为 `checkRateLimit`、`checkAccountLockout`、`verifyPassword`、`loadUserRoles` 等步骤函数，`authorize` 仅编排。动态 import 改为静态 import。
|
||||
|
||||
### 4. `OnboardingGate` 组件 @ `src/shared/components/onboarding-gate.tsx:27-312`
|
||||
|
||||
- **行数**：285（组件函数体）
|
||||
- **参数数**：0（无 props，内部消费 session）
|
||||
- **问题**：单组件承担了状态检查、4 步表单、角色推断、API 提交、路由跳转。组件内 9 个 `useState`，3 个 `useEffect`，逻辑密集。
|
||||
- **建议**：按步骤拆分为 `OnboardingRoleStep`、`OnboardingProfileStep`、`OnboardingRoleDetailStep`、`OnboardingCompleteStep` 子组件；提取 `useOnboarding` hook 封装状态与提交逻辑。
|
||||
|
||||
### 5. `GlobalSearch` 组件 @ `src/shared/components/global-search.tsx:49-221`
|
||||
|
||||
- **行数**：172（组件函数体）
|
||||
- **参数数**：2（`className?`, `placeholder?`）
|
||||
- **问题**：单组件承担了输入控制、防抖搜索、快捷键监听、点击外部关闭、键盘导航、结果渲染。6 个 `useState`，3 个 `useEffect`。
|
||||
- **建议**：提取 `useGlobalSearch(query)` hook 封装搜索请求与状态；提取 `useSearchKeyboard` 封装快捷键与导航。组件仅负责渲染。
|
||||
|
||||
---
|
||||
|
||||
## 模块间依赖问题
|
||||
|
||||
### 1. shared 层与 `@/auth` 的循环依赖
|
||||
|
||||
- **涉及模块**：`shared/lib/{audit-logger, change-logger, auth-guard}` → `@/auth` → `shared/lib/{login-logger, permissions, password-policy, rate-limit}` + `shared/db`
|
||||
- **问题类型**：循环依赖
|
||||
- **问题详情**：
|
||||
- `shared/lib/audit-logger.ts`（行 7）`import { auth } from "@/auth"`
|
||||
- `shared/lib/change-logger.ts`（行 6）`import { auth } from "@/auth"`
|
||||
- `shared/lib/auth-guard.ts`（行 1）`import { auth } from "@/auth"`
|
||||
- 而 `src/auth.ts` 反向依赖 `shared/lib/permissions`、`shared/lib/login-logger`、`shared/lib/password-policy`、`shared/lib/rate-limit`、`shared/db`
|
||||
|
||||
这构成了 `shared/lib/*` → `auth` → `shared/lib/*` 的循环。虽然 NextAuth 的 `auth()` 函数是运行时调用而非模块级副作用，目前不会导致运行时错误，但架构上 shared 基础设施层不应反向依赖业务层的认证入口。
|
||||
- **建议**：将 `auth()` 的 session 获取抽象为接口或通过参数注入。logger 函数改为接收 `session` 参数（由调用方传入），而非内部调用 `auth()`。或创建 `shared/lib/session.ts` 封装 session 获取，`auth.ts` 和 logger 都依赖它，打破循环。
|
||||
|
||||
### 2. shared 层对根模块 `@/auth` 的反向依赖
|
||||
|
||||
- **涉及模块**：`shared/lib/*` → `@/auth`（根模块）
|
||||
- **问题类型**：反向依赖
|
||||
- **问题详情**：`src/auth.ts` 位于项目根目录，属于应用层（非 shared 层）。shared 层应是被依赖方，不应依赖应用层模块。三个文件（audit-logger、change-logger、auth-guard）直接 import `@/auth`，使 shared 层无法独立测试或复用。
|
||||
- **建议**：同上，通过依赖注入或提取 `shared/lib/session.ts` 解耦。
|
||||
|
||||
### 3. 三个 logger 重复实现 IP/Header 提取
|
||||
|
||||
- **涉及模块**：`shared/lib/audit-logger`、`shared/lib/change-logger`、`shared/lib/login-logger`、`src/auth.ts`
|
||||
- **问题类型**：过度耦合（DRY 违反）
|
||||
- **问题详情**：三个 logger 各自重复实现相同的 IP/User-Agent 提取逻辑：
|
||||
- `audit-logger.ts`（行 27-32）：`headerList.get("x-forwarded-for") ?? headerList.get("x-real-ip") ?? "unknown"`
|
||||
- `change-logger.ts`（行 27-31）：相同逻辑
|
||||
- `login-logger.ts`（行 26-31）：相同逻辑
|
||||
- `auth.ts`（行 39-51）：`resolveClientIp` 也是类似逻辑（取 `x-forwarded-for` 第一段）
|
||||
|
||||
四处实现略有差异（auth.ts 取逗号分隔第一段，其他取全值），存在不一致风险。
|
||||
- **建议**：提取 `shared/lib/http-utils.ts`，导出 `getClientIp()` 和 `getUserAgent()` 统一复用。
|
||||
|
||||
---
|
||||
|
||||
## 架构文档改进建议
|
||||
|
||||
1. **补充依赖关系图**：当前 004 文档以函数/常量为粒度列举导出，但缺少模块间依赖方向的可视化图。建议在 005 JSON 中增加 `dependencyMatrix` 节点，记录 `shared/lib/* → @/auth`、`@/auth → shared/lib/*` 等依赖边，并在 004 Markdown 中用 Mermaid 图渲染。本次审查发现的循环依赖（shared ↔ auth）在当前文档中完全不可见。
|
||||
|
||||
2. **标注循环依赖与反向依赖**：004/005 文档应明确标注 `shared/lib/{audit-logger, change-logger, auth-guard}` 对 `@/auth` 的依赖，以及这与 `@/auth` 对 `shared/lib/*` 的依赖构成的循环。当前文档将 `auth` 模块与 `shared` 模块分别描述，未揭示二者双向依赖。
|
||||
|
||||
3. **修正 schema.ts 分节编号**：004 文档的"数据库表"章节按表名平铺列举，未反映 schema.ts 源文件中的分节结构。建议文档增加 schema.ts 分节映射表，并修正源文件中 section 12 出现在 section 14b 之后的编号混乱。
|
||||
|
||||
4. **增加 shared 层边界说明**：004 文档应明确 shared 层"不应依赖应用层模块（如 `@/auth`）"的架构约束，以及哪些文件属于 shared 层的对外公共 API。当前文档未说明 shared 与根模块（auth.ts、proxy.ts）的边界。
|
||||
|
||||
5. **补充函数复杂度标注**：005 JSON 中每个函数已有签名记录，但缺少行数与参数数量字段。建议增加 `"lines"` 和 `"paramCount"` 字段，便于自动识别过耦合函数（如本次发现的 `authorize` 86 行、`resolveDataScope` 67 行）。
|
||||
|
||||
6. **记录 proxy.ts 的路由权限映射**：004 文档未记录 `proxy.ts` 中的 `ROUTE_PERMISSIONS` 和 `API_PERMISSIONS` 硬编码映射，也未说明这些映射与 `Permissions` 常量的关系。建议在 005 JSON 的 `routes` 节点中补充代理层权限规则。
|
||||
|
||||
---
|
||||
|
||||
## 附：审查范围文件清单
|
||||
|
||||
| 目录 | 文件数 | 最大文件（行数） | 备注 |
|
||||
|------|--------|------------------|------|
|
||||
| `src/shared/db/` | 3 | schema.ts (1111) | **超过 1000 行硬性上限** |
|
||||
| `src/shared/lib/` | 13 | ai.ts (218) | |
|
||||
| `src/shared/hooks/` | 7 | use-aria-live.ts (88) | |
|
||||
| `src/shared/components/ui/` | 34 | chart.tsx (329) | 多为标准 shadcn/ui 组件 |
|
||||
| `src/shared/components/a11y/` | 4 | focus-trap.tsx (110) | |
|
||||
| `src/shared/components/`（顶层） | 4 | onboarding-gate.tsx (312) | |
|
||||
| `src/shared/types/` | 2 | permissions.ts (92) | |
|
||||
| `src/auth.ts` | 1 | auth.ts (293) | |
|
||||
| `src/proxy.ts` | 1 | proxy.ts (75) | |
|
||||
|
||||
> 注：`components/ui/` 下 34 个文件多为 shadcn/ui 标准生成组件（基于 Radix UI），职责单一，未发现结构性问题，故未逐一列入问题清单。`chart.tsx`（329 行）为标准 shadcn chart 组件，行数较高但属框架约定，可接受。
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2025-12-23 教师仪表盘的实现细节（含 Hydration 修复）。
|
||||
> 当前实现已演进，最新架构与组件清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 dashboard 模块章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 教师仪表盘实现与 Hydration 修复记录
|
||||
|
||||
**日期**: 2025-12-23
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2025-12-23（更新 2026-01-13）教材模块的实现细节。
|
||||
> 当前实现已演进，最新架构与组件清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 textbooks 模块章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# Textbooks Module Implementation Details
|
||||
|
||||
**Date**: 2025-12-23
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2025-12-23 题库模块的实现细节。
|
||||
> 当前实现已演进，最新架构与组件清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 questions 模块章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 题库模块实现
|
||||
|
||||
## 1. 概述
|
||||
|
||||
@@ -1,7 +1,14 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是考试模块的实现设计（含与作业模块合并的调整说明）。
|
||||
> 当前实现已演进，最新架构与组件清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 exams 模块章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 考试模块实现设计文档
|
||||
|
||||
## 1. 概述
|
||||
考试模块用于教师侧的“试卷制作与管理”，覆盖创建考试、组卷（支持嵌套分组）、发布/归档等流程。
|
||||
考试模块用于教师侧的"试卷制作与管理"，覆盖创建考试、组卷（支持嵌套分组）、发布/归档等流程。
|
||||
|
||||
**说明（合并调整）**：与“作业（Homework）”模块合并后，考试模块不再提供“阅卷/评分（grading）”与提交流转；教师批改统一在 Homework 的 submissions 中完成。
|
||||
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2025-12-31 作业模块的实现设计。
|
||||
> 当前实现已演进，最新架构与组件清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 homework 模块章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 作业模块实现设计文档（Homework Module）
|
||||
|
||||
**日期**: 2025-12-31
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档记录的是 2026-03-03 教师端页面实现的分析。
|
||||
> 当前路由与页面已大幅扩展，最新路由清单详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 routes.teacher 章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 教师端页面实现分析文档
|
||||
|
||||
**日期**: 2026-03-03
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档是 2026-03-03 的功能实现对比文档（已实现 vs 规划）。
|
||||
> 当前已由 [007 差距审计报告](../architecture/007_gap_audit_report.md) 取代——007 基于 004/005 架构图全量扫描，覆盖更完整、数据更新。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 功能实现对比文档（已实现 vs 规划）
|
||||
|
||||
**日期**: 2026-03-03
|
||||
|
||||
@@ -1,3 +1,10 @@
|
||||
> ⚠️ **已归档文档**
|
||||
> 本文档是 2026-03-18 的项目全量测试方案与执行反馈。
|
||||
> 当前测试体系已演进（Vitest 单元/集成 + Playwright E2E + CI 安全扫描），最新 CI 配置详见 [004 架构影响地图](../architecture/004_architecture_impact_map.md) 的 devops 章节。
|
||||
> 保留用于历史参考，不再维护。
|
||||
|
||||
---
|
||||
|
||||
# 项目全量测试方案与执行反馈
|
||||
|
||||
**日期**: 2026-03-18
|
||||
|
||||
@@ -2,6 +2,54 @@
|
||||
|
||||
## 2026-06-17
|
||||
|
||||
### 架构全面审查与文档重构
|
||||
|
||||
#### 问题背景
|
||||
用户反馈:架构文档阅读后仍无法理解各模块、函数关系,说明文档质量不足或代码耦合度过高。006/007 及其他文档长期未更新。
|
||||
|
||||
#### 完成工作
|
||||
|
||||
##### 1. 全项目逐文件审查(4 份审查报告)
|
||||
- `docs/architecture/audit/shared-audit.md` - shared 基础设施层(69 文件,15 问题)
|
||||
- `docs/architecture/audit/core-business-audit.md` - 核心业务模块(exams/homework/questions/textbooks/grades)
|
||||
- `docs/architecture/audit/management-modules-audit.md` - 管理模块(school/classes/scheduling/attendance/users/audit/course-plans/announcements)
|
||||
- `docs/architecture/audit/new-and-other-modules-audit.md` - 新增模块和其他模块(elective/proctoring/diagnostic/notifications/dashboard/messaging/parent/settings/files/auth/layout/student)
|
||||
- `docs/architecture/audit/00_summary.md` - 汇总报告
|
||||
|
||||
##### 2. 发现的关键问题
|
||||
**P0 严重问题(6 项)**:
|
||||
1. `classes/data-access.ts` 2104 行,超硬上限 2.1 倍,混入 homework/scheduling/grades 逻辑
|
||||
2. `homework/data-access.ts` 1038 行,超硬上限,混入排名计算
|
||||
3. `shared/lib` ↔ `auth` 循环依赖
|
||||
4. `dashboard/data-access.ts` 直查 11 张跨模块表
|
||||
5. `messaging` 绕过 `notifications` 直接写通知
|
||||
6. `classSchedule` 表三处写入口(数据完整性风险)
|
||||
|
||||
**P1 较严重问题(6 项)**:
|
||||
- 跨模块直接 DB 查询普遍存在(classes 被 8+ 处直接查询)
|
||||
- actions 层混入数据访问逻辑
|
||||
- auth.ts 混合 5 类职责
|
||||
- users/import-export.ts 四重职责
|
||||
- proctoring/exam-mode-config.tsx 死代码
|
||||
- notifications 反向依赖 messaging
|
||||
|
||||
##### 3. 重写架构文档(5 份)
|
||||
- **004 架构影响地图**:从"罗列函数签名"重构为"图优先 + 结构化",含分层架构图、模块依赖关系图(标注合理/违规/循环依赖)、数据流向图、核心调用链路、26 个模块清单、P0/P1/P2 问题分级与解耦建议
|
||||
- **005 架构数据 JSON**:新增 architectureOverview、moduleDependencyGraph(25 节点 37 边)、knownIssues(12 问题)、dbTables(54 表按业务域分组)节点;补全 permissions(52→54)、apiRoutes(10→11)
|
||||
- **006 功能清单**:添加"当前实现状态"列,143 个功能项标注 ✅/⚠️/❌,P0 覆盖率 80%→92%
|
||||
- **007 差距审计报告**:v2→v3,总体完成度 P0 69%→84%,P2 路线图 8/14=57%,新增架构技术债章节
|
||||
- **001 项目概览**:更新为 6 角色/54 权限/26 模块/54 表,新增架构原则和项目状态章节
|
||||
|
||||
##### 4. 文档治理
|
||||
- 创建 `docs/README.md` 文档索引(架构/审查/专题/归档分类)
|
||||
- 11 个过时文档添加"已归档"标注(002×2/003/设计文档×8)
|
||||
- 所有文档保持活跃维护与归档分离
|
||||
|
||||
#### 验证
|
||||
- 待验证 lint + tsc
|
||||
|
||||
---
|
||||
|
||||
### P2 质量保障类实现（5 项全部完成）
|
||||
|
||||
#### 1. 屏幕阅读器兼容性增强（a11y）
|
||||
|
||||
Reference in New Issue
Block a user