refactor: RBAC权限系统重构 + UI组件拆分 + 测试修复 + 架构文档
Some checks failed
CI / build-deploy (push) Has been cancelled
Some checks failed
CI / build-deploy (push) Has been cancelled
- RBAC: 新增30个权限点、DataScope行级权限、requirePermission守卫，所有57+ Server Action接入权限校验 - UI拆分: exam-form(1623行→11文件)、textbook-reader(744行→7文件)，均降至300行以内 - 测试: 新增5个单元测试文件(19用例)，修复4个集成测试文件(38用例全部通过) - 架构文档: 新增架构影响地图(004/005)、标准功能清单(006)、差距审计报告(007) - 项目规则: 架构图优先规则，改码必同步图 - 安全: rehype-sanitize净化、AES加密API Key、权限路由守卫 - 无障碍: skip-link、aria-label、prefers-reduced-motion - 性能: next/font优化、next/image、代码分割
This commit is contained in:
SpecialX
241
docs/architecture/001_project_overview.md
Normal file
241
docs/architecture/001_project_overview.md
Normal file
@@ -0,0 +1,241 @@
|
||||
# Next_Edu 项目架构分析
|
||||
|
||||
> 本文档基于源码逆向分析生成，未参考任何已有文档。
|
||||
|
||||
---
|
||||
|
||||
## 一、项目定位与目标
|
||||
|
||||
**Next_Edu** 是一个面向 K12 场景的**智慧教务管理系统**，旨在将传统学校的教务流程数字化、智能化。
|
||||
|
||||
核心目标：
|
||||
1. **多角色协同**：管理员、教师、学生、家长四种角色在同一平台协作，各角色有独立的仪表盘和功能入口
|
||||
2. **AI 赋能教学**：集成大语言模型（智谱/OpenAI/Gemini），支持 AI 自动生成试卷、AI 重写题目、AI 对话辅导
|
||||
3. **全流程闭环**：从教材管理 → 题库建设 → 试卷组卷 → 考试/作业发布 → 学生作答 → 教师批改 → 数据分析，覆盖教学评估全链路
|
||||
4. **知识体系结构化**：教材章节与知识点树形关联，知识点与题目双向链接，支撑精准教学
|
||||
|
||||
---
|
||||
|
||||
## 二、技术栈
|
||||
|
||||
| 层次 | 技术选型 | 版本 |
|
||||
|------|---------|------|
|
||||
| 框架 | Next.js (App Router) | 16 |
|
||||
| 语言 | TypeScript (strict) | 5 |
|
||||
| 前端 | React | 19 |
|
||||
| 样式 | Tailwind CSS + shadcn/ui | v4 |
|
||||
| 状态 | Zustand + nuqs (URL) + React Hook Form | — |
|
||||
| 数据库 | MySQL | — |
|
||||
| ORM | Drizzle ORM | 0.45 |
|
||||
| 认证 | NextAuth v5 (JWT strategy) | beta |
|
||||
| 校验 | Zod | 4 |
|
||||
| AI | OpenAI SDK (多 provider) | — |
|
||||
| 富文本 | TipTap | 3 |
|
||||
| 图表 | Recharts | 3 |
|
||||
| 测试 | Vitest + Playwright | — |
|
||||
| 部署 | Docker (standalone output) | — |
|
||||
|
||||
---
|
||||
|
||||
## 三、系统角色与权限模型
|
||||
|
||||
### 角色定义
|
||||
|
||||
| 角色 | 路由前缀 | 核心职责 |
|
||||
|------|---------|---------|
|
||||
| **Admin** | `/admin/*` | 学校管理、年级/班级/部门配置、用户管理、全局设置 |
|
||||
| **Teacher** | `/teacher/*` | 教材管理、题库建设、试卷组卷、作业发布与批改、班级管理 |
|
||||
| **Student** | `/student/*` | 课程学习、作业作答、教材阅读、课表查看 |
|
||||
| **Parent** | `/parent/*` | 子女学情查看、缴费、消息沟通 |
|
||||
|
||||
### 权限控制机制
|
||||
|
||||
```
|
||||
请求 → NextAuth Middleware (proxy.ts)
|
||||
→ 检查 session 是否存在 → 无则重定向 /login
|
||||
→ 解析 JWT 中的 role 字段
|
||||
→ 按路由前缀校验角色匹配
|
||||
→ 不匹配则重定向到角色首页
|
||||
```
|
||||
|
||||
- **角色解析**：`grade_head` 和 `teaching_head` 映射为 `teacher`；多角色用户取优先级 `admin > teacher > parent > student`
|
||||
- **用户-角色**：多对多关系（`users_to_roles` 表），支持一人多角色
|
||||
- **导航隔离**：`NAV_CONFIG` 按角色定义侧边栏菜单，不同角色看到完全不同的功能入口
|
||||
|
||||
---
|
||||
|
||||
## 四、数据模型
|
||||
|
||||
### 核心实体关系
|
||||
|
||||
```
|
||||
School ──1:N──→ Grade ──1:N──→ Class ──1:N──→ ClassEnrollment ←──N:1── User(student)
|
||||
│ │
|
||||
│ ├── ClassSubjectTeacher (班级-科目-教师)
|
||||
│ └── ClassSchedule (课表)
|
||||
│
|
||||
├── Department
|
||||
├── Classroom
|
||||
└── AcademicYear
|
||||
|
||||
User ──M:N──→ Role (RBAC)
|
||||
|
||||
Textbook ──1:N──→ Chapter (树形嵌套) ──1:N──→ KnowledgePoint (树形嵌套)
|
||||
│
|
||||
Question ──M:N──→ KnowledgePoint │
|
||||
│ │
|
||||
├── 支持类型: single_choice / multiple_choice │
|
||||
│ / text / judgment / composite │
|
||||
└── 支持无限嵌套 (parentId 自引用) │
|
||||
│
|
||||
Exam ──M:N──→ Question (exam_questions) │
|
||||
├── ExamSubmission ──1:N──→ SubmissionAnswer │
|
||||
└── structure (JSON 层级结构) │
|
||||
│
|
||||
HomeworkAssignment ──M:N──→ Question │
|
||||
├── sourceExamId → Exam (作业源自试卷) │
|
||||
├── HomeworkAssignmentTarget (指定学生) │
|
||||
└── HomeworkSubmission ──1:N──→ HomeworkAnswer │
|
||||
│
|
||||
AIProvider (zhipu / openai / gemini / custom) │
|
||||
└── apiKeyEncrypted (AES 加密存储) │
|
||||
```
|
||||
|
||||
### 数据库规模
|
||||
|
||||
- **20+ 张表**，覆盖用户认证、RBAC、学校管理、教学资源、考试系统、作业系统、AI 配置
|
||||
- **ID 策略**：CUID2（`@paralleldrive/cuid2`），128 位 varchar
|
||||
- **索引策略**：所有外键和查询字段均有索引，支持级联删除
|
||||
|
||||
---
|
||||
|
||||
## 五、架构设计
|
||||
|
||||
### 分层架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ App Router (src/app/) │
|
||||
│ ├── Route Groups: (auth) / (dashboard) │
|
||||
│ ├── Server Components (默认) │
|
||||
│ ├── loading.tsx (Suspense 边界) │
|
||||
│ └── error.tsx (错误边界) │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ Feature Modules (src/modules/) │
|
||||
│ ├── auth/ 认证模块 │
|
||||
│ ├── exams/ 考试模块 │
|
||||
│ ├── homework/ 作业模块 │
|
||||
│ ├── questions/ 题库模块 │
|
||||
│ ├── textbooks/ 教材模块 │
|
||||
│ ├── classes/ 班级模块 │
|
||||
│ ├── school/ 学校管理模块 │
|
||||
│ ├── dashboard/ 仪表盘模块 │
|
||||
│ ├── layout/ 布局与导航 │
|
||||
│ ├── settings/ 设置模块 │
|
||||
│ └── users/ 用户管理模块 │
|
||||
│ 每个模块: │
|
||||
│ ├── components/ UI 组件 │
|
||||
│ ├── hooks/ 自定义 Hook │
|
||||
│ ├── actions.ts Server Actions │
|
||||
│ ├── data-access.ts 数据访问层 │
|
||||
│ └── types.ts 类型定义 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ Shared (src/shared/) │
|
||||
│ ├── components/ui/ shadcn/ui 基础组件 (30+) │
|
||||
│ ├── hooks/ 通用 Hook │
|
||||
│ ├── lib/ 工具函数 │
|
||||
│ ├── db/ 数据库 (schema/relations) │
|
||||
│ └── types/ 公共类型 │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ API Routes (src/app/api/) │
|
||||
│ ├── auth/[...nextauth] NextAuth 端点 │
|
||||
│ ├── ai/chat AI 对话 │
|
||||
│ └── onboarding/* 用户引导 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
用户操作 → Client Component
|
||||
→ Server Action (actions.ts)
|
||||
→ 数据访问层 (data-access.ts)
|
||||
→ Drizzle ORM (db/index.ts)
|
||||
→ MySQL
|
||||
|
||||
Server Action 返回 → ActionState<T>
|
||||
→ { success, message, data?, errors? }
|
||||
→ Client 端 toast 反馈
|
||||
```
|
||||
|
||||
### AI 集成架构
|
||||
|
||||
```
|
||||
教师操作 → AI Provider 选择 (支持多 provider)
|
||||
→ API Key AES 加密存储 (ai_providers 表)
|
||||
→ Server Action 调用 AI Pipeline
|
||||
├── 试卷生成: 输入源文本 → AI 解析 → 结构化题目
|
||||
├── 题目重写: 输入原题 + 指令 → AI 重写 → 更新题目
|
||||
└── AI 对话: /api/ai/chat → 流式响应
|
||||
→ PQueue 并发控制 (最多 3 个后台任务)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 六、核心业务流程
|
||||
|
||||
### 1. 试卷组卷流程
|
||||
|
||||
```
|
||||
手动模式: 选择科目/年级 → 填写考试信息 → 创建草稿 → 进入试卷构建器 → 从题库选题
|
||||
AI 模式: 选择 AI Provider → 粘贴试卷源文本 → AI 解析生成 → 预览/编辑 → 确认创建
|
||||
```
|
||||
|
||||
### 2. 作业发布与批改流程
|
||||
|
||||
```
|
||||
教师: 从已有试卷创建作业 → 选择目标学生 → 设置截止时间 → 发布
|
||||
学生: 查看作业列表 → 作答 → 提交
|
||||
教师: 查看提交列表 → 批改评分 → 填写反馈
|
||||
```
|
||||
|
||||
### 3. 教材与知识体系流程
|
||||
|
||||
```
|
||||
教师: 创建教材 → 添加章节(树形) → 编写内容(Markdown/富文本)
|
||||
→ 从文本选中创建知识点 → 知识点自动关联章节
|
||||
→ 从知识点创建题目 → 题目关联知识点
|
||||
学生: 选择章节阅读 → 知识点高亮链接 → 查看知识图谱
|
||||
```
|
||||
|
||||
### 4. 用户注册与引导流程
|
||||
|
||||
```
|
||||
注册 → 默认 student 角色 → OnboardingGate 检查
|
||||
→ 未引导: 强制填写角色/学校/班级信息
|
||||
→ 已引导: 进入角色仪表盘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 七、部署与运维
|
||||
|
||||
- **构建模式**: `output: "standalone"` — 适配 Docker 容器化部署
|
||||
- **数据库迁移**: Drizzle Kit (`db:generate` / `db:migrate`)
|
||||
- **数据填充**: `db:seed` 脚本 + `@faker-js/faker`
|
||||
- **CI/CD**: `.gitea/workflows/ci.yml` — Gitea Actions
|
||||
- **测试**: 单元测试 (Vitest) + 集成测试 + E2E (Playwright)
|
||||
|
||||
---
|
||||
|
||||
## 八、项目规模统计
|
||||
|
||||
| 维度 | 数量 |
|
||||
|------|------|
|
||||
| 数据库表 | 20+ |
|
||||
| 业务模块 | 11 |
|
||||
| UI 基础组件 | 30+ |
|
||||
| 路由页面 | 30+ |
|
||||
| Server Actions | 50+ |
|
||||
| API 路由 | 4 |
|
||||
| 用户角色 | 4 (admin/teacher/student/parent) |
|
||||
Reference in New Issue
Block a user