125f7ec54c
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、代码分割
19 KiB
19 KiB
Next_Edu 差距审计报告
对照《企业级 K12 教务管理系统标准功能模块清单》(006)，基于架构影响地图(004/005)与源码扫描 审计日期：2026-06-16
一、总体完成度
| 维度 | P0 子功能总数 | 已完成 | 部分完成 | 未实现 | 完成率 |
|---|---|---|---|---|---|
| 核心业务 | 31 | 22 | 5 | 4 | 71% |
| 平台基础 | 8 | 3 | 2 | 3 | 38% |
| 非功能性 | 8 | 5 | 2 | 1 | 63% |
| 合规安全 | 8 | 6 | 1 | 1 | 75% |
| 合计 | 55 | 36 | 10 | 9 | 65% |
P1 完成率约 25%，P2 完成率约 5%。
关键风险项
- 通知公告系统完全缺失 — P0 级功能，家校沟通核心载体，无任何代码实现
- 操作/登录日志完全缺失 — P0 级功能，合规审计基础，无 DB 表、无代码
- 成绩分析严重不足 — 仅有作业维度的分数趋势，缺少独立的成绩录入/统计报表/查询模块
- 文件上传/权限控制缺失 — 当前无文件上传能力，题目/教材无法关联附件
- 排课仅手动录入 — 无排课规则引擎，无自动排课，无冲突检测
二、功能差距明细表
核心业务模块
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|---|---|---|---|---|
| 用户与权限 | 用户注册/登录 | ✅ | NextAuth v5，邮箱+OAuth 登录，JWT 策略 | — |
| 多角色体系 | ✅ | 6 角色(admin/teacher/student/parent/grade_head/teaching_head)，usersToRoles 多对多 | — | |
| RBAC 权限模型 | ✅ | 30 个 resource:action 权限点，ROLE_PERMISSIONS 映射 |
— | |
| 数据范围控制 | ✅ | DataScope 6 种类型(all/owned/class_taught/grade_managed/class_members/children) | — | |
| 角色切换 | ❌ | JWT 存 roles[]，但无主动切换 UI | 新增角色切换下拉组件，切换后重写 JWT | |
| 用户档案管理 | ⚠️ | profile 页可编辑姓名/邮箱，但无头像上传、地址编辑 | 增加 avatar 字段 + 图片上传 | |
| 新手引导 | ✅ | OnboardingGate 组件，角色选择→学校/班级配置 | — | |
| 组织架构管理 | ⚠️ | 部门/年级 CRUD 已有(school 模块)，但无教研组管理 | 新增 teachingGroups 表 + CRUD | |
| 用户批量导入 | ❌ | 无导入功能 | 新增 Excel 解析 + 批量 insert 事务 | |
| 密码安全策略 | ⚠️ | NextAuth 默认 bcrypt，但无强度校验、无锁定策略 | 前端强度校验 + 后端失败计数锁定 | |
| 学校管理 | 学校信息配置 | ✅ | schools 表 + createSchoolAction/updateSchoolAction | — |
| 学年学期管理 | ✅ | academicYears 表 + CRUD actions，isActive 标记 | — | |
| 年级管理 | ✅ | grades 表 + CRUD，gradeHeadId/teachingHeadId 指派 | — | |
| 班级管理 | ✅ | classes 表 + 17 个 actions，含邀请码、学生注册 | — | |
| 学科管理 | ⚠️ | subjects 表存在，但仅有 name/order，无代码/学段归属字段 | 扩展 subjects 表字段 | |
| 部门管理 | ✅ | departments 表 + CRUD actions | — | |
| 校区管理 | ❌ | 无校区概念 | 新增 campuses 表，schools 关联 campusId | |
| 学校参数配置 | ❌ | 无参数配置功能 | 新增 schoolSettings KV 表 | |
| 教务排课 | 课程计划管理 | ❌ | classSchedule 表仅存单条课表项，无课程计划概念 | 新增 coursePlans 表 + 管理界面 |
| 排课规则配置 | ❌ | 无规则引擎 | 新增 schedulingRules 表 + 约束求解器 | |
| 自动排课引擎 | ❌ | 无 | 集成开源排课算法或自研 CSP 求解器 | |
| 课表查看 | ⚠️ | 教师班级课表 + 学生课表已有，但无教室维度 | 增加 classroom 维度查询 | |
| 课表调整/代课 | ❌ | 仅 CRUD 课表项，无调课/代课流程 | 新增 scheduleChanges 表 + 审批流 | |
| 教室资源管理 | ⚠️ | classrooms 表存在(字段: location, capacity)，但无管理 UI | 增加 CRUD 页面 + 设备标签 | |
| 选课管理 | ❌ | 无 | 新增 electiveCourses + studentSelections 表 | |
| 教材资源 | 教材库管理 | ✅ | textbooks 表 + createTextbookAction，含 subject/grade/publisher | — |
| 章节结构管理 | ✅ | chapters 树形结构 + reorderChaptersAction 拖拽排序 | — | |
| 知识点图谱 | ⚠️ | knowledgePoints 有 CRUD + 章节关联，但无前置/后继关系 | 增加 prerequisiteEdges 表 | |
| 教材内容阅读 | ✅ | textbook-content-panel.tsx，Markdown 渲染 + rehype-sanitize | — | |
| 教材版本管理 | ❌ | 无版本概念 | 增加 textbookVersions 表或 version 字段 | |
| 资源附件管理 | ❌ | 无文件上传能力 | 新增 attachments 表 + 文件上传服务 | |
| 教材审核流程 | ❌ | 无审核机制 | 新增 reviewWorkflow 表 + 状态机 | |
| 题库与试卷 | 题目创建/编辑 | ✅ | 5 种题型(single_choice/multiple_choice/text/judgment/composite)，支持子题目 | — |
| 题目分类标签 | ✅ | 知识点关联 + difficulty + type 多维标签 | — | |
| 题目批量导入 | ❌ | 无 | Excel 模板 + 批量解析 | |
| 题目版本管理 | ❌ | 无 | 增加 questionVersions 表 | |
| 试卷手动组卷 | ✅ | exams 表 structure 字段，examQuestions 关联 | — | |
| 试卷智能组卷 | ❌ | 无自动抽题 | 按知识点/难度分布约束随机抽题算法 | |
| AI 辅助出题 | ✅ | ai-pipeline.ts：generateAiPreviewData/generateAiCreateDraftFromSource/regenerateAiQuestionByInstruction | — | |
| 试卷模板管理 | ❌ | 无 | 新增 examTemplates 表 | |
| 试卷预览/打印 | ⚠️ | exam-preview-dialog.tsx 可预览，但无打印适配 | 增加打印 CSS @media print | |
| 作业与考试 | 作业布置 | ✅ | createHomeworkAssignmentAction，关联 sourceExamId + classId | — |
| 作业提交 | ✅ | startHomeworkSubmissionAction + saveHomeworkAnswerAction + submitHomeworkAction | — | |
| 作业批改评分 | ✅ | gradeHomeworkSubmissionAction，逐题评分 + feedback | — | |
| 迟交/补交策略 | ⚠️ | homeworkAssignments 表有 allowLate/lateDueAt 字段，但前端未暴露配置 | 作业创建表单增加迟交开关 | |
| 多次提交/重做 | ⚠️ | maxAttempts 字段存在，startHomeworkSubmissionAction 有次数检查 | 前端暴露配置 + 重做入口 | |
| 作业统计分析 | ⚠️ | getHomeworkAssignmentAnalytics 存在，但仅限单次作业维度 | 增加班级/时间维度汇总 | |
| 作业归档 | ❌ | 无归档机制 | 增加 archivedAt 字段 + 归档 API | |
| 在线考试模式 | ❌ | 无限时/防切屏/乱序/自动交卷 | 新增 examMode 字段 + 前端计时器 + 乱序逻辑 | |
| 考试监考 | ❌ | 无 | 新增实时提交进度 WebSocket 推送 | |
| 成绩分析 | 成绩录入 | ❌ | 无独立成绩录入功能，仅作业自动同步分数 | 新增 gradeRecords 表 + 手动录入 UI |
| 成绩查询 | ⚠️ | 学生可查作业分数(getStudentDashboardGrades)，但无独立成绩查询页 | 新增成绩查询页面 | |
| 成绩统计报表 | ❌ | 无班级/年级均分、中位数、标准差、及格率统计 | 新增统计聚合查询 + 图表组件 | |
| 成绩趋势分析 | ⚠️ | getTeacherGradeTrends 提供教师维度趋势，学生有 trend 数据 | 扩展为多维度趋势 | |
| 成绩对比分析 | ❌ | 无班级间/学科间对比 | 新增对比查询 + 雷达图 | |
| 学情诊断报告 | ❌ | 无 | 基于知识点掌握度生成诊断 | |
| 成绩导出 | ❌ | 无导出功能 | ExcelJS/PDFKit 导出 | |
| 等第转换 | ❌ | 无 | 新增 gradeScale 配置 + 转换函数 | |
| 家校沟通 | 通知公告 | ❌ | 完全缺失，无 DB 表、无 API、无 UI | 新增 announcements 表 + 三级发布 + 已读回执 |
| 站内消息 | ❌ | 无 | 新增 messages 表 + 实时通知 | |
| 家长端仪表盘 | ⚠️ | /parent/dashboard 路由存在但组件为空壳 | 接入子女数据查询 | |
| 家长会/约谈预约 | ❌ | 无 | 新增 appointments 表 | |
| 请假审批 | ❌ | 无 | 新增 leaveRequests 表 + 审批流 | |
| 校园动态/班级圈 | ❌ | 无 | 新增 posts 表 + 评论/点赞 | |
| AI 赵能 | AI 对话助手 | ✅ | /api/ai/chat 路由 + createAiChatCompletion，Zod 校验 | — |
| AI 辅助出题 | ✅ | exams/ai-pipeline.ts 完整实现 | — | |
| AI 批改辅助 | ❌ | 无 | 接入 AI 评分 prompt + 教师终审 | |
| AI 学情分析 | ❌ | 无 | 基于作业数据生成学习路径 | |
| AI 备课助手 | ❌ | 无 | 根据教材章节生成教案 | |
| AI 多模型配置 | ✅ | aiProviders 表 + upsertAiProviderAction，支持多 provider | — | |
| AI API Key 加密 | ✅ | encryptAiApiKey/decryptAiApiKey，AES 加密 | — | |
| 考勤管理 | 学生考勤 | ❌ | 无 | 新增 attendanceRecords 表 + 登记界面 |
| 教师考勤 | ❌ | 无 | 同上 | |
| 考勤统计 | ❌ | 无 | 聚合查询 + 报表 | |
| 考勤规则配置 | ❌ | 无 | 新增 attendanceRules 配置 |
平台基础能力
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|---|---|---|---|---|
| 消息通知 | 站内通知 | ❌ | 无通知系统 | 新增 notifications 表 + 轮询/WebSocket 推送 |
| 邮件通知 | ❌ | 无 | 集成 nodemailer/Resend | |
| 短信通知 | ❌ | 无 | 集成短信网关 SDK | |
| 微信/钉钉推送 | ❌ | 无 | 集成 webhook | |
| 通知偏好管理 | ❌ | 无 | 新增 notificationPreferences 表 | |
| 日志审计 | 操作日志 | ❌ | 完全缺失 | 新增 auditLogs 表 + action 拦截器 |
| 登录日志 | ❌ | 无 | 新增 loginLogs 表 + NextAuth event 回调 | |
| 数据变更日志 | ❌ | 无 | Drizzle middleware 或 trigger | |
| 日志查询/导出 | ❌ | 无 | 管理员日志查询页面 | |
| 文件管理 | 文件上传 | ❌ | 无文件上传能力 | 新增 upload API + 本地/OSS 存储 |
| 文件预览 | ❌ | 无 | 集成文件预览服务 | |
| 文件存储策略 | ❌ | 无 | 抽象 StorageProvider 接口 | |
| 文件权限控制 | ❌ | 无 | 文件访问鉴权中间件 | |
| 全局搜索 | 全文检索 | ❌ | 无 | 集成 Meilisearch/Typesense |
| 搜索建议 | ❌ | 无 | 搜索 API + 前端联想 | |
| 搜索过滤 | ❌ | 无 | 搜索结果筛选器 | |
| 导入导出 | Excel 导入 | ❌ | 无 | ExcelJS 解析 + 校验 |
| Excel/PDF 导出 | ❌ | 无 | ExcelJS/PDFKit 生成 | |
| 导入校验与错误报告 | ❌ | 无 | 行级校验 + 错误报告下载 | |
| 数据看板 | 管理员仪表盘 | ✅ | getAdminDashboardData：userCount/classCount/activeSessions/userRoleCounts | — |
| 教师仪表盘 | ✅ | TeacherDashboardData：classes/schedule/assignments/submissions/gradeTrends | — | |
| 学生仪表盘 | ✅ | StudentDashboardProps：dueSoonCount/overdueCount/gradedCount/todaySchedule/grades | — | |
| 家长仪表盘 | ⚠️ | 路由存在但组件为空壳 | 接入子女数据 | |
| 自定义看板 | ❌ | 无 | 拖拽布局 + localStorage 持久化 |
非功能性模块
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|---|---|---|---|---|
| 国际化 | 多语言框架 | ❌ | 无 i18n 集成 | 集成 next-intl |
| 语言切换 | ❌ | 无 | 语言选择器 + URL 前缀 | |
| 日期/数字本地化 | ⚠️ | formatDate 支持 locale 参数(默认 zh-CN)，但无用户偏好 | 绑定用户语言偏好 | |
| 多租户/多校区 | 租户隔离 | ❌ | 无 | 行级 tenantId 或 schema 隔离 |
| 校区资源映射 | ❌ | 无 | 跨校区共享规则 | |
| 统一管理后台 | ❌ | 无 | 集团管理视图 | |
| 深色主题 | 主题切换 | ✅ | ThemeProvider(next-themes) + theme-preferences-card | — |
| 主题色定制 | ❌ | 无 | CSS 变量动态注入 | |
| 无障碍访问 | 键盘导航 | ⚠️ | 部分组件支持，但非系统性 | 全面键盘测试 + 修复 |
| ARIA 标注 | ⚠️ | icon 按钮 aria-label 已加，但非全覆盖 | 系统性 ARIA 审计 | |
| 屏幕阅读器兼容 | ❌ | 未测试 | NVDA/VoiceOver 测试 | |
| 跳转链接 | ✅ | layout.tsx 有 skip-link + id="main-content" | — | |
| 性能优化 | 页面懒加载 | ✅ | 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：lint + typecheck + test | — |
| 持续部署 | ✅ | Dockerfile + CI 自动构建部署 | — | |
| 预览环境 | ❌ | 无 | PR 预览部署 | |
| 数据备份 | 数据库定时备份 | ❌ | 无 | cron + mysqldump 脚本 |
| 备份恢复演练 | ❌ | 无 | 定期恢复测试 | |
| 灾备方案 | ❌ | 无 | 异地容灾规划 |
合规与安全
| 标准模块 | 标准子功能 | 状态 | 项目现状说明 | 补齐建议 |
|---|---|---|---|---|
| 隐私合规 | 隐私政策与用户协议 | ❌ | 无隐私政策页面，注册无同意勾选 | 新增 consent 页 + 注册流程集成 |
| 未成年人信息保护 | ❌ | 无年龄判断、无监护人同意流程 | 注册时年龄校验 + 监护人字段 | |
| 数据保留策略 | ❌ | 无 | 新增 dataRetentionPolicies 配置 | |
| 用户数据导出/删除 | ❌ | 无 | GDPR 式数据操作 API | |
| 数据加密 | 传输加密 | ✅ | Next.js 默认 HTTPS，生产环境应配 HSTS | 部署时配置 HSTS 头 |
| 存储加密 | ✅ | AI API Key AES 加密，密码 bcrypt 哈希 | — | |
| 密码哈希 | ✅ | NextAuth 默认 bcrypt | — | |
| 操作安全 | CSRF 防护 | ✅ | NextAuth SameSite Cookie + Server Action CSRF 保护 | — |
| XSS 防护 | ✅ | React 自动转义 + rehype-sanitize 净化 HTML | — | |
| SQL 注入防护 | ✅ | Drizzle ORM 参数化查询 | — | |
| 速率限制 | ❌ | 无 | 集成 next-rate-limit 或 upstash/ratelimit | |
| 会话管理 | ✅ | JWT 过期策略 + NextAuth session 管理 | — | |
| 敏感信息脱敏 | 日志脱敏 | ❌ | 无日志系统 | 日志框架内置脱敏 |
| 前端脱敏 | ❌ | 无 | 手机号/邮箱掩码组件 | |
| 导出脱敏 | ❌ | 无导出功能 | 导出时可选脱敏 | |
| 安全审计 | 漏洞扫描 | ❌ | 无 | 集成 OWASP ZAP 或 Snyk |
| 依赖审计 | ⚠️ | npm audit 可用但未集成 CI | CI 增加 npm audit 步骤 | |
| 渗透测试 | ❌ | 无 | 上线前第三方测试 |
三、优先补齐路线图
Phase 1: P0 缺口补齐（MVP 必须项）
目标：将 P0 完成率从 65% 提升到 100%
| 序号 | 功能 | 所属模块 | 工作量 | 理由 |
|---|---|---|---|---|
| 1 | 通知公告系统 | 家校沟通 | 大 | P0 缺失最严重项，学校运营核心需求；需 DB 表 + API + 三级发布 + 已读回执 |
| 2 | 操作日志 + 登录日志 | 日志审计 | 大 | P0 合规底线，无日志则无法追溯问题；需 DB 表 + action 拦截 + NextAuth event |
| 3 | 成绩录入 + 查询 + 统计报表 | 成绩分析 | 大 | P0 教务核心闭环缺失；需 gradeRecords 表 + 录入 UI + 聚合查询 + 图表 |
| 4 | 文件上传 + 权限控制 | 文件管理 | 中 | P0 基础能力，题目/教材/通知均需附件；需 upload API + 存储抽象 + 鉴权 |
| 5 | 课程计划管理 | 教务排课 | 中 | P0 排课前置条件；需 coursePlans 表 + 管理界面 |
| 6 | 隐私政策 + 用户同意 | 隐私合规 | 小 | P0 合规底线；需 consent 页面 + 注册流程集成 |
| 7 | 未成年人信息保护 | 隐私合规 | 小 | P0 K12 强制要求；需年龄校验 + 监护人字段 |
Phase 2: P1 关键增强（上线前推荐）
目标：产品达到可上线标准
| 序号 | 功能 | 所属模块 | 理由 |
|---|---|---|---|
| 1 | 站内消息系统 | 家校沟通 | 教师与家长沟通核心渠道 |
| 2 | 家长端仪表盘 | 家校沟通 | 家长核心入口，当前为空壳 |
| 3 | Excel 批量导入 | 导入导出 | 开学季批量导入学生/教师刚需 |
| 4 | Excel/PDF 导出 | 导入导出 | 成绩单/名单导出刚需 |
| 5 | 排课规则 + 自动排课 | 教务排课 | 手动排课效率极低，自动排课是核心竞争力 |
| 6 | 课表调整/代课 | 教务排课 | 日常调课是高频操作 |
| 7 | 速率限制 | 操作安全 | 防暴力破解，API 安全基线 |
| 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 | 合计 |
|---|---|---|---|---|
| ✅ 已完成 | 36 | 12 | 2 | 50 |
| ⚠️ 部分完成 | 10 | 8 | 1 | 19 |
| ❌ 未实现 | 9 | 28 | 27 | 64 |
| 合计 | 55 | 48 | 30 | 133 |
| 完成率 | P0 | P1 | P2 | 总体 |
|---|---|---|---|---|
| 按已完成计 | 65% | 25% | 7% | 38% |
| 含部分完成 | 83% | 42% | 10% | 51% |
结论：项目 P0 核心功能完成度约 65%（严格）/ 83%（含部分），主要缺口集中在家校沟通(通知公告)、日志审计、成绩分析三个 P0 模块。建议优先补齐 Phase 1 的 7 项 P0 缺口，再推进 Phase 2 的 P1 增强。