NextEdu/docs/architecture/008_module_role_mapping.md

# 模块-角色-功能映射总览

> 生成日期：2026-06-22
> 数据来源：`src/modules/` 全量扫描 + `src/app/(dashboard)/` 路由权限校验 + `src/shared/types/permissions.ts` 权限点定义
> 角色体系：admin / teacher / student / parent / grade_head / teaching_head（含 management 路由组）

---

## 一、模块-角色速查表

| # | 模块 | 目录 | admin | teacher | student | parent | mgmt | 核心功能 |
|---|------|------|:-----:|:-------:|:-------:|:------:|:----:|----------|
| 1 | adaptive-practice | `adaptive-practice/` | | ✅ | ✅ | ✅ | ✅ | 专项练习：自适应出题、答题、练习历史、成绩分析 |
| 2 | ai | `ai/` | ✅ | ✅ | ✅ | ✅ | ✅ | AI 赋能：对话助手、出题辅助、批改辅助、学情分析、多模型配置 |
| 3 | announcements | `announcements/` | ✅ | ✅ | ✅ | ✅ | ✅ | 通知公告：学校/年级/班级三级公告发布与查看 |
| 4 | attendance | `attendance/` | ✅ | ✅ | ✅ | ✅ | | 考勤管理：学生/教师考勤登记、统计、规则配置 |
| 5 | audit | `audit/` | ✅ | | | | | 日志审计：操作日志、登录日志、数据变更日志、导出 |
| 6 | auth | `auth/` | ✅ | ✅ | ✅ | ✅ | ✅ | 认证系统：登录/注册/JWT/双因素认证 |
| 7 | classes | `classes/` | ✅ | ✅ | ✅ | | | 班级管理：班级 CRUD、课表、学生管理、邀请码 |
| 8 | course-plans | `course-plans/` | ✅ | ✅ | ✅ | ✅ | | 课程计划：教学计划创建、进度跟踪、日历视图 |
| 9 | dashboard | `dashboard/` | ✅ | ✅ | ✅ | ✅ | ✅ | 仪表盘：角色独立看板（统计卡片/图表/快捷操作） |
| 10 | diagnostic | `diagnostic/` | | ✅ | ✅ | ✅ | | 学情诊断：知识点掌握度雷达图、班级/个人诊断报告 |
| 11 | elective | `elective/` | ✅ | ✅ | ✅ | ✅ | | 选课管理：选修课创建/选课/退选/抽签 |
| 12 | error-book | `error-book/` | ✅ | ✅ | ✅ | ✅ | | 错题本：错题自动采集、SM-2 间隔复习、统计分析 |
| 13 | exams | `exams/` | | ✅ | | | | 考试管理：AI 出题/组卷/批改/监考/分析 |
| 14 | files | `files/` | ✅ | ✅ | ✅ | ✅ | ✅ | 文件管理：上传/预览/存储/权限控制 |
| 15 | grades | `grades/` | ✅ | ✅ | ✅ | ✅ | ✅ | 成绩管理：录入/查询/统计/趋势/导出/排名 |
| 16 | homework | `homework/` | | ✅ | ✅ | | | 作业管理：布置/提交/批改/评分/统计分析 |
| 17 | layout | `layout/` | ✅ | ✅ | ✅ | ✅ | ✅ | 布局框架：导航配置/侧边栏/顶部栏（所有角色共用） |
| 18 | lesson-preparation | `lesson-preparation/` | ✅ | ✅ | ✅ | ✅ | | 备课系统：教案创建/编辑/发布/查看 |
| 19 | messaging | `messaging/` | ✅ | ✅ | ✅ | ✅ | ✅ | 站内消息：私信/群发/草稿/已读状态 |
| 20 | notifications | `notifications/` | ✅ | ✅ | ✅ | ✅ | ✅ | 通知系统：站内/邮件/短信/微信多渠道推送、偏好管理 |
| 21 | onboarding | `onboarding/` | ✅ | ✅ | ✅ | ✅ | ✅ | 新手引导：首次登录角色选择、资料填写、班级加入 |
| 22 | parent | `parent/` | | | | ✅ | | 家长聚合：子女学习概览、成绩/作业/考勤详情 |
| 23 | proctoring | `proctoring/` | | ✅ | | | | 考试监考：实时提交进度、异常行为标记 |
| 24 | questions | `questions/` | ✅ | ✅ | | | | 题库管理：题目 CRUD、分类标签、批量导入导出 |
| 25 | rbac | `rbac/` | ✅ | | | | | 角色权限：动态角色管理、权限目录、角色-权限分配 |
| 26 | scheduling | `scheduling/` | ✅ | ✅ | ✅ | | | 排课系统：自动排课引擎、课表查看、调课/代课 |
| 27 | school | `school/` | ✅ | | | | | 学校管理：学校信息/学年学期/年级/班级/部门/学科 |
| 28 | settings | `settings/` | ✅ | ✅ | ✅ | ✅ | ✅ | 用户设置：个人信息/通知偏好/外观/安全/登出 |
| 29 | standards | `standards/` | (via) | (via) | | | | 课标库：国家/校标/自定义课标，通过 lesson-preparation 使用 |
| 30 | student | `student/` | | | ✅ | | | 学生聚合：课程查看/课表/学习路径 |
| 31 | textbooks | `textbooks/` | (via) | ✅ | ✅ | | | 教材资源：教材库/章节结构/知识点图谱/内容阅读 |
| 32 | users | `users/` | ✅ | | | | | 用户管理：用户 CRUD、批量导入、角色分配 |

> 注：`✅` = 有独立页面路由；`(via)` = 通过其他模块间接使用，无独立路由页面

---

## 二、按角色展开的模块清单

### 2.1 admin（系统管理员）

| 模块 | 页面路由 | 权限点 | 功能说明 |
|------|----------|--------|----------|
| **school** | `/admin/school` | `SCHOOL_MANAGE` | 学校基础信息配置 |
| | `/admin/school/schools` | `SCHOOL_MANAGE` | 多校区管理 |
| | `/admin/school/academic-year` | `SCHOOL_MANAGE` | 学年学期管理 |
| | `/admin/school/classes` | `SCHOOL_MANAGE` | 班级创建与管理 |
| | `/admin/school/departments` | `SCHOOL_MANAGE` | 部门管理 |
| | `/admin/school/grades` | `SCHOOL_MANAGE` | 年级管理与组长指派 |
| | `/admin/school/grades/insights` | `SCHOOL_MANAGE` | 年级洞察分析 |
| **users** | `/admin/users` | `USER_MANAGE` | 用户账号管理 |
| | `/admin/users/import` | `USER_MANAGE` | 批量导入用户 |
| **rbac** | `/admin/roles` | `ROLE_READ` | 角色列表查看 |
| | `/admin/roles/[id]` | `ROLE_READ` | 角色详情与权限编辑 |
| | `/admin/permissions` | `PERMISSION_READ` | 权限点目录查看 |
| **announcements** | `/admin/announcements` | `ANNOUNCEMENT_MANAGE` | 公告管理（创建/编辑/删除） |
| | `/admin/announcements/[id]` | `ANNOUNCEMENT_MANAGE` | 公告详情 |
| | `/admin/announcements/[id]/edit` | `ANNOUNCEMENT_MANAGE` | 编辑公告 |
| **audit** | `/admin/audit-logs` | `AUDIT_LOG_READ` | 操作日志查看 |
| | `/admin/audit-logs/overview` | `AUDIT_LOG_READ` | 审计概览统计 |
| | `/admin/audit-logs/data-changes` | `AUDIT_LOG_READ` | 数据变更日志 |
| | `/admin/audit-logs/login-logs` | `AUDIT_LOG_READ` | 登录日志 |
| **dashboard** | `/admin/dashboard` | `DASHBOARD_ADMIN_READ` | 管理员仪表盘 |
| **scheduling** | `/admin/scheduling/auto` | `SCHEDULE_AUTO` | 自动排课 |
| | `/admin/scheduling/changes` | `SCHEDULE_ADJUST` | 调课管理 |
| | `/admin/scheduling/rules` | `SCHEDULE_ADJUST` | 排课规则配置 |
| **course-plans** | `/admin/course-plans` | `COURSE_PLAN_READ` | 课程计划查看 |
| | `/admin/course-plans/create` | `COURSE_PLAN_MANAGE` | 创建课程计划 |
| | `/admin/course-plans/[id]` | `COURSE_PLAN_READ` | 课程计划详情 |
| | `/admin/course-plans/[id]/edit` | `COURSE_PLAN_MANAGE` | 编辑课程计划 |
| **elective** | `/admin/elective` | `ELECTIVE_READ` | 选课管理 |
| | `/admin/elective/create` | `ELECTIVE_MANAGE` | 创建选修课 |
| | `/admin/elective/[id]` | `ELECTIVE_READ` | 选修课详情 |
| | `/admin/elective/[id]/edit` | `ELECTIVE_MANAGE` | 编辑选修课 |
| **attendance** | `/admin/attendance` | `ATTENDANCE_READ` | 考勤数据查看 |
| **error-book** | `/admin/error-book` | `ERROR_BOOK_ANALYTICS_READ` | 全校错题统计分析 |
| **questions** | `/admin/questions` | `QUESTION_READ` | 题库管理 |
| **files** | `/admin/files` | `FILE_READ` | 文件管理 |
| **ai** | `/admin/ai-settings` | `AI_CHAT` | AI 多模型配置 |
| **lesson-plans** | `/admin/lesson-plans` | `LESSON_PLAN_READ` | 教案查看 |
| | `/admin/lesson-plans/[planId]/view` | `LESSON_PLAN_READ` | 教案详情 |
| **settings** | `/admin/settings` | `SETTINGS_ADMIN` | 管理员设置 |

---

### 2.2 teacher（教师）

| 模块 | 页面路由 | 权限点 | 功能说明 |
|------|----------|--------|----------|
| **dashboard** | `/teacher/dashboard` | `DASHBOARD_TEACHER_READ` | 教师仪表盘（待批改/今日课表/班级动态） |
| **classes** | `/teacher/classes/my` | `CLASS_READ` | 我的班级列表 |
| | `/teacher/classes/my/[id]` | `CLASS_READ` | 班级详情 |
| | `/teacher/classes/schedule` | `CLASS_READ` | 班级课表 |
| | `/teacher/classes/students` | `CLASS_READ` | 班级学生管理 |
| **exams** | `/teacher/exams` | `EXAM_READ` | 考试列表 |
| | `/teacher/exams/all` | `EXAM_READ` | 全部考试 |
| | `/teacher/exams/create` | `EXAM_CREATE` | 创建考试 |
| | `/teacher/exams/new` | `EXAM_CREATE` | AI 出题 |
| | `/teacher/exams/[id]/build` | `EXAM_READ` | 组卷 |
| | `/teacher/exams/[id]/edit-rich` | `EXAM_UPDATE` | 富文本编辑试卷 |
| | `/teacher/exams/[id]/analytics` | `EXAM_READ` | 考试分析 |
| | `/teacher/exams/[id]/proctoring` | `EXAM_PROCTOR` | 考试监考 |
| | `/teacher/exams/grading` | `HOMEWORK_GRADE` | 批改列表 |
| | `/teacher/exams/grading/[submissionId]` | `HOMEWORK_GRADE` | 批改详情 |
| **homework** | `/teacher/homework/assignments` | `HOMEWORK_CREATE` | 作业管理 |
| | `/teacher/homework/assignments/create` | `HOMEWORK_CREATE` | 布置作业 |
| | `/teacher/homework/assignments/[id]` | `HOMEWORK_CREATE` | 作业详情 |
| | `/teacher/homework/assignments/[id]/submissions` | `HOMEWORK_GRADE` | 提交列表 |
| | `/teacher/homework/submissions` | `HOMEWORK_GRADE` | 批改列表 |
| | `/teacher/homework/submissions/[submissionId]` | `HOMEWORK_GRADE` | 批改详情 |
| | `/teacher/homework/submissions/[submissionId]/scan-grading` | `HOMEWORK_GRADE` | 阅卷式批改 |
| **grades** | `/teacher/grades` | `GRADE_RECORD_READ` | 成绩查询 |
| | `/teacher/grades/analytics` | `GRADE_RECORD_READ` | 成绩分析 |
| | `/teacher/grades/entry` | `GRADE_RECORD_MANAGE` | 成绩录入 |
| | `/teacher/grades/stats` | `GRADE_RECORD_READ` | 成绩统计 |
| **questions** | `/teacher/questions` | `QUESTION_READ` | 题库管理 |
| **textbooks** | `/teacher/textbooks` | `TEXTBOOK_READ` | 教材查看 |
| | `/teacher/textbooks/[id]` | `TEXTBOOK_READ` | 教材内容 |
| **lesson-plans** | `/teacher/lesson-plans` | `LESSON_PLAN_READ` | 教案列表 |
| | `/teacher/lesson-plans/new` | `LESSON_PLAN_READ` | 创建教案 |
| | `/teacher/lesson-plans/[planId]/edit` | `LESSON_PLAN_READ` | 编辑教案 |
| **diagnostic** | `/teacher/diagnostic` | `DIAGNOSTIC_READ` | 学情诊断总览 |
| | `/teacher/diagnostic/class/[classId]` | `DIAGNOSTIC_READ` | 班级诊断 |
| | `/teacher/diagnostic/student/[studentId]` | `DIAGNOSTIC_READ` | 学生诊断 |
| **attendance** | `/teacher/attendance` | `ATTENDANCE_READ` | 考勤查看 |
| | `/teacher/attendance/sheet` | `ATTENDANCE_MANAGE` | 考勤登记 |
| | `/teacher/attendance/stats` | `ATTENDANCE_READ` | 考勤统计 |
| **course-plans** | `/teacher/course-plans` | `COURSE_PLAN_READ` | 课程计划 |
| | `/teacher/course-plans/[id]` | `COURSE_PLAN_READ` | 计划详情 |
| **elective** | `/teacher/elective` | `ELECTIVE_READ` | 选课管理 |
| | `/teacher/elective/create` | `ELECTIVE_MANAGE` | 创建选修课 |
| | `/teacher/elective/[id]/edit` | `ELECTIVE_MANAGE` | 编辑选修课 |
| **error-book** | `/teacher/error-book` | `ERROR_BOOK_ANALYTICS_READ` | 班级错题分析 |
| **practice** | `/teacher/practice` | `ADAPTIVE_PRACTICE_READ` | 专项练习统计 |
| **schedule** | `/teacher/schedule-changes` | `SCHEDULE_ADJUST` | 调课申请 |

---

### 2.3 student（学生）

| 模块 | 页面路由 | 权限点 | 功能说明 |
|------|----------|--------|----------|
| **dashboard** | `/student/dashboard` | `DASHBOARD_STUDENT_READ` | 学生仪表盘（作业/考试/成绩趋势） |
| **learning** | `/student/learning` | `CLASS_READ` | 学习中心 |
| | `/student/learning/assignments` | — | 作业列表 |
| | `/student/learning/assignments/[assignmentId]` | — | 作答 |
| | `/student/learning/assignments/[assignmentId]/result` | — | 作答结果 |
| | `/student/learning/courses` | `CLASS_READ` | 课程列表 |
| | `/student/learning/courses/[classId]` | `CLASS_READ` | 课程详情 |
| | `/student/learning/textbooks` | `TEXTBOOK_READ` | 教材 |
| | `/student/learning/textbooks/[id]` | `TEXTBOOK_READ` | 教材内容 |
| | `/student/learning/study-path` | `AI_CHAT` | AI 学习路径 |
| **grades** | `/student/grades` | `GRADE_RECORD_READ` | 成绩查询 |
| **error-book** | `/student/error-book` | `ERROR_BOOK_READ` | 我的错题本 |
| **practice** | `/student/practice` | `ADAPTIVE_PRACTICE_READ` | 专项练习 |
| | `/student/practice/[sessionId]` | `ADAPTIVE_PRACTICE_READ` | 练习对话 |
| **diagnostic** | `/student/diagnostic` | `DIAGNOSTIC_READ` | 学情诊断 |
| **elective** | `/student/elective` | `ELECTIVE_READ` | 选课 |
| | `/student/elective/[id]` | `ELECTIVE_READ` | 课程详情 |
| **schedule** | `/student/schedule` | `CLASS_READ` | 课表查看 |
| **attendance** | `/student/attendance` | `ATTENDANCE_READ` | 考勤查询 |
| **course-plans** | `/student/course-plans` | `COURSE_PLAN_READ` | 课程计划 |
| | `/student/course-plans/[id]` | `COURSE_PLAN_READ` | 计划详情 |
| **lesson-plans** | `/student/lesson-plans` | `LESSON_PLAN_READ` | 教案查看 |
| | `/student/lesson-plans/[planId]/view` | `LESSON_PLAN_READ` | 教案详情 |

---

### 2.4 parent（家长）

| 模块 | 页面路由 | 权限点 | 功能说明 |
|------|----------|--------|----------|
| **dashboard** | `/parent/dashboard` | `DASHBOARD_PARENT_READ` | 家长仪表盘（子女学习概况） |
| **children** | `/parent/children/[studentId]` | — | 子女详情聚合页 |
| **grades** | `/parent/grades` | `GRADE_RECORD_READ` | 子女成绩查询 |
| **error-book** | `/parent/error-book` | `ERROR_BOOK_READ` | 子女错题本 |
| **diagnostic** | `/parent/diagnostic` | `DIAGNOSTIC_READ` | 子女学情诊断 |
| **elective** | `/parent/elective` | `ELECTIVE_READ` | 子女选课查看 |
| **attendance** | `/parent/attendance` | `ATTENDANCE_READ` | 子女考勤查询 |
| **course-plans** | `/parent/course-plans` | `COURSE_PLAN_READ` | 课程计划 |
| | `/parent/course-plans/[id]` | `COURSE_PLAN_READ` | 计划详情 |
| **lesson-plans** | `/parent/lesson-plans` | `LESSON_PLAN_READ` | 教案查看 |
| | `/parent/lesson-plans/[planId]/view` | `LESSON_PLAN_READ` | 教案详情 |
| **practice** | `/parent/practice` | `ADAPTIVE_PRACTICE_READ` | 子女练习记录 |
| **leave** | `/parent/leave` | — | 请假申请 |

---

### 2.5 management（年级组长/教研组长）

| 模块 | 页面路由 | 权限点 | 功能说明 |
|------|----------|--------|----------|
| **grade** | `/management/grade` | `GRADE_MANAGE` | 年级管理首页 |
| | `/management/grade/dashboard` | `GRADE_RECORD_READ` | 年级仪表盘 |
| | `/management/grade/insights` | `GRADE_RECORD_READ` | 年级洞察分析 |
| | `/management/grade/classes` | `GRADE_MANAGE` | 年级班级管理 |
| | `/management/grade/practice` | `ADAPTIVE_PRACTICE_READ` | 年级练习统计 |

---

## 三、共享模块（所有角色可访问）

以下模块为所有已登录用户提供服务，不区分角色路由：

| 模块 | 路由 | 权限点 | 说明 |
|------|------|--------|------|
| **auth** | `/login`, `/register` | 公开 | 认证（登录/注册） |
| **onboarding** | `/onboarding` | 已登录 | 新手引导（首次登录） |
| **announcements** | `/announcements`, `/announcements/[id]` | `ANNOUNCEMENT_READ` | 公告查看（所有角色） |
| **messages** | `/messages`, `/messages/[id]`, `/messages/compose` | `MESSAGE_READ` / `MESSAGE_SEND` | 站内消息 |
| **profile** | `/profile` | `USER_PROFILE_UPDATE` | 个人资料 |
| **settings** | `/settings` | `USER_PROFILE_UPDATE` | 用户设置（通知/外观/安全） |
| **dashboard** | `/dashboard` | 角色自动路由 | 仪表盘（自动重定向到角色对应仪表盘） |
| **layout** | 所有路由 | — | 全局布局框架（侧边栏/顶部栏/导航配置） |
| **notifications** | 全局组件 | — | 通知弹窗/偏好管理（内嵌于 layout） |
| **files** | 全局上传 | `FILE_UPLOAD` | 文件上传（所有角色可上传，admin 可管理） |

---

## 四、权限点汇总（67 个）

| 权限分类 | 权限点 | 适用角色 |
|----------|--------|----------|
| **考试** | `exam:create/create/read/update/delete/duplicate/publish/ai_generate/submit` | teacher |
| | `exam:proctor/read` | teacher |
| **作业** | `homework:create/grade` | teacher |
| | `homework:submit` | student |
| **题库** | `question:create/read/update/delete` | admin, teacher |
| **教材** | `textbook:create/read/update/delete` | admin, teacher |
| **班级** | `class:create/read/update/delete/enroll/schedule` | admin, teacher, student |
| **学校管理** | `school:manage` | admin |
| | `grade:manage` | admin, grade_head |
| | `user:manage` | admin |
| **成绩** | `grade_record:manage/read` | admin, teacher, student, parent |
| **考勤** | `attendance:manage/read` | admin, teacher, student, parent |
| **课程计划** | `course_plan:manage/read` | admin, teacher, student, parent |
| **公告** | `announcement:manage` | admin |
| | `announcement:read` | all |
| **消息** | `message:send/read/delete` | all |
| **排课** | `schedule:auto/adjust` | admin, teacher |
| **选课** | `elective:manage/read/select` | admin, teacher, student, parent |
| **诊断** | `diagnostic:manage/read` | admin, teacher, student, parent |
| **备课** | `lesson_plan:create/read/update/delete/publish` | admin, teacher, student, parent |
| **仪表盘** | `dashboard:admin_read/teacher_read/student_read/parent_read` | 各角色独立 |
| **错题本** | `error_book:read/manage` | student, parent |
| | `error_book:analytics_read` | admin, teacher |
| **专项练习** | `adaptive_practice:read/manage` | student, teacher, parent, grade_head |
| **AI** | `ai:chat` | all |
| | `ai:configure` | admin |
| **文件** | `file:upload/read/delete` | all（upload），admin（delete） |
| **审计** | `audit_log:read` | admin |
| **RBAC** | `role:create/read/update/delete/assign` | admin |
| | `permission:read` | admin |
| **设置** | `settings:admin` | admin |
| | `user:profile_update` | all |

---

## 五、模块依赖关系速查

| 模块 | 依赖模块（通过 data-access） | 被依赖模块 |
|------|------------------------------|-----------|
| **exams** | questions, classes, school, homework | homework, dashboard, proctoring, diagnostic, grades |
| **homework** | exams, classes, school, users | grades, dashboard, diagnostic |
| **grades** | exams, classes, school, users | dashboard, parent |
| **classes** | homework, scheduling | exams, homework, grades, scheduling, attendance, dashboard |
| **dashboard** | users, classes, textbooks, questions, exams, homework | — |
| **parent** | classes, homework, grades | — |
| **diagnostic** | exams, questions, classes, users | — |
| **lesson-preparation** | textbooks, questions, exams, homework, classes, files | — |
| **messaging** | notifications | settings |
| **scheduling** | classes, users | — |
| **proctoring** | exams, users | — |
| **school** | — | exams, classes, grades, scheduling, attendance |
| **textbooks** | — | questions, exams, homework, lesson-preparation |
| **users** | — | all modules |
| **rbac** | — | admin |
| **audit** | — | all modules (via shared/audit-logger) |

---

## 六、维护说明

- 新增模块时，需同步更新本文档的模块-角色速查表（第一节）和对应角色的详细清单（第二节）
- 新增权限点时，需同步更新权限点汇总（第四节）
- 模块依赖关系变更时，需同步更新依赖关系速查（第五节）
- 路由变更时，需同步更新对应角色的路由表