NextEdu/docs/architecture/007_gap_audit_report.md

Next_Edu 差距审计报告（v2 — 基于完整架构图）

对照《企业级 K12 教务管理系统标准功能模块清单》(006)，基于完整架构影响地图(004/005)与源码全量扫描 审计日期：2026-06-16（v2 更新） v2 变更：架构图已全量补全（12 模块 + 46 路由 + 32 表 + 200+ 导出），安全漏洞已修复

---

一、总体完成度

维度	P0 子功能总数	已完成	部分完成	未实现	完成率
核心业务	31	23	5	3	74%
平台基础	8	3	2	3	38%
非功能性	8	5	2	1	63%
合规安全	8	7	1	0	88%
合计	55	38	10	7	69%

P1 完成率约 25%，P2 完成率约 7%。

v2 修复项

修复项	v1 状态	v2 状态	说明
school/actions.ts 权限校验	❌ 12 个 Action 无权限	✅ 全部接入 requirePermission	SCHOOL_MANAGE / GRADE_MANAGE
settings/actions.ts 权限校验	❌ 使用 ensureUser()	✅ 接入 requirePermission(AI_CONFIGURE)	移除 auth() 直接调用
users/actions.ts 权限校验	❌ 使用 auth()	✅ 接入 requireAuth()	自助操作用 requireAuth
架构图完整性	⚠️ 大量缺失	✅ 全量补全	12 模块 + 46 路由 + 200+ 导出

关键风险项（v2 更新后）

1. 通知公告系统完全缺失 — P0 级功能，家校沟通核心载体，无任何代码实现
2. 操作/登录日志完全缺失 — P0 级功能，合规审计基础，无 DB 表、无代码
3. 成绩分析严重不足 — 仅有作业维度的分数趋势，缺少独立的成绩录入/统计报表/查询模块
4. 文件上传/权限控制缺失 — 当前无文件上传能力，题目/教材无法关联附件
5. 13 个幽灵导航路由 — navigation.ts 引用了 13 个不存在的页面（/admin/users/, /courses/, /reports, /finance, /parent/children, /parent/tuition, /messages），用户点击会 404

---

二、功能差距明细表

核心业务模块

标准模块	标准子功能	状态	项目现状说明	补齐建议
用户与权限	用户注册/登录	✅	NextAuth v5，邮箱+OAuth 登录，JWT 策略	—
	多角色体系	✅	6 角色，usersToRoles 多对多	—
	RBAC 权限模型	✅	30 个权限点，ROLE_PERMISSIONS 映射	—
	数据范围控制	✅	DataScope 6 种类型	—
	角色切换	❌	JWT 存 roles[]，但无主动切换 UI	新增角色切换下拉组件
	用户档案管理	✅	users 模块 updateUserProfile + getUserProfile，profile 页可编辑	—
	新手引导	✅	OnboardingGate 组件	—
	组织架构管理	⚠️	部门/年级 CRUD 已有，但无教研组管理	新增 teachingGroups 表
	用户批量导入	❌	无导入功能	Excel 解析 + 批量 insert
	密码安全策略	⚠️	NextAuth 默认 bcrypt，但无强度校验、无锁定策略	前端强度校验 + 后端锁定
学校管理	学校信息配置	✅	schools 表 + CRUD，requirePermission(SCHOOL_MANAGE)	—
	学年学期管理	✅	academicYears 表 + CRUD	—
	年级管理	✅	grades 表 + CRUD，requirePermission(GRADE_MANAGE)	—
	班级管理	✅	classes 表 + 17 个 actions，含邀请码	—
	学科管理	⚠️	subjects 表存在，但仅有 name/order/code	扩展学段归属字段
	部门管理	✅	departments 表 + CRUD	—
	校区管理	❌	无校区概念	新增 campuses 表
	学校参数配置	❌	无参数配置功能	新增 schoolSettings KV 表
教务排课	课程计划管理	❌	classSchedule 表仅存单条课表项	新增 coursePlans 表
	排课规则配置	❌	无规则引擎	新增 schedulingRules 表
	自动排课引擎	❌	无	CSP 求解器
	课表查看	✅	教师课表 + 学生课表 + 班级课表，含 ScheduleView/ScheduleFilters 组件	—
	课表调整/代课	❌	仅 CRUD 课表项	新增 scheduleChanges 表 + 审批流
	教室资源管理	⚠️	classrooms 表(name/building/floor/capacity)，但无管理 UI	增加 CRUD 页面
	选课管理	❌	无	新增 electiveCourses 表
教材资源	教材库管理	✅	textbooks 表 + createTextbookAction	—
	章节结构管理	✅	chapters 树形结构 + reorderChaptersAction 拖拽排序	—
	知识点图谱	⚠️	knowledgePoints 有 CRUD + 章节关联，但无前置/后继关系	增加 prerequisiteEdges 表
	教材内容阅读	✅	TextbookContentPanel，Markdown + rehype-sanitize	—
	教材版本管理	❌	无版本概念	增加 version 字段
	资源附件管理	❌	无文件上传能力	新增 attachments 表
	教材审核流程	❌	无审核机制	新增 reviewWorkflow 表
题库与试卷	题目创建/编辑	✅	5 种题型，支持子题目，CreateQuestionDialog	—
	题目分类标签	✅	知识点关联 + difficulty + type 多维标签	—
	题目批量导入	❌	无	Excel 模板 + 批量解析
	题目版本管理	❌	无	增加 questionVersions 表
	试卷手动组卷	✅	ExamAssembly 组件 + StructureEditor + QuestionBankList	—
	试卷智能组卷	❌	无自动抽题	按知识点/难度分布随机抽题
	AI 辅助出题	✅	ai-pipeline.ts：3 个 AI 生成函数 + generateAiExamDraft	—
	试卷模板管理	❌	无	新增 examTemplates 表
	试卷预览/打印	⚠️	ExamPreviewDialog 可预览，但无打印适配	增加 @media print
作业与考试	作业布置	✅	createHomeworkAssignmentAction + HomeworkAssignmentForm	—
	作业提交	✅	startHomeworkSubmissionAction + saveHomeworkAnswerAction + submitHomeworkAction	—
	作业批改评分	✅	gradeHomeworkSubmissionAction + HomeworkGradingView	—
	迟交/补交策略	⚠️	allowLate/lateDueAt 字段存在，前端未暴露配置	作业创建表单增加开关
	多次提交/重做	⚠️	maxAttempts 字段存在，有次数检查	前端暴露配置 + 重做入口
	作业统计分析	✅	getHomeworkAssignmentAnalytics + HomeworkAssignmentQuestionErrorOverviewCard	—
	作业归档	❌	无归档机制	增加 archivedAt 字段
	在线考试模式	❌	无限时/防切屏/乱序/自动交卷	新增 examMode + 前端计时器
	考试监考	❌	无	WebSocket 实时推送
成绩分析	成绩录入	❌	无独立成绩录入功能	新增 gradeRecords 表 + 录入 UI
	成绩查询	⚠️	学生仪表盘有作业分数(getStudentDashboardGrades)，无独立查询页	新增成绩查询页面
	成绩统计报表	❌	无班级/年级均分、中位数、标准差统计	新增聚合查询 + 图表
	成绩趋势分析	⚠️	getTeacherGradeTrends 提供教师维度趋势	扩展为多维度
	成绩对比分析	❌	无班级间/学科间对比	新增对比查询 + 雷达图
	学情诊断报告	❌	无	基于知识点掌握度生成诊断
	成绩导出	❌	无导出功能	ExcelJS/PDFKit 导出
	等第转换	❌	无	新增 gradeScale 配置
家校沟通	通知公告	❌	完全缺失	新增 announcements 表 + 三级发布
	站内消息	❌	无	新增 messages 表
	家长端仪表盘	⚠️	/parent/dashboard 路由存在但组件为空壳	接入子女数据查询
	家长会/约谈预约	❌	无	新增 appointments 表
	请假审批	❌	无	新增 leaveRequests 表
	校园动态/班级圈	❌	无	新增 posts 表
AI 赋能	AI 对话助手	✅	/api/ai/chat + createAiChatCompletion	—
	AI 辅助出题	✅	exams/ai-pipeline.ts 完整实现	—
	AI 批改辅助	❌	无	接入 AI 评分 prompt + 教师终审
	AI 学情分析	❌	无	基于作业数据生成学习路径
	AI 备课助手	❌	无	根据教材章节生成教案
	AI 多模型配置	✅	aiProviders 表 + upsertAiProviderAction，requirePermission(AI_CONFIGURE)	—
	AI API Key 加密	✅	AES 加密	—
考勤管理	学生考勤	❌	无	新增 attendanceRecords 表
	教师考勤	❌	无	同上
	考勤统计	❌	无	聚合查询 + 报表
	考勤规则配置	❌	无	新增 attendanceRules 配置

平台基础能力

标准模块	标准子功能	状态	项目现状说明	补齐建议
消息通知	站内通知	❌	无通知系统	新增 notifications 表 + 推送
	邮件通知	❌	无	集成 nodemailer/Resend
	短信通知	❌	无	集成短信网关
	微信/钉钉推送	❌	无	集成 webhook
	通知偏好管理	❌	无	新增 notificationPreferences 表
日志审计	操作日志	❌	完全缺失	新增 auditLogs 表 + action 拦截器
	登录日志	❌	无	新增 loginLogs 表 + NextAuth event
	数据变更日志	❌	无	Drizzle middleware 或 trigger
	日志查询/导出	❌	无	管理员日志查询页面
文件管理	文件上传	❌	无文件上传能力	新增 upload API + 存储
	文件预览	❌	无	集成文件预览服务
	文件存储策略	❌	无	抽象 StorageProvider 接口
	文件权限控制	❌	无	文件访问鉴权中间件
全局搜索	全文检索	❌	无	集成 Meilisearch/Typesense
	搜索建议	❌	无	搜索 API + 前端联想
	搜索过滤	❌	无	搜索结果筛选器
导入导出	Excel 导入	❌	无	ExcelJS 解析 + 校验
	Excel/PDF 导出	❌	无	ExcelJS/PDFKit 生成
	导入校验与错误报告	❌	无	行级校验 + 错误报告
数据看板	管理员仪表盘	✅	getAdminDashboardData + AdminDashboardView	—
	教师仪表盘	✅	TeacherDashboardView + 9 个子组件	—
	学生仪表盘	✅	StudentDashboard + 5 个子组件	—
	家长仪表盘	⚠️	路由存在但组件为空壳	接入子女数据
	自定义看板	❌	无	拖拽布局 + localStorage

非功能性模块

标准模块	标准子功能	状态	项目现状说明	补齐建议
国际化	多语言框架	❌	无 i18n 集成	集成 next-intl
	语言切换	❌	无	语言选择器 + URL 前缀
	日期/数字本地化	⚠️	formatDate 支持 locale 参数(默认 zh-CN)	绑定用户语言偏好
多租户/多校区	租户隔离	❌	无	行级 tenantId 或 schema 隔离
	校区资源映射	❌	无	跨校区共享规则
	统一管理后台	❌	无	集团管理视图
深色主题	主题切换	✅	ThemeProvider(next-themes) + ThemePreferencesCard	—
	主题色定制	❌	无	CSS 变量动态注入
无障碍访问	键盘导航	⚠️	部分组件支持，但非系统性	全面键盘测试
	ARIA 标注	⚠️	icon 按钮 aria-label 已加，非全覆盖	系统性 ARIA 审计
	屏幕阅读器兼容	❌	未测试	NVDA/VoiceOver 测试
	跳转链接	✅	layout.tsx 有 skip-link	—
性能优化	页面懒加载	✅	Next.js App Router 自动代码分割	—
	图片优化	✅	next/image 使用	—
	缓存策略	⚠️	部分页面 SSR，无系统性 ISR/SSG	关键页面配置 revalidate
	性能监控	❌	无 Web Vitals 采集	集成 next/web-vitals
自动化测试	单元测试	✅	Vitest 5 文件 19 用例	扩展覆盖率
	集成测试	✅	Vitest 7 文件 38 用例	扩展覆盖率
	E2E 测试	⚠️	Playwright 3 个 spec，需数据库环境	完善 CI 环境配置
	视觉回归测试	❌	无	集成 Chromatic
CI/CD	持续集成	✅	.gitea/workflows/ci.yml	—
	持续部署	✅	Dockerfile + CI 自动构建部署	—
	预览环境	❌	无	PR 预览部署
数据备份	数据库定时备份	❌	无	cron + mysqldump
	备份恢复演练	❌	无	定期恢复测试
	灾备方案	❌	无	异地容灾规划

合规与安全

标准模块	标准子功能	状态	项目现状说明	补齐建议
隐私合规	隐私政策与用户协议	❌	无隐私政策页面	新增 consent 页
	未成年人信息保护	❌	无年龄判断、无监护人同意流程	注册时年龄校验
	数据保留策略	❌	无	新增 dataRetentionPolicies
	用户数据导出/删除	❌	无	GDPR 式数据操作 API
数据加密	传输加密	✅	Next.js 默认 HTTPS	部署时配 HSTS
	存储加密	✅	AI API Key AES 加密，密码 bcrypt	—
	密码哈希	✅	NextAuth 默认 bcrypt	—
操作安全	CSRF 防护	✅	NextAuth SameSite Cookie + Server Action	—
	XSS 防护	✅	React 自动转义 + rehype-sanitize	—
	SQL 注入防护	✅	Drizzle ORM 参数化查询	—
	速率限制	❌	无	集成 upstash/ratelimit
	会话管理	✅	JWT 过期策略 + NextAuth	—
	Server Action 权限校验	✅	v2 修复：全部 57+ Server Action 均使用 requirePermission/requireAuth	—
敏感信息脱敏	日志脱敏	❌	无日志系统	日志框架内置脱敏
	前端脱敏	❌	无	手机号/邮箱掩码组件
	导出脱敏	❌	无导出功能	导出时可选脱敏
安全审计	漏洞扫描	❌	无	集成 OWASP ZAP/Snyk
	依赖审计	⚠️	npm audit 可用但未集成 CI	CI 增加 npm audit
	渗透测试	❌	无	上线前第三方测试

---

三、优先补齐路线图

Phase 1: P0 缺口补齐（MVP 必须项）

目标：将 P0 完成率从 69% 提升到 100%

序号	功能	所属模块	工作量	理由
1	通知公告系统	家校沟通	大	P0 缺失最严重项，学校运营核心需求
2	操作日志 + 登录日志	日志审计	大	P0 合规底线，无日志则无法追溯
3	成绩录入 + 查询 + 统计报表	成绩分析	大	P0 教务核心闭环缺失
4	文件上传 + 权限控制	文件管理	中	P0 基础能力，题目/教材/通知需附件
5	课程计划管理	教务排课	中	P0 排课前置条件
6	隐私政策 + 用户同意	隐私合规	小	P0 合规底线
7	未成年人信息保护	隐私合规	小	P0 K12 强制要求
8	修复 13 个幽灵导航路由	布局	小	用户点击 404，影响体验

Phase 2: P1 关键增强（上线前推荐）

序号	功能	所属模块	理由
1	站内消息系统	家校沟通	教师与家长沟通核心渠道
2	家长端仪表盘	家校沟通	家长核心入口，当前为空壳
3	Excel 批量导入	导入导出	开学季批量导入学生/教师
4	Excel/PDF 导出	导入导出	成绩单/名单导出
5	排课规则 + 自动排课	教务排课	手动排课效率极低
6	课表调整/代课	教务排课	日常调课高频操作
7	速率限制	操作安全	防暴力破解
8	成绩趋势 + 对比分析	成绩分析	教学质量分析核心
9	成绩导出	成绩分析	家长会/教研会必备
10	学生考勤	考勤管理	日常管理刚需
11	用户批量导入	用户与权限	开学季批量注册
12	密码安全策略	用户与权限	安全基线
13	数据变更日志	日志审计	争议追溯
14	日志查询/导出	日志审计	管理员日常使用
15	文件预览 + 存储策略	文件管理	用户体验提升
16	全文检索	全局搜索	题库/教材量大后必须
17	依赖审计集成 CI	安全审计	安全基线
18	数据库定时备份	数据备份	数据安全底线
19	E2E 测试完善	自动化测试	上线前回归保障
20	通知偏好管理	消息通知	用户体验

Phase 3: P2 迭代优化（竞争力提升）

序号	功能	所属模块	理由
1	国际化(i18n)	非功能性	海外学校/国际学校市场
2	多租户/多校区	非功能性	集团化办学市场
3	主题色定制	深色主题	学校品牌化
4	屏幕阅读器兼容	无障碍	合规 + 社会责任
5	视觉回归测试	自动化测试	UI 变更质量保障
6	AI 批改辅助	AI 赋能	教师效率提升
7	AI 学情分析	AI 赋能	个性化学习差异化
8	AI 备课助手	AI 赋能	教师备课效率
9	选课管理	教务排课	高中选修课场景
10	考试监考	作业与考试	在线考试完整性
11	学情诊断报告	成绩分析	精准教学
12	短信/微信推送	消息通知	紧急事件触达
13	漏洞扫描 + 渗透测试	安全审计	上线后安全验证
14	灾备方案	数据备份	业务连续性

---

四、差距统计摘要

状态	P0	P1	P2	合计
✅ 已完成	38	12	2	52
⚠️ 部分完成	10	8	1	19
❌ 未实现	7	28	27	62
合计	55	48	30	133

完成率	P0	P1	P2	总体
按已完成计	69%	25%	7%	39%
含部分完成	87%	42%	10%	53%

v1 → v2 改善

指标	v1	v2	变化
P0 完成率（严格）	65%	69%	+4%
P0 完成率（含部分）	83%	87%	+4%
安全漏洞数	15 个 Server Action 无权限	0	全部修复
架构图覆盖率	~40%	100%	全量补全
幽灵路由	未发现	13 个	新发现

结论：项目 P0 核心功能完成度约 69%（严格）/ 87%（含部分），较 v1 提升 4%。安全漏洞全部修复。架构图已全量补全。主要缺口集中在通知公告、日志审计、成绩分析三个 P0 模块。建议优先补齐 Phase 1 的 8 项 P0 缺口。