19 KiB
19 KiB
Next_Edu 项目概览
本文档是项目的入口概览，基于源码与架构影响地图（004/005）维护。 详细模块/函数/路由/表结构请查阅 004 架构影响地图 与 005 架构数据。
一、项目定位与目标
Next_Edu 是一个面向 K12 场景的智慧教务管理系统，旨在将传统学校的教务流程数字化、智能化。
核心目标：
- 多角色协同：6 种角色（管理员、教师、学生、家长、年级组长、教研组长）在同一平台协作，各角色有独立的仪表盘和功能入口
- AI 赋能教学：集成大语言模型（智谱/OpenAI/Gemini），支持 AI 自动生成试卷、AI 重写题目、AI 对话辅导
- 全流程闭环：从教材管理 → 题库建设 → 试卷组卷 → 考试/作业发布 → 学生作答 → 教师批改 → 数据分析，覆盖教学评估全链路
- 知识体系结构化：教材章节与知识点树形关联，知识点与题目双向链接，支撑精准教学与学情诊断
二、技术栈
| 层次 | 技术选型 | 版本 |
|---|---|---|
| 框架 | 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 张表定义）
五、架构设计
架构原则
- 分层架构：
app → modules → shared，三层单向依赖src/app/：Next.js App Router 路由层，负责路由分发、页面组装、Suspense/error 边界src/modules/：业务模块层，每个模块是一个独立的业务领域src/shared/：共享基础设施层，提供数据库、工具函数、权限系统、UI 基础组件
- 模块化：每个模块对应一个业务领域，包含
components/、hooks/、actions.ts、data-access.ts、types.ts、schema.ts - 权限校验：所有 Server Action 必须使用
requirePermission()或requireAuth()进行权限校验，前端组件使用usePermission().hasPermission()条件渲染（禁止role === "xxx"硬编码） - 数据访问：通过
data-access.ts层访问数据库，Server Action 不直接调用 Drizzle ORM - 类型安全：TypeScript strict 模式，Zod schema 校验输入，
ActionState<T>统一返回结构 - 行级权限：
DataScope提供 6 种数据范围类型，data-access 层按 scope 过滤数据
分层架构
┌─────────────────────────────────────────────────┐
│ App Router (src/app/) │
│ ├── Route Groups: (auth) / (dashboard) │
│ ├── Server Components (默认) │
│ ├── loading.tsx (Suspense 边界) │
│ └── error.tsx (错误边界) │
├─────────────────────────────────────────────────┤
│ Feature Modules (src/modules/) — 25 个模块 │
│ ├── 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.ymlscheduled-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 |
| 业务模块 | 25 |
| UI 基础组件 | 30+ |
| 路由页面 | 60+ |
| API 路由 | 9 |
| Server Actions | 80+ |
| 用户角色 | 6 (admin/teacher/student/parent/grade_head/teaching_head) |
| 权限点 | 54 |
相关文档
| 文档 | 用途 |
|---|---|
| 004 架构影响地图 | 全模块·全函数·全参数级别架构图 |
| 005 架构数据 | AI 友好的结构化架构数据 |
| 006 功能清单 | 企业级 K12 标准功能模块清单 |
| 007 差距审计报告 | 功能差距审计与补齐路线图 |