NextEdu/docs/architecture/001_project_overview.md

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)