NextEdu/docs/architecture/001_project_overview.md

Next_Edu 项目概览

本文档是项目的入口概览，基于源码与架构影响地图（004/005）维护。 详细模块/函数/路由/表结构请查阅 004 架构影响地图 与 005 架构数据。

---

一、项目定位与目标

Next_Edu 是一个面向 K12 场景的智慧教务管理系统，旨在将传统学校的教务流程数字化、智能化。

核心目标：

1. 多角色协同：6 种角色（管理员、教师、学生、家长、年级组长、教研组长）在同一平台协作，各角色有独立的仪表盘和功能入口
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/*	子女学情查看、成绩/考勤/课表、消息沟通
Grade Head (年级组长)	映射为 /teacher/*	年级管理、年级作业洞察、学情诊断
Teaching Head (教研组长)	映射为 /teacher/*	教研管理、学情诊断

权限控制机制

请求 → NextAuth Middleware (proxy.ts)
     → 检查 session 是否存在 → 无则重定向 /login
     → 解析 JWT 中的 role/permissions 字段
     → 按路由前缀校验角色与权限点匹配
     → 不匹配则重定向到角色首页

• 权限点：共 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 按角色定义侧边栏菜单，不同角色看到完全不同的功能入口

---

四、数据模型

核心实体关系

School ──1:N──→ Grade ──1:N──→ Class ──1:N──→ ClassEnrollment ←──N:1── User(student)
    │                           │
    │                           ├── ClassSubjectTeacher (班级-科目-教师)
    │                           ├── ClassSchedule (课表)
    │                           └── AttendanceRecords (考勤)
    │
    ├── Department
    ├── Classroom
    └── AcademicYear

User ──M:N──→ Role (RBAC) ──→ Permissions (54 个权限点)
User ──M:N──→ ParentStudentRelation (家长-子女)

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 层级结构)                       │
  └── 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 加密存储)                  │

数据库规模

• 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 过滤数据

分层架构

┌─────────────────────────────────────────────────┐
│  App Router (src/app/)                          │
│  ├── Route Groups: (auth) / (dashboard)         │
│  ├── Server Components (默认)                    │
│  ├── loading.tsx (Suspense 边界)                 │
│  └── error.tsx (错误边界)                        │
├─────────────────────────────────────────────────┤
│  Feature Modules (src/modules/) — 26 个模块      │
│  ├── auth/          认证模块                     │
│  ├── exams/         考试模块                     │
│  ├── homework/      作业模块                     │
│  ├── questions/     题库模块                     │
│  ├── textbooks/     教材模块                     │
│  ├── classes/       班级模块                     │
│  ├── school/        学校管理模块                 │
│  ├── dashboard/     仪表盘模块                   │
│  ├── layout/        布局与导航                   │
│  ├── settings/      设置模块                     │
│  ├── 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/             工具函数 (auth-guard/ai/   │
│  │                    excel/file-storage/        │
│  │                    rate-limit/password-policy)│
│  ├── db/              数据库 (schema/relations)  │
│  └── types/           公共类型 (permissions/     │
│                       action-state)              │
├─────────────────────────────────────────────────┤
│  API Routes (src/app/api/)                      │
│  ├── auth/[...nextauth]   NextAuth 端点          │
│  ├── ai/chat              AI 对话                │
│  ├── upload / files       文件上传与管理         │
│  ├── search               全局全文检索           │
│  ├── export / import      Excel 导入导出         │
│  └── onboarding/*         用户引导               │
└─────────────────────────────────────────────────┘

数据流

用户操作 → Client Component
        → Server Action (actions.ts)
        → requirePermission() 权限校验
        → 数据访问层 (data-access.ts) 按 DataScope 过滤
        → 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 检查
     → 未引导: 强制填写角色/学校/班级信息
     → 已引导: 进入角色仪表盘

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（构建/部署/测试）
• 安全扫描: .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 功能清单 与 007 差距审计报告。

优先级完成情况

优先级	状态	说明
P0 (MVP 必须)	✅ 已完成	核心业务、平台基础、合规安全 P0 项已全部实现
P1 (上线前推荐)	✅ 已完成	站内消息、家长仪表盘、考勤、排课、成绩分析、Excel 导入导出、密码安全、数据变更日志等 P1 项已实现
P2 (迭代优化)	🔄 8/14 完成 (57%)	已完成：选课管理、考试监考、学情诊断、漏洞扫描、灾备方案、视觉回归测试等；剩余：国际化、多租户、AI 批改/学情/备课等

主要模块完成情况

• ✅ 用户与权限（6 角色、54 权限点、DataScope 行级权限）
• ✅ 学校管理（学校/年级/班级/部门/学年/学科）
• ✅ 教务排课（课程计划、排课规则、自动排课、调课审批、冲突检测）
• ✅ 教材资源（教材/章节/知识点树形结构、知识图谱）
• ✅ 题库与试卷（5 种题型、手动/AI 组卷、试卷预览）
• ✅ 作业与考试（作业发布/作答/批改、统计分析）
• ✅ 成绩分析（录入/查询/统计报表/趋势/对比/导出）
• ✅ 家校沟通（公告、站内消息、家长仪表盘）
• ✅ AI 赋能（AI 对话、AI 出题、多模型配置、API Key 加密）
• ✅ 考勤管理（学生考勤、考勤规则、统计）
• ✅ 日志审计（操作日志、登录日志、数据变更日志）
• ✅ 文件管理（上传/预览/删除、StorageProvider 抽象）
• ✅ 学情诊断（知识点掌握度、个人/班级诊断报告）
• ✅ 选课管理（选修课、选课/退选、抽签模式）
• ✅ 平台基础（全局搜索、Excel 导入导出、通知偏好、深色主题）

---

十、项目规模统计

维度	数量
数据库表	54
业务模块	26
UI 基础组件	30+
路由页面	60+
API 路由	9
Server Actions	80+
用户角色	6 (admin/teacher/student/parent/grade_head/teaching_head)
权限点	54

---

相关文档

文档	用途
004 架构影响地图	全模块·全函数·全参数级别架构图
005 架构数据	AI 友好的结构化架构数据
006 功能清单	企业级 K12 标准功能模块清单
007 差距审计报告	功能差距审计与补齐路线图