# Next_Edu 架构影响地图

> 全模块·全函数·全参数级别
> 生成日期：2026-06-16
> 规则：每次文件修改后须同步更新本文档

---

## 模块：shared

### 模块职责
提供全项目共享的基础设施：数据库连接、Schema、工具函数、权限系统、UI 基础组件、通用 Hooks。

### 导出函数

#### `cn`
- 签名：`cn(...inputs: ClassValue[]): string`
- 参数说明：
  - `inputs`: ClassValue[]，来自 `clsx` + `tailwind-merge`，CSS 类名列表
- 功能：合并 CSS 类名并解决 Tailwind 冲突
- 依赖：`clsx`, `tailwind-merge`
- 被以下模块使用：**所有模块**的组件（50+ 文件）

#### `formatDate`
- 签名：`formatDate(date: string | Date, locale?: string): string`
- 参数说明：
  - `date`: string | Date，日期值
  - `locale`: string，默认 `"zh-CN"`，`Intl.DateTimeFormat` 的 locale
- 功能：国际化日期格式化
- 依赖：无
- 被以下模块使用：exams, homework, dashboard, textbooks

#### `parseAiChatPayload`
- 签名：`parseAiChatPayload(body: unknown): AiChatRequest`
- 参数说明：`body`: unknown，HTTP 请求体
- 功能：解析并校验 AI 聊天请求负载
- 依赖：Zod schema
- 被以下模块使用：`app/api/ai/chat/route.ts`

#### `encryptAiApiKey` / `decryptAiApiKey`
- 签名：`(value: string) => string`
- 功能：AES 加密/解密 AI Provider API Key
- 依赖：`crypto` (Node.js 内置)
- 被以下模块使用：settings (存储/读取 API Key)

#### `testAiProviderConfig` / `testAiProviderById`
- 签名：`(input: { apiKey, baseUrl?, model }) => Promise<boolean>` / `(providerId, overrides?) => Promise<boolean>`
- 功能：测试 AI Provider 连通性
- 依赖：`createAiChatCompletion`, `shared/db`
- 被以下模块使用：settings/actions.ts

#### `createAiChatCompletion`
- 签名：`(input: AiChatRequest) => Promise<{ content, usage }>`
- 功能：调用 AI 模型生成聊天回复
- 依赖：OpenAI SDK, `shared/db` (读取 provider 配置)
- 被以下模块使用：exams/ai-pipeline.ts, `app/api/ai/chat/route.ts`

#### `getAuthContext`
- 签名：`getAuthContext(): Promise<AuthContext>`
- 功能：获取当前用户的完整认证上下文（userId, roles, permissions, dataScope）
- 依赖：`auth` (NextAuth), `shared/db` (查询角色/班级/年级关系)
- 被以下模块使用：**所有业务模块**的 Server Actions

#### `requirePermission`
- 签名：`requirePermission(permission: Permission): Promise<AuthContext>`
- 参数说明：`permission`: Permission，来自 `shared/types/permissions` 的权限常量
- 功能：断言当前用户拥有指定权限，否则抛出 PermissionDeniedError
- 依赖：`getAuthContext`
- 被以下模块使用：**所有业务模块**的 Server Actions（exams, homework, questions, textbooks, classes, school, settings）

#### `checkPermission`
- 签名：`checkPermission(permission: Permission): Promise<{ allowed: boolean; ctx: AuthContext }>`
- 功能：非抛出版权限检查
- 依赖：`getAuthContext`
- 被以下模块使用：待扩展

#### `requireAuth`
- 签名：`requireAuth(): Promise<AuthContext>`
- 功能：仅断言用户已登录
- 依赖：`getAuthContext`
- 被以下模块使用：待扩展

#### `resolvePermissions`
- 签名：`resolvePermissions(roleNames: string[]): Permission[]`
- 参数说明：`roleNames`: string[]，用户的角色名称列表
- 功能：合并多角色的权限列表（去重）
- 依赖：`ROLE_PERMISSIONS` 常量
- 被以下模块使用：auth.ts (JWT callback)

### 导出组件

#### `AuthSessionProvider`
- Props: `{ children: React.ReactNode }`
- 内部使用：`next-auth/react` 的 `SessionProvider`
- 被使用：`app/layout.tsx`

#### `OnboardingGate`
- Props: 无（内部使用 `useSession`）
- 内部使用：`useSession`, `Permissions`, 多个 Server Action
- 功能：新用户引导流程（角色选择、学校/班级配置）
- 被使用：`app/layout.tsx`

#### `ThemeProvider`
- Props: `next-themes` 的 `ThemeProviderProps`
- 被使用：`app/layout.tsx`

#### `EmptyState`
- Props: `{ icon?, title, description, action? }`
- 被使用：exams, homework, questions, textbooks 等模块的列表空状态

### 导出 Hooks

#### `useActionWithToast`
- 签名：`useActionWithToast<T>(): { isPending, execute }`
- 功能：包装 Server Action + toast 反馈
- 被使用：待扩展

#### `useDebounce`
- 签名：`useDebounce<T>(value: T, delay?: number): T`
- 被使用：搜索输入框等

#### `useMediaQuery`
- 签名：`useMediaQuery(query: string): boolean`
- 被使用：响应式布局判断

#### `useLocalStorage`
- 签名：`useLocalStorage<T>(key: string, initialValue: T): [T, setter]`
- 被使用：exam-form (previewTaskStorageKey)

#### `usePermission`
- 签名：`usePermission(): { permissions, roles, hasPermission, hasAnyPermission, hasAllPermissions, hasRole }`
- 功能：客户端权限检查 Hook
- 被使用：layout/app-sidebar.tsx, exams/components, homework/components

### 类型/接口

#### `ActionState<T>`
- 定义：`{ success: boolean; message?: string; errors?: Record<string, string[]>; data?: T }`
- 被使用：**所有模块**的 Server Action 返回类型

#### `Permissions` (常量对象)
- 定义：22 个权限常量（`exam:create`, `homework:grade` 等）
- 被使用：auth-guard.ts, 所有模块的 actions.ts, 前端组件

#### `Permission` (类型)
- 定义：`Permissions` 值的联合类型
- 被使用：auth-guard.ts, use-permission.ts

#### `DataScope` (联合类型)
- 定义：`{ type: "all" } | { type: "owned"; userId: string } | { type: "class_taught"; classIds: string[]; subjectIds?: string[] } | { type: "grade_managed"; gradeIds: string[] } | { type: "class_members" } | { type: "children"; childrenIds: string[] }`
- 被使用：auth-guard.ts, exams/data-access.ts, homework/data-access.ts, dashboard/data-access.ts

#### `AuthContext` (接口)
- 定义：`{ userId: string; roles: string[]; permissions: Permission[]; dataScope: DataScope }`
- 被使用：auth-guard.ts, 所有调用 `requirePermission` 的 Server Action

#### `PermissionDeniedError` (类)
- 被使用：所有 Server Action 的 try/catch

### 数据库表 (shared/db/schema.ts)

| 表名 | 核心字段 | 被哪些模块使用 |
|------|---------|--------------|
| `users` | id, name, email, password, gradeId, departmentId, onboardedAt | auth, users, dashboard, classes |
| `accounts` | userId, provider, access_token | auth |
| `sessions` | userId, sessionToken | auth |
| `roles` | id, name | auth, auth-guard |
| `usersToRoles` | userId, roleId | auth, auth-guard |
| `rolePermissions` | roleId, permission | auth (seed) |
| `knowledgePoints` | id, name, chapterId, parentId | textbooks, questions |
| `questions` | id, content, type, authorId, parentId | questions, exams, homework |
| `questionsToKnowledgePoints` | questionId, knowledgePointId | questions |
| `subjects` | id, name, order | exams, textbooks |
| `textbooks` | id, title, subject, grade | textbooks |
| `chapters` | id, textbookId, title, parentId, content | textbooks |
| `departments` | id, name, description | school |
| `classrooms` | id, location, capacity | school |
| `academicYears` | id, name, startDate, endDate | school |
| `schools` | id, name, code | school, classes |
| `grades` | id, schoolId, name, gradeHeadId, teachingHeadId | school, classes, exams, auth-guard |
| `classes` | id, schoolId, gradeId, teacherId, name, invitationCode | classes, homework, auth-guard |
| `classSubjectTeachers` | classId, teacherId, subject | classes, auth-guard |
| `classEnrollments` | classId, studentId, status | classes, homework |
| `classSchedule` | id, classId, weekday, startTime, endTime, course | classes |
| `exams` | id, creatorId, title, subjectId, gradeId, status, structure | exams, homework |
| `examQuestions` | examId, questionId | exams |
| `examSubmissions` | examId, studentId, score | exams |
| `submissionAnswers` | submissionId, questionId, answer, score | exams |
| `homeworkAssignments` | id, creatorId, sourceExamId, title, status, dueAt | homework |
| `homeworkAssignmentQuestions` | assignmentId, questionId | homework |
| `homeworkAssignmentTargets` | assignmentId, studentId | homework |
| `homeworkSubmissions` | assignmentId, studentId, status, score | homework |
| `homeworkAnswers` | submissionId, questionId, answer, score, feedback | homework |
| `aiProviders` | id, provider, baseUrl, model, apiKeyEncrypted | settings, ai |

---

## 模块：auth

### 模块职责
处理用户认证（登录/注册/JWT/Session），提供 NextAuth 实例和中间件。

### 导出函数

#### `auth`
- 签名：`auth(): Promise<Session | null>` (NextAuth 导出)
- 功能：获取当前用户 Session
- 被使用：auth-guard.ts, 所有 Server Component 页面

#### `handlers`
- 签名：`{ GET, POST }` (NextAuth Route Handler)
- 被使用：`app/api/auth/[...nextauth]/route.ts`

#### `signIn` / `signOut`
- 被使用：login-form.tsx, site-header.tsx

#### `middleware` (proxy.ts)
- 签名：`middleware(request: NextRequest) => Promise<NextResponse>`
- 功能：基于权限点的路由守卫，未登录重定向 /login，无权限重定向角色首页
- 依赖：`getToken` (next-auth/jwt), `Permissions`
- 被使用：Next.js middleware 层

---

## 模块：exams

### 模块职责
考试全生命周期管理：创建（手动/AI）、编辑、预览、发布、删除、复制。

### 导出函数 (actions.ts)

#### `createExamAction`
- 签名：`(prevState: ActionState<string> | null, formData: FormData) => Promise<ActionState<string>>`
- 参数说明：`formData` 包含 mode, title, subject, grade, difficulty, totalScore, durationMin, scheduledAt
- 功能：手动模式创建考试草稿
- 依赖：`requirePermission(EXAM_CREATE)`, `shared/db`, `data-access.persistExamDraft`
- 被使用：exam-form.tsx

#### `createAiExamAction`
- 签名：同上
- 功能：AI 模式创建考试（调用 AI pipeline 生成题目）
- 依赖：`requirePermission(EXAM_AI_GENERATE)`, `ai-pipeline.generateAiCreateDraftFromSource`, `data-access.persistAiGeneratedExamDraft`
- 被使用：exam-form.tsx

#### `previewAiExamAction`
- 签名：`(prevState: ActionState<AiPreviewData> | null, formData: FormData) => Promise<ActionState<AiPreviewData>>`
- 功能：AI 预览试卷（不持久化）
- 依赖：`requirePermission(EXAM_AI_GENERATE)`, `ai-pipeline.generateAiPreviewData`
- 被使用：exam-ai-generator.tsx (via useExamPreview)

#### `regenerateAiQuestionAction`
- 签名：`(prevState: ActionState<AiRewriteQuestionData> | null, formData: FormData) => Promise<ActionState<AiRewriteQuestionData>>`
- 功能：AI 重写单个题目
- 依赖：`requirePermission(EXAM_AI_GENERATE)`, `ai-pipeline.regenerateAiQuestionByInstruction`
- 被使用：exam-preview-question-editor.tsx

#### `updateExamAction`
- 签名：`(prevState: ActionState<string> | null, formData: FormData) => Promise<ActionState<string>>`
- 功能：更新考试信息，含资源归属校验（非 admin 只能改自己的）
- 依赖：`requirePermission(EXAM_UPDATE)`, `shared/db`
- 被使用：exam-form.tsx

#### `deleteExamAction`
- 签名：同上
- 功能：删除考试，含资源归属校验
- 依赖：`requirePermission(EXAM_DELETE)`, `shared/db`
- 被使用：exam-actions.tsx

#### `duplicateExamAction`
- 签名：同上
- 功能：复制考试
- 依赖：`requirePermission(EXAM_DUPLICATE)`, `shared/db`
- 被使用：exam-actions.tsx

#### `getSubjectsAction`
- 签名：`() => Promise<ActionState<{ id: string; name: string }[]>>`
- 依赖：`requirePermission(EXAM_READ)`, `shared/db`
- 被使用：exam-form.tsx

#### `getGradesAction`
- 签名：同上
- 依赖：`requirePermission(EXAM_READ)`, `shared/db`
- 被使用：exam-form.tsx

### 导出函数 (data-access.ts)

#### `getExams`
- 签名：`getExams(params: GetExamsParams & { scope: DataScope }): Promise<Exam[]>`
- 参数说明：`scope` 来自 `auth-guard.getAuthContext().dataScope`
- 功能：查询考试列表，含数据权限过滤
- 依赖：`shared/db`, `DataScope`
- 被使用：teacher/exams/all/page.tsx, homework 创建页面

#### `getExamById`
- 签名：`getExamById(id: string, scope?: DataScope): Promise<Exam | null>`
- 被使用：exam 详情/编辑页面

#### `persistExamDraft` / `persistAiGeneratedExamDraft`
- 被使用：createExamAction, createAiExamAction

### 导出函数 (ai-pipeline.ts)

#### `generateAiPreviewData`
- 签名：`(input: { title, subject?, grade?, difficulty, totalScore, durationMin, questionCount?, sourceText, aiProviderId? }) => Promise<{ ok, data?, rawOutput?, message? }>`
- 依赖：`shared/lib/ai.createAiChatCompletion`
- 被使用：previewAiExamAction

#### `generateAiCreateDraftFromSource`
- 被使用：createAiExamAction

#### `regenerateAiQuestionByInstruction`
- 被使用：regenerateAiQuestionAction

### 类型/接口

#### `Exam`
- 被使用：exams/components, homework/types (sourceExam), dashboard/types

#### `AiPreviewData` / `AiRewriteQuestionData`
- 被使用：exams/actions.ts, exams/components

---

## 模块：homework

### 模块职责
作业全生命周期：创建（源自考试）、发布、学生作答、教师批改、数据分析。

### 导出函数 (actions.ts)

#### `createHomeworkAssignmentAction`
- 签名：`(prevState: ActionState<string> | null, formData: FormData) => Promise<ActionState<string>>`
- 功能：从已有考试创建作业
- 依赖：`requirePermission(HOMEWORK_CREATE)`, `shared/db`, `exams/data-access.getExams`
- 被使用：homework-assignment-form.tsx

#### `startHomeworkSubmissionAction`
- 签名：同上
- 功能：学生开始作答
- 依赖：`requirePermission(HOMEWORK_SUBMIT)`, `shared/db`
- 被使用：homework-take-view.tsx

#### `saveHomeworkAnswerAction`
- 签名：同上
- 功能：保存单题答案
- 依赖：`requirePermission(HOMEWORK_SUBMIT)`, `shared/db`
- 被使用：homework-take-view.tsx

#### `submitHomeworkAction`
- 签名：同上
- 功能：提交作业
- 依赖：`requirePermission(HOMEWORK_SUBMIT)`, `shared/db`
- 被使用：homework-take-view.tsx

#### `gradeHomeworkSubmissionAction`
- 签名：同上
- 功能：教师批改作业
- 依赖：`requirePermission(HOMEWORK_GRADE)`, `shared/db`
- 被使用：homework-grading-view.tsx

### 导出函数 (data-access.ts)

#### `getHomeworkAssignments`
- 签名：`(params?: { creatorId?, ids?, classId?, scope? }) => Promise<HomeworkAssignmentListItem[]>`
- 依赖：`shared/db`, `DataScope`
- 被使用：teacher 作业列表页, homework-assignment-form.tsx

#### `getStudentHomeworkAssignments`
- 签名：`(studentId: string) => Promise<StudentHomeworkAssignmentListItem[]>`
- 被使用：student/dashboard

#### `getStudentDashboardGrades`
- 签名：`(studentId: string) => Promise<StudentDashboardGradeProps>`
- 被使用：dashboard/data-access.ts (学生仪表盘)

#### `getHomeworkAssignmentAnalytics`
- 签名：`(assignmentId: string) => Promise<HomeworkAssignmentAnalytics | null>`
- 被使用：homework 错误分析组件

### 类型/接口

#### `StudentDashboardGradeProps`
- 被使用：dashboard/types.ts (StudentDashboardProps.grades)

#### `HomeworkAssignmentListItem`
- 被使用：homework 列表页, homework-assignment-form.tsx

---

## 模块：questions

### 模块职责
题库管理：题目 CRUD、知识点关联、题型支持（选择/填空/判断/复合）。

### 导出函数 (actions.ts)

#### `createNestedQuestion`
- 签名：`(prevState: ActionState<string> | undefined, formData: FormData | CreateQuestionInput) => Promise<ActionState<string>>`
- 依赖：`requirePermission(QUESTION_CREATE)`, `shared/db`
- 被使用：create-question-dialog.tsx

#### `updateQuestionAction`
- 签名：同上
- 依赖：`requirePermission(QUESTION_UPDATE)`, `shared/db`
- 被使用：question-actions.tsx

#### `deleteQuestionAction`
- 签名：同上
- 依赖：`requirePermission(QUESTION_DELETE)`, `shared/db`
- 被使用：question-actions.tsx

#### `getQuestionsAction`
- 签名：`(params: GetQuestionsParams) => Promise<...>`
- 依赖：`requirePermission(QUESTION_READ)`, `data-access.getQuestions`
- 被使用：teacher/questions/page.tsx

#### `getKnowledgePointOptionsAction`
- 签名：`() => Promise<KnowledgePointOption[]>`
- 依赖：`requirePermission(QUESTION_READ)`, `shared/db`
- 被使用：create-question-dialog.tsx

### 类型/接口

#### `Question`
- 被使用：exams (题目选择), homework (作业题目)

#### `KnowledgePointOption`
- 被使用：create-question-dialog.tsx

---

## 模块：textbooks

### 模块职责
教材与知识体系管理：教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱。

### 导出函数 (actions.ts)

| 函数 | 权限 | 核心功能 |
|------|------|---------|
| `createTextbookAction` | TEXTBOOK_CREATE | 创建教材 |
| `updateTextbookAction` | TEXTBOOK_UPDATE | 更新教材元信息 |
| `deleteTextbookAction` | TEXTBOOK_DELETE | 删除教材 |
| `createChapterAction` | TEXTBOOK_CREATE | 创建章节 |
| `updateChapterContentAction` | TEXTBOOK_UPDATE | 更新章节内容(Markdown) |
| `deleteChapterAction` | TEXTBOOK_DELETE | 删除章节 |
| `createKnowledgePointAction` | TEXTBOOK_CREATE | 创建知识点 |
| `updateKnowledgePointAction` | TEXTBOOK_UPDATE | 更新知识点 |
| `deleteKnowledgePointAction` | TEXTBOOK_DELETE | 删除知识点 |
| `reorderChaptersAction` | TEXTBOOK_UPDATE | 章节排序 |

### 导出函数 (data-access.ts)

| 函数 | 签名 | 被使用 |
|------|------|--------|
| `getTextbooks` | `(query?, subject?, grade?) => Promise<Textbook[]>` | teacher/textbooks/page.tsx |
| `getTextbookById` | `(id: string) => Promise<Textbook \| undefined>` | teacher/textbooks/[id]/page.tsx |
| `getChaptersByTextbookId` | `(textbookId: string) => Promise<Chapter[]>` | textbook-reader.tsx |
| `getKnowledgePointsByChapterId` | `(chapterId: string) => Promise<KnowledgePoint[]>` | textbook-reader.tsx |
| `getKnowledgePointsByTextbookId` | `(textbookId: string) => Promise<KnowledgePoint[]>` | textbook-reader.tsx |

### 导出 Hooks

#### `useTextSelection`
- 签名：`useTextSelection(contentRef, onCreateKnowledgePoint) => { selectedText, createDialogOpen, isCreating, handleContentPointerDown, handleContextMenuChange }`
- 被使用：textbook-content-panel.tsx

#### `useKnowledgePointActions`
- 签名：`useKnowledgePointActions(textbookId, selectedChapterId, highlightedKpId, setHighlightedKpId) => { editingKp, editKpDialogOpen, ..., requestDeleteKnowledgePoint, confirmDeleteKnowledgePoint, handleUpdateKnowledgePoint }`
- 被使用：textbook-reader.tsx

### 类型/接口

#### `Chapter`
- 被使用：textbooks/components, questions (知识点关联)

#### `KnowledgePoint`
- 被使用：textbooks/components, questions/types (KnowledgePointOption)

---

## 模块：classes

### 模块职责
班级管理：班级 CRUD、学生注册/退班、邀请码、课表、学科教师分配。

### 导出函数 (actions.ts)

| 函数 | 权限 | 核心功能 |
|------|------|---------|
| `createTeacherClassAction` | CLASS_CREATE | 教师创建班级 |
| `updateTeacherClassAction` | CLASS_UPDATE | 教师更新班级 |
| `deleteTeacherClassAction` | CLASS_DELETE | 教师删除班级 |
| `createGradeClassAction` | CLASS_CREATE | 年级主任创建班级 |
| `updateGradeClassAction` | CLASS_UPDATE | 年级主任更新班级 |
| `deleteGradeClassAction` | CLASS_DELETE | 年级主任删除班级 |
| `enrollStudentByEmailAction` | CLASS_ENROLL | 通过邮箱注册学生 |
| `joinClassByInvitationCodeAction` | CLASS_ENROLL | 通过邀请码加入 |
| `ensureClassInvitationCodeAction` | CLASS_ENROLL | 确保邀请码存在 |
| `regenerateClassInvitationCodeAction` | CLASS_ENROLL | 重新生成邀请码 |
| `setStudentEnrollmentStatusAction` | CLASS_ENROLL | 设置学生状态 |
| `createClassScheduleItemAction` | CLASS_SCHEDULE | 创建课表项 |
| `updateClassScheduleItemAction` | CLASS_SCHEDULE | 更新课表项 |
| `deleteClassScheduleItemAction` | CLASS_SCHEDULE | 删除课表项 |
| `createAdminClassAction` | CLASS_CREATE | 管理员创建班级 |
| `updateAdminClassAction` | CLASS_UPDATE | 管理员更新班级 |
| `deleteAdminClassAction` | CLASS_DELETE | 管理员删除班级 |

### 导出函数 (data-access.ts)

| 函数 | 被使用 |
|------|--------|
| `getTeacherClasses(teacherId?)` | teacher/classes/my/page.tsx, dashboard |
| `getAdminClasses()` | admin 班级管理 |
| `getGradeManagedClasses(userId)` | grade_head 班级管理 |
| `getStudentClasses(studentId)` | student/dashboard |
| `getStudentSchedule(studentId)` | student 课表 |
| `getClassStudents(classId, scope?)` | teacher/classes/students/page.tsx |
| `getClassSchedule(classId)` | teacher/classes/schedule/page.tsx |
| `getClassHomeworkInsights(classId)` | classes 作业洞察 |
| `getGradeHomeworkInsights(gradeId)` | 年级作业洞察 |

---

## 模块：school

### 模块职责
学校基础数据管理：学校、年级、部门、学年的 CRUD。

### 导出函数 (actions.ts)

| 函数 | 权限 | 核心功能 |
|------|------|---------|
| `createSchoolAction` | SCHOOL_MANAGE | 创建学校 |
| `updateSchoolAction` | SCHOOL_MANAGE | 更新学校 |
| `deleteSchoolAction` | SCHOOL_MANAGE | 删除学校 |
| `createGradeAction` | GRADE_MANAGE | 创建年级 |
| `updateGradeAction` | GRADE_MANAGE | 更新年级 |
| `deleteGradeAction` | GRADE_MANAGE | 删除年级 |
| `createDepartmentAction` | SCHOOL_MANAGE | 创建部门 |
| `updateDepartmentAction` | SCHOOL_MANAGE | 更新部门 |
| `deleteDepartmentAction` | SCHOOL_MANAGE | 删除部门 |
| `createAcademicYearAction` | SCHOOL_MANAGE | 创建学年 |
| `updateAcademicYearAction` | SCHOOL_MANAGE | 更新学年 |
| `deleteAcademicYearAction` | SCHOOL_MANAGE | 删除学年 |

### 导出函数 (data-access.ts)

| 函数 | 被使用 |
|------|--------|
| `getSchools()` | admin 学校管理, onboarding |
| `getGrades()` | admin 年级管理, exams, onboarding |
| `getDepartments()` | admin 部门管理 |
| `getAcademicYears()` | admin 学年管理 |
| `getStaffOptions()` | school 组件 (年级主任选择) |
| `getGradesForStaff(staffId)` | grade_head 视图 |

---

## 模块：dashboard

### 模块职责
各角色仪表盘数据聚合与展示。

### 导出函数 (data-access.ts)

#### `getAdminDashboardData`
- 签名：`getAdminDashboardData(scope?: DataScope): Promise<AdminDashboardData>`
- 依赖：`shared/db`, `DataScope`
- 被使用：admin/dashboard/page.tsx

### 类型/接口

#### `StudentDashboardProps`
- 被使用：student-dashboard-view.tsx
- 依赖：`homework/types.StudentDashboardGradeProps`

#### `TeacherDashboardData`
- 被使用：teacher-dashboard-view.tsx
- 依赖：`homework/data-access.getTeacherGradeTrends`, `classes/data-access.getTeacherClasses`

---

## 模块：layout

### 模块职责
应用布局框架：侧边栏、顶栏、导航配置。

### 导出组件

#### `AppSidebar`
- 内部使用：`usePermission`, `NAV_CONFIG`
- 功能：根据权限渲染侧边栏导航

#### `SiteHeader`
- 内部使用：`useSession`, `signOut`
- 功能：顶部导航栏

### 导出配置

#### `NAV_CONFIG`
- 类型：`Record<string, NavItem[]>`
- 每个NavItem含 `permission?: string` 字段
- 被使用：app-sidebar.tsx

---

## 模块：settings

### 模块职责
系统设置：AI Provider 配置、用户偏好。

### 导出函数 (actions.ts)

| 函数 | 权限 | 核心功能 |
|------|------|---------|
| `getAiProviderSummaries()` | AI_CONFIGURE | 获取 AI Provider 列表 |
| `upsertAiProviderAction(data)` | AI_CONFIGURE | 创建/更新 AI Provider |
| `testAiProviderAction(data)` | AI_CONFIGURE | 测试 AI Provider 连通性 |

---

## 模块间依赖矩阵

| ↓ 使用 → | shared | auth | exams | homework | questions | textbooks | classes | school | dashboard | layout | settings |
|----------|--------|------|-------|----------|-----------|-----------|---------|--------|-----------|--------|----------|
| **shared** | - | - | - | - | - | - | - | - | - | - | - |
| **auth** | db,schema,permissions | - | - | - | - | - | - | - | - | - | - |
| **exams** | db,auth-guard,types,ai | auth | - | - | - | - | - | - | - | - | - |
| **homework** | db,auth-guard,types | auth | data-access.getExams | - | - | - | schema | - | - | - | - |
| **questions** | db,auth-guard,types | auth | - | - | - | - | - | - | - | - | - |
| **textbooks** | db,auth-guard,types | auth | - | - | - | - | - | - | - | - | - |
| **classes** | db,auth-guard,types | auth | - | homework-insights | - | - | - | - | - | - | - |
| **school** | db,auth-guard,types | auth | - | - | - | - | - | - | - | - | - |
| **dashboard** | db,types | auth | - | data-access.getTeacherGradeTrends,getStudentDashboardGrades | - | - | data-access.getTeacherClasses,getStudentClasses,getStudentSchedule | - | - | - | - |
| **layout** | hooks.usePermission | auth(useSession) | - | - | - | - | - | - | - | - | - |
| **settings** | db,auth-guard,ai,types | auth | - | - | - | - | - | - | - | - | - |

---

## 关键参数影响链

### `userId`
1. 由 `auth.ts` JWT callback 从 `users` 表查询产生，存入 JWT
2. 通过 `session.user.id` 传递到所有 Server Components 和 Client Components
3. 通过 `getAuthContext().userId` 传递到所有 Server Actions
4. 在 `auth-guard.ts` 中用于查询 `usersToRoles`（获取角色）和 `classSubjectTeachers`/`grades`（获取 DataScope）
5. 在 exams/actions.ts 中作为 `creatorId` 写入 `exams` 表
6. 在 homework/actions.ts 中作为 `creatorId` 写入 `homeworkAssignments` 表
7. 在 classes/data-access.ts 中查询 `getTeacherClasses(teacherId)` 和 `getGradeManagedClasses(userId)`

### `examId`
1. 由 `exams/actions.ts` 的 `createExamAction` 产生，通过 CUID2 生成，写入 `exams` 表
2. 被 `exams/data-access.getExamById(id)` 读取
3. 被 `exams/actions.ts` 的 `updateExamAction`/`deleteExamAction`/`duplicateExamAction` 用于定位考试
4. 传入 `homework/actions.ts` 的 `createHomeworkAssignmentAction` 的 `sourceExamId` 参数
5. 在 `homeworkAssignments` 表中作为外键关联到源考试
6. 被 `homework/data-access.getHomeworkAssignmentAnalytics` 用于追溯作业来源

### `classId`
1. 由 `classes/actions.ts` 的 `createTeacherClassAction`/`createAdminClassAction` 产生
2. 被 `classes/data-access.getClassStudents(classId)` 读取学生列表
3. 被 `classes/data-access.getClassSchedule(classId)` 读取课表
4. 被 `classes/data-access.getClassHomeworkInsights(classId)` 读取作业洞察
5. 被 `homework/data-access.getHomeworkAssignments({ classId })` 过滤作业列表
6. 在 `auth-guard.ts` 中通过 `classSubjectTeachers` 查询教师关联的 classIds，构建 `DataScope.class_taught`

### `permission`
1. 由 `shared/types/permissions.ts` 的 `Permissions` 常量定义（22 个权限点）
2. 在 `shared/lib/permissions.ts` 中通过 `ROLE_PERMISSIONS` 映射角色到权限列表
3. 在 `auth.ts` JWT callback 中通过 `resolvePermissions(roleNames)` 合并多角色权限，存入 JWT
4. 在 `proxy.ts` middleware 中通过 `token.permissions` 检查路由访问权限
5. 在 `shared/lib/auth-guard.ts` 中通过 `requirePermission(permission)` 在 Server Action 层断言权限
6. 在 `shared/hooks/use-permission.ts` 中通过 `hasPermission(permission)` 在客户端组件中条件渲染
7. 在 `layout/config/navigation.ts` 中作为 `NavItem.permission` 字段过滤侧边栏菜单

### `DataScope`
1. 由 `auth-guard.ts` 的 `resolveDataScope(userId, roles)` 根据用户角色和 DB 关系动态计算
2. 传递到 `exams/data-access.getExams({ scope })` 进行行级过滤
3. 传递到 `homework/data-access.getHomeworkAssignments({ scope })` 进行行级过滤
4. 传递到 `dashboard/data-access.getAdminDashboardData(scope)` 进行统计过滤
5. 在 exams/actions.ts 的 `updateExamAction`/`deleteExamAction` 中用于判断是否需要资源归属校验（`scope.type !== "all"`）