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

docs: 全项目架构审查与文档体系重写

Browse Source 
- 全项目逐文件审查: 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
2026-06-17 21:51:32 +08:00
parent 6585e10c6f
commit f8dfd1dddd
23 changed files with 15183 additions and 4727 deletions
Download Patch File Download Diff File Expand all files Collapse all files

199
docs/architecture/001_project_overview.md
View File

@@ -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) | 功能差距审计与补齐路线图 |