xiner/NextEdu
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity
Files
125f7ec54cb3beef26475977252d7dfe54b4ed75
NextEdu/docs/architecture/004_architecture_impact_map.md
SpecialX 125f7ec54c
Some checks failed
CI / build-deploy (push) Has been cancelled
Details
refactor: RBAC权限系统重构 + UI组件拆分 + 测试修复 + 架构文档 
- 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、代码分割
2026-06-16 23:38:33 +08:00

683 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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"`）
Reference in New Issue View Git Blame Copy Permalink