docs: 全项目架构审查与文档体系重写

- 全项目逐文件审查: 4 份审计报告(shared/core-business/management/new-modules)
- 重写 004 架构影响地图: 图优先 + 模块依赖图 + 数据流 + 调用链 + 问题分级
- 更新 005 结构化数据: 新增 architectureOverview/moduleDependencyGraph/knownIssues/dbTables 节点
- 更新 006 功能清单: 143 项功能标注实现状态, P0 覆盖率 80%->92%
- 更新 007 差距审计: v2->v3, P0 完成 69%->84%, 新增架构技术债章节
- 更新 001 项目概览: 6 角色/54 权限/26 模块/54 表
- 新增 docs/README.md 文档索引
- 归档 11 份过时文档(002x2/003/designx8) 标注
- 更新 work_log

docs/architecture/audit/00_summary.md

@@ -0,0 +1,132 @@
+# 架构审查汇总报告
+
+> 基于对全项目 69+ 文件的逐文件审查,汇总关键架构问题。
+> 审查日期: 2026-06-17
+> 子报告:
+> - [shared 基础设施层审查](./shared-audit.md)
+> - [核心业务模块审查](./core-business-audit.md)
+> - [管理模块群审查](./management-modules-audit.md)
+> - [新增模块和其他模块审查](./new-and-other-modules-audit.md)
+
+---
+
+## 一、总体评估
+
+| 维度 | 状态 | 说明 |
+|------|------|------|
+| 模块化程度 | ⚠️ 中等 | 20+ 模块划分合理,但跨模块直接 DB 查询普遍存在 |
+| 职责单一性 | ⚠️ 中等 | 多数模块职责清晰,但 5 个文件超 1000 行硬上限 |
+| 架构文档质量 | ❌ 不足 | 004 文档按模块罗列函数,缺乏关系图/数据流/调用链 |
+| 循环依赖 | ❌ 存在 | shared/lib ↔ auth 循环依赖 |
+| 死代码 | ⚠️ 少量 | proctoring/exam-mode-config.tsx 未集成 |
+
+**核心结论**: 架构设计思路正确(模块化 + 分层),但执行不够严格。主要问题是跨模块直接 DB 查询破坏了模块封装,以及少数文件过大。
+
+---
+
+## 二、P0 严重问题(必须修复)
+
+### 1. 文件超 1000 行硬上限(3 个文件)
+
+| 文件 | 行数 | 问题 |
+|------|------|------|
+| `classes/data-access.ts` | 2104 | 混入 homework/scheduling/grades 逻辑 |
+| `homework/data-access.ts` | 1038 | 混入排名计算业务逻辑 |
+| `shared/db/schema.ts` | 1111 | 54 张表混合(可接受,但需分节) |
+
+### 2. 循环依赖
+
+```
+shared/lib/{audit-logger, change-logger, auth-guard}
+    → @/auth (src/auth.ts)
+    → shared/lib/* (循环)
+```
+
+### 3. dashboard 跨模块直接查询 11 张表
+
+`dashboard/data-access.ts` 的 `getAdminDashboardData` 直查 sessions/users/classes/textbooks/chapters/questions/exams/homeworkAssignments/homeworkSubmissions/usersToRoles/roles,严重违反模块封装。
+
+### 4. messaging 绕过 notifications 直接写通知
+
+`messaging/actions.ts` 第 66-72 行直接调用 `createNotification`,导致用户通知偏好失效、多渠道通知无效。
+
+### 5. classSchedule 表三处写入口
+
+- `classes/data-access.ts`
+- `scheduling/actions.ts` (直接 transaction 写入)
+- `scheduling/data-access.ts`
+
+数据完整性高风险。
+
+---
+
+## 三、P1 较严重问题
+
+### 6. 跨模块直接 DB 查询普遍存在
+
+| 被访问表 | 访问次数 | 应归属模块 | 主要违规者 |
+|---------|---------|-----------|-----------|
+| `classes` | 8+ | classes | exams, homework, grades, dashboard |
+| `classEnrollments` | 6+ | classes | homework, grades, attendance |
+| `users` | 6+ | users | 多个模块 |
+| `subjects` | 6+ | school | exams, homework, questions |
+| `exams` | 5+ | exams | homework, grades, dashboard |
+
+### 7. actions 层混入数据访问逻辑
+
+exams/homework/questions/announcements 的 actions.ts 中存在直接 `db.insert/update/delete`,应该通过 data-access 层。
+
+### 8. auth.ts 混合 5 类职责
+
+NextAuth 配置 + 密码安全 DB 操作 + 角色规范化 + IP 解析 + 回调函数,应拆分。
+
+### 9. users/import-export.ts 四重职责
+
+导入解析 + 导出 + 用户创建(含密码哈希) + 班级注册(跨模块写 classEnrollments)。
+
+### 10. proctoring 死代码
+
+`exam-mode-config.tsx` 组件已创建但未集成到考试表单,DB schema 有 examMode 字段但表单不收集。
+
+---
+
+## 四、架构文档问题
+
+### 当前 004 文档的问题
+
+1. **按模块罗列函数签名**,缺乏全局视角
+2. **缺少模块依赖关系图**,无法直观看出模块间如何协作
+3. **缺少数据流向图**,不知道数据如何在模块间流动
+4. **缺少调用链路**,不知道一个请求从 API 到 DB 的完整路径
+5. **缺少分层架构说明**,不知道 shared/modules/app 的层次关系
+6. **未标注循环依赖**,给人虚假的"架构清晰"印象
+
+### 理想的架构文档应该
+
+1. **一图胜千言**: 用 ASCII/Mermaid 图展示模块关系
+2. **分层清晰**: shared → modules → app 三层,依赖方向单向
+3. **数据流明确**: 标注每个核心业务的数据从哪来、到哪去
+4. **调用链完整**: 关键 API 的完整调用路径
+5. **问题标注**: 明确标注已知的耦合问题和技术债
+
+---
+
+## 五、解耦优先级
+
+### 立即执行(P0)
+1. 拆分 `classes/data-access.ts`(2104 行 → 按职责拆 3-4 个文件)
+2. 拆分 `homework/data-access.ts`(1038 行 → 分离排名逻辑)
+3. 修复 shared/lib ↔ auth 循环依赖
+4. dashboard 改为通过各模块 data-access 获取数据
+5. messaging 写通知改为通过 notifications dispatcher
+
+### 短期执行(P1)
+6. 统一 classSchedule 写入口到 scheduling 模块
+7. actions 层移除直接 DB 操作
+8. 拆分 auth.ts
+9. 集成 proctoring/exam-mode-config 到考试表单
+10. 拆分 users/import-export.ts
+
+### 中期执行(P2)
+11. 建立模块间数据访问规范(通过对方 data-access 或导出查询函数)
+12. schema.ts 按业务域分节(加注释分隔)

docs/architecture/audit/core-business-audit.md

@@ -0,0 +1,417 @@
+# 核心业务模块职责与耦合审查报告
+
+> 审计日期：2026-06-17
+> 审计范围：`src/modules/exams`、`src/modules/homework`、`src/modules/questions`、`src/modules/textbooks`、`src/modules/grades`
+> 审计目标：识别职责不单一和过耦合问题，重点关注跨模块直接数据库查询（违反模块封装）
+> 审计依据：项目规则（`.trae/rules/project_rules.md`）、架构影响地图（004/005）
+
+---
+
+## 一、总体结论
+
+| 维度 | 状态 | 说明 |
+|------|------|------|
+| 模块职责边界 | ⚠️ 部分违规 | homework 混入考试/班级逻辑；grades 混入班级/用户逻辑 |
+| data-access 层职责 | ❌ 普遍违规 | 5 个模块均存在跨模块直接 DB 查询；homework/data-access.ts 混入排名业务逻辑 |
+| actions 层职责 | ⚠️ 部分违规 | exams/homework/questions 的 actions 直接访问 DB；textbooks/grades 的 actions 设计良好 |
+| 组件耦合 | ✅ 基本合规 | 组件层跨模块依赖均为类型导入或 UI 组合，无直接 data-access 调用 |
+| 跨模块依赖 | ⚠️ 存在风险 | 无循环依赖，但 exams→questions、homework→exams、grades→classes 的直接 DB 访问破坏封装 |
+| 文件行数 | ❌ 存在违规 | homework/data-access.ts 1038 行（超 1000 硬上限）；exams/ai-pipeline.ts 912 行、exams/actions.ts 832 行（超 800 建议值） |
+
+### 关键风险项
+
+1. **homework/data-access.ts 超过 1000 行硬上限**（1038 行）—— 必须拆分
+2. **5 个模块均存在跨模块直接 DB 查询** —— 违反模块封装原则
+3. **exams/homework/questions 的 actions 层混入数据访问逻辑** —— 应只做编排
+4. **homework/data-access.ts 混入排名计算业务逻辑** —— data-access 应只负责数据存取
+
+---
+
+## 二、模块依赖关系图
+
+```
+                    ┌──────────────┐
+                    │  textbooks   │ ← 被引用方（知识点/章节）
+                    └──────┬───────┘
+                           │
+            ┌──────────────┼──────────────┐
+            │              │              │
+            ▼              ▼              ▼
+     ┌────────────┐  ┌──────────┐  ┌────────────┐
+     │ questions  │  │  exams   │  │  homework  │
+     └─────┬──────┘  └────┬─────┘  └─────┬──────┘
+           │              │              │
+           │   ┌──────────┘              │
+           │   │                          │
+           ▼   ▼                          ▼
+     ┌────────────────┐            ┌──────────┐
+     │    grades      │            │  classes │
+     └────────────────┘            └──────────┘
+```
+
+### 依赖关系明细
+
+| 依赖方向 | 类型 | 合理性 | 问题 |
+|---------|------|--------|------|
+| exams → questions | data-access + 类型 + action | ⚠️ 部分合理 | 类型导入合理；但 `persistAiGeneratedExamDraft` 直接 insert 到 questions 表，应通过 questions/data-access |
+| exams → classes | data-access | ❌ 不合理 | `getExams`/`getExamById` 直接查询 classes 表获取教师 gradeIds，应通过 classes/data-access |
+| exams → school | actions | ❌ 不合理 | `getSubjectsAction`/`getGradesAction` 直接查询 subjects/grades 表，应通过 school/data-access |
+| homework → exams | data-access + 组件 | ⚠️ 部分合理 | 业务上 homework 引用 exam（sourceExamId）合理；但直接查询 exams 表应改为调用 exams/data-access |
+| homework → classes | data-access + actions | ❌ 不合理 | 直接查询 classes/classEnrollments/classSubjectTeachers 表，应通过 classes/data-access |
+| homework → questions | data-access | ✅ 合理 | 通过 Drizzle 关系查询 homeworkAssignmentQuestions.question，未直接访问 questions 表 |
+| grades → exams | 无 | ✅ 合理 | grades 仅通过 examId 外键引用，不直接查询 exams 表 |
+| grades → homework | 无 | ✅ 合理 | grades 仅通过 type 枚举值 "homework" 引用，不直接查询 homework 表 |
+| grades → classes | data-access | ❌ 不合理 | 多个 data-access 文件直接查询 classes/classEnrollments 表 |
+| grades → users/subjects | data-access | ❌ 不合理 | 直接查询 users/subjects 表获取关联名称，应通过对应模块 data-access |
+| questions → textbooks | actions | ❌ 不合理 | `getKnowledgePointOptionsAction` 直接查询 knowledgePoints/chapters/textbooks 表 |
+| textbooks → questions | 组件 | ✅ 合理 | `knowledge-point-dialogs.tsx` 导入 CreateQuestionDialog 组件，属于 UI 组合 |
+
+### 循环依赖分析
+
+- **无直接循环依赖**：模块间的 data-access 依赖是单向的
+- **潜在风险**：exams → questions（data-access）与 questions → textbooks（actions）与 textbooks → questions（组件）形成链式依赖，但因 textbooks→questions 仅为组件层导入，不构成 data-access 层的循环依赖
+
+---
+
+## 三、各模块审查明细
+
+### 3.1 exams 模块
+
+#### 文件行数
+
+| 文件 | 行数 | 限制 | 状态 |
+|------|------|------|------|
+| actions.ts | 832 | ≤800 | ⚠️ 超限 |
+| ai-pipeline.ts | 912 | ≤800 | ⚠️ 超限 |
+| data-access.ts | 339 | ≤800 | ✅ |
+| types.ts | 31 | 无限制 | ✅ |
+| hooks/use-exam-preview.ts | 295 | ≤500 | ✅ |
+
+#### 模块职责边界
+
+- **职责**：考试全生命周期管理（创建/编辑/预览/发布/删除/复制）+ AI 辅助出题
+- **问题**：`getSubjectsAction`/`getGradesAction` 属于 school 模块职责，被放在 exams/actions.ts 中
+
+#### data-access 层问题
+
+| 函数 | 问题 | 严重程度 |
+|------|------|---------|
+| `getExams` | 直接查询 `classes` 表获取教师 gradeIds（第 71-78 行） | 高 |
+| `getExamById` | 直接查询 `classes` 表获取教师 gradeIds（第 155-159 行） | 高 |
+| `persistAiGeneratedExamDraft` | 直接 insert 到 `questions` 表（第 317-326 行） | 高 |
+
+#### actions 层问题
+
+| 函数 | 问题 | 严重程度 |
+|------|------|---------|
+| `updateExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete`/`db.insert`/`db.update` 操作 examQuestions | 高 |
+| `deleteExamAction` | 直接 `db.query.exams.findFirst` 做归属校验 + `db.delete` | 高 |
+| `duplicateExamAction` | 直接 `db.query.exams.findFirst` + `db.transaction` 内联 insert exams/examQuestions | 高 |
+| `getExamPreviewAction` | 直接 `db.query.exams.findFirst` 查询考试预览数据 | 高 |
+| `getSubjectsAction` | 直接查询 `subjects` 表 —— 跨模块 DB 访问 | 高 |
+| `getGradesAction` | 直接查询 `grades` 表 —— 跨模块 DB 访问 | 高 |
+
+#### 组件耦合
+
+| 组件 | 问题 | 严重程度 |
+|------|------|---------|
+| `exam-assembly.tsx` | 调用 `getQuestionsAction`（questions 模块的 action） | 中 |
+| 8 个组件 | 导入 `Question` 类型自 questions/types | 低（类型导入合理） |
+| `ExamAssembly` | **10 个 props**（examId, title, subject, grade, difficulty, totalScore, durationMin, initialSelected, initialStructure, questionOptions） | 中 |
+| `ExamPreviewQuestionEditor` | **10 个 props** | 中 |
+
+#### ai-pipeline.ts 问题
+
+- 912 行，超过 800 行建议值
+- 混合了 Zod schema、AI prompt、JSON 解析修复、题目详情解析、并发控制等多种职责
+- 建议拆分为：`ai-schema.ts`（Zod schema）、`ai-prompts.ts`（prompt 常量）、`ai-parser.ts`（JSON 解析修复）、`ai-pipeline.ts`（核心生成逻辑）
+
+---
+
+### 3.2 homework 模块
+
+#### 文件行数
+
+| 文件 | 行数 | 限制 | 状态 |
+|------|------|------|------|
+| data-access.ts | **1038** | ≤1000 硬上限 | ❌ **必须拆分** |
+| actions.ts | 387 | ≤800 | ✅ |
+| schema.ts | 29 | 无限制 | ✅ |
+| types.ts | 186 | 无限制 | ✅ |
+
+#### 模块职责边界
+
+- **职责**：作业全生命周期（创建/发布/作答/批改/分析）
+- **问题**：`getStudentDashboardGrades` 包含班级排名计算逻辑（150+ 行），属于 dashboard 或 grades 模块职责
+
+#### data-access 层问题（严重）
+
+| 函数 | 问题 | 严重程度 |
+|------|------|---------|
+| `getStudentDashboardGrades` | 150+ 行排名计算业务逻辑混入 data-access | 高 |
+| `getHomeworkAssignmentAnalytics` | 145+ 行错误率/错误答案统计业务逻辑混入 data-access | 高 |
+| `getHomeworkAssignments` | 直接查询 `exams` 表（第 167-171 行） | 高 |
+| `getHomeworkAssignmentReviewList` | 直接查询 `exams` 表（第 227-233 行） | 高 |
+| `getHomeworkSubmissions` | 直接查询 `exams` 表（第 349-359 行） | 高 |
+| `getHomeworkAssignmentById` | 直接查询 `exams` 表（第 403-407 行） | 高 |
+| `getStudentHomeworkAssignments` | 直接 join `exams`/`subjects` 表（第 730-731 行） | 高 |
+| `getDemoStudentUser` | 直接查询 `users`/`roles`/`usersToRoles` 表 + 使用 `auth()` 而非 auth-guard | 高 |
+| `getStudentDashboardGrades` | 直接查询 `classEnrollments`/`users` 表 | 高 |
+
+#### actions 层问题
+
+| 函数 | 问题 | 严重程度 |
+|------|------|---------|
+| `createHomeworkAssignmentAction` | **157 行**，混合数据访问 + 业务逻辑 + 权限校验 | 高 |
+| 同上 | 直接查询 `classes`/`classSubjectTeachers`/`exams`/`classEnrollments` 表 | 高 |
+| 同上 | 内联 `db.transaction` insert homeworkAssignments/homeworkAssignmentQuestions/homeworkAssignmentTargets | 高 |
+| `startHomeworkSubmissionAction` | 直接 `db.query` + `db.insert` | 高 |
+| `saveHomeworkAnswerAction` | 直接 `db.query` + `db.transaction` | 高 |
+| `submitHomeworkAction` | 直接 `db.query` + `db.update` | 高 |
+| `gradeHomeworkSubmissionAction` | 直接 `db.update` 循环更新 homeworkAnswers | 高 |
+
+#### 拆分建议
+
+`data-access.ts`（1038 行）建议拆分为：
+- `data-access.ts`：基础 CRUD（getHomeworkAssignments, getHomeworkAssignmentById, getHomeworkSubmissions）
+- `data-access-student.ts`：学生视角查询（getStudentHomeworkAssignments, getStudentHomeworkTakeData, getStudentDashboardGrades）
+- `data-access-analytics.ts`：分析统计（getHomeworkAssignmentAnalytics, getTeacherGradeTrends）
+- `data-access-grading.ts`：批改相关（getHomeworkSubmissionDetails, getHomeworkAssignmentReviewList）
+
+---
+
+### 3.3 questions 模块
+
+#### 文件行数
+
+| 文件 | 行数 | 限制 | 状态 |
+|------|------|------|------|
+| actions.ts | 294 | ≤800 | ✅ |
+| data-access.ts | 129 | ≤800 | ✅ |
+| schema.ts | 18 | 无限制 | ✅ |
+| types.ts | 34 | 无限制 | ✅ |
+
+#### 模块职责边界
+
+- **职责**：题库管理（题目 CRUD、知识点关联、题型支持）
+- **问题**：`getKnowledgePointOptionsAction` 查询 textbooks 模块的表，属于 textbooks 模块职责
+
+#### data-access 层问题
+
+- ✅ 仅访问 `questions` 和 `questionsToKnowledgePoints` 表，无跨模块 DB 访问
+- ❌ **缺失写操作函数**：`insertQuestionWithRelations`、`deleteQuestionRecursive` 等 data-access 函数被错误地放在 actions.ts 中
+
+#### actions 层问题
+
+| 函数 | 问题 | 严重程度 |
+|------|------|---------|
+| `createNestedQuestion` | 内联 `db.transaction` + 调用 `insertQuestionWithRelations`（data-access 函数错放在 actions） | 高 |
+| `updateQuestionAction` | 内联 `db.transaction` 做 update/delete/insert | 高 |
+| `deleteQuestionAction` | 内联 `db.transaction` + 调用 `deleteQuestionRecursive`（data-access 函数错放在 actions） | 高 |
+| `getKnowledgePointOptionsAction` | 直接查询 `knowledgePoints`/`chapters`/`textbooks` 表 —— 跨模块 DB 访问 | 高 |
+| `getQuestionsAction` | ✅ 正确委托给 data-access.getQuestions | ✅ |
+
+#### 组件耦合
+
+- ✅ 无跨模块依赖
+
+---
+
+### 3.4 textbooks 模块（标杆模块）
+
+#### 文件行数
+
+| 文件 | 行数 | 限制 | 状态 |
+|------|------|------|------|
+| actions.ts | 276 | ≤800 | ✅ |
+| data-access.ts | 428 | ≤800 | ✅ |
+| types.ts | 79 | 无限制 | ✅ |
+| hooks/use-knowledge-point-actions.ts | 121 | ≤500 | ✅ |
+| hooks/use-text-selection.ts | - | ≤500 | ✅ |
+
+#### 模块职责边界
+
+- **职责**：教材与知识体系管理（教材/章节树形结构、知识点 CRUD、Markdown 内容编辑、知识图谱）
+- ✅ 职责单一，无越界
+
+#### data-access 层评价
+
+- ✅ 仅访问 `textbooks`、`chapters`、`knowledgePoints` 表
+- ✅ 无跨模块 DB 访问
+- ✅ 无业务逻辑混入
+
+#### actions 层评价
+
+- ✅ **标杆实现**：所有 action 均遵循"权限校验 → 调用 data-access → revalidatePath → 返回"模式
+- ✅ 无直接 DB 访问
+- ✅ 无业务逻辑混入
+
+#### 组件耦合
+
+- `knowledge-point-dialogs.tsx` 导入 `CreateQuestionDialog` 自 questions 模块 —— ✅ 合理的 UI 组合
+
+#### hooks 评价
+
+- `useKnowledgePointActions` 有 7 个参数（textbookId, selectedChapterId, selectedChapterTextbookId, highlightedKpId, setHighlightedKpId, onKpCreated）—— ✅ 在 8 个限制内
+
+---
+
+### 3.5 grades 模块
+
+#### 文件行数
+
+| 文件 | 行数 | 限制 | 状态 |
+|------|------|------|------|
+| actions.ts | 312 | ≤800 | ✅ |
+| actions-analytics.ts | 133 | ≤800 | ✅ |
+| data-access.ts | 419 | ≤800 | ✅ |
+| data-access-analytics.ts | 293 | ≤800 | ✅ |
+| data-access-ranking.ts | 121 | ≤800 | ✅ |
+| export.ts | 214 | ≤800 | ✅ |
+| schema.ts | 52 | 无限制 | ✅ |
+| types.ts | - | 无限制 | ✅ |
+
+#### 模块职责边界
+
+- **职责**：成绩分析（录入/查询/统计/导出/趋势对比分析）
+- ✅ 职责单一，未混入考试/作业逻辑
+- ✅ 通过 `examId` 外键引用考试，通过 `type` 枚举引用作业类型，未直接依赖 exams/homework 模块的 data-access
+
+#### data-access 层问题
+
+| 文件 | 函数 | 问题 | 严重程度 |
+|------|------|------|---------|
+| data-access.ts | `getGradeRecords` | 直接 join `classes`/`subjects`/`users` 表 | 高 |
+| data-access.ts | `getStudentGradeSummary` | 直接 join `classes`/`subjects`/`users` 表 | 高 |
+| data-access.ts | `getClassRanking` | 直接 join `users` 表 | 高 |
+| data-access.ts | `getClassStudentsForEntry` | 直接查询 `classEnrollments`/`users` 表 —— 应在 classes 模块 | 高 |
+| data-access.ts | `getClassGradeStatsWithMeta` | 直接查询 `classes`/`classEnrollments` 表 | 高 |
+| data-access.ts | `getClassGradeStats` | 统计计算业务逻辑（average/median/stdDev/passRate/excellentRate）混入 data-access | 中 |
+| data-access-analytics.ts | `getGradeTrend` | 直接 join `classes`/`subjects` 表 | 高 |
+| data-access-analytics.ts | `getClassComparison` | 直接查询 `classes` 表 + 统计计算业务逻辑 | 高 |
+| data-access-analytics.ts | `getSubjectComparison` | 直接 join `subjects` 表 + 统计计算业务逻辑 | 高 |
+| data-access-analytics.ts | `getGradeDistribution` | 分桶统计业务逻辑混入 data-access | 中 |
+| data-access-ranking.ts | `getRankingTrend` | 直接查询 `classEnrollments`/`users` 表 + 排名计算业务逻辑 | 高 |
+| export.ts | `exportClassGradeReportToExcel` | 直接查询 `classes`/`subjects`/`users` 表 + 排名计算业务逻辑 | 高 |
+
+#### actions 层评价
+
+- ✅ **标杆实现**：`actions.ts` 和 `actions-analytics.ts` 均遵循"权限校验 → 调用 data-access → 返回"模式
+- ✅ 无直接 DB 访问
+- ✅ 无业务逻辑混入
+
+#### 组件耦合
+
+- ✅ 无跨模块依赖
+
+---
+
+## 四、跨模块直接 DB 访问汇总
+
+> 以下为违反模块封装原则的直接数据库查询，应改为通过对方模块的 data-access 函数调用。
+
+### 4.1 按来源模块分类
+
+| 来源模块 | 文件 | 被访问的表 | 应调用的模块 |
+|---------|------|-----------|-------------|
+| exams | data-access.ts | `classes` | classes/data-access |
+| exams | data-access.ts | `questions`（insert） | questions/data-access |
+| exams | actions.ts | `subjects`, `grades` | school/data-access |
+| homework | actions.ts | `classes`, `classSubjectTeachers`, `exams`, `classEnrollments` | classes/data-access, exams/data-access |
+| homework | data-access.ts | `exams`, `classEnrollments`, `subjects`, `users`, `roles`, `usersToRoles` | exams/data-access, classes/data-access, school/data-access |
+| questions | actions.ts | `knowledgePoints`, `chapters`, `textbooks` | textbooks/data-access |
+| grades | data-access.ts | `classes`, `classEnrollments`, `subjects`, `users` | classes/data-access, school/data-access |
+| grades | data-access-analytics.ts | `classes`, `subjects` | classes/data-access, school/data-access |
+| grades | data-access-ranking.ts | `classEnrollments`, `users` | classes/data-access |
+| grades | export.ts | `classes`, `subjects`, `users` | classes/data-access, school/data-access |
+
+### 4.2 按被访问表分类（频次）
+
+| 被访问表 | 访问次数 | 应归属模块 |
+|---------|---------|-----------|
+| `classes` | 8+ | classes |
+| `classEnrollments` | 6+ | classes |
+| `users` | 6+ | users |
+| `subjects` | 6+ | school |
+| `exams` | 5+ | exams |
+| `grades`（年级表） | 1 | school |
+| `classSubjectTeachers` | 1 | classes |
+| `knowledgePoints` | 1 | textbooks |
+| `chapters` | 1 | textbooks |
+| `textbooks` | 1 | textbooks |
+| `roles`, `usersToRoles` | 1 | users |
+| `questions`（insert） | 1 | questions |
+
+---
+
+## 五、改进建议
+
+### 5.1 高优先级（P0）
+
+1. **拆分 homework/data-access.ts**（1038 行 → 4 个文件）
+   - 按职责拆分为 data-access.ts / data-access-student.ts / data-access-analytics.ts / data-access-grading.ts
+
+2. **消除跨模块直接 DB 访问**
+   - 在 classes/data-access 暴露 `getClassGradeIdsByClassIds`、`getClassStudentsByClassId`、`getActiveClassStudents` 等函数
+   - 在 exams/data-access 暴露 `getExamForHomeworkCreation`（含 questions 关联）
+   - 在 school/data-access 暴露 `getSubjectOptions`、`getGradeOptions`
+   - 在 users/data-access 暴露 `getUserNameByIds`、`getStudentInfo`
+   - 在 textbooks/data-access 暴露 `getKnowledgePointOptions`
+   - 在 questions/data-access 暴露 `insertQuestionWithRelations`、`deleteQuestionRecursive`
+
+3. **将 exams/actions.ts 中的 DB 操作下沉到 data-access**
+   - `updateExamAction`、`deleteExamAction`、`duplicateExamAction`、`getExamPreviewAction` 的 DB 操作移至 data-access
+   - 将 `getSubjectsAction`/`getGradesAction` 移至 school 模块或改为调用 school/data-access
+
+4. **将 homework/actions.ts 中的 DB 操作下沉到 data-access**
+   - `createHomeworkAssignmentAction`（157 行）拆分为：data-access 函数 + action 编排
+   - 其他 action 的 DB 操作全部移至 data-access
+
+5. **将 questions/actions.ts 中的 DB 操作下沉到 data-access**
+   - `insertQuestionWithRelations`、`deleteQuestionRecursive` 移至 data-access
+   - `getKnowledgePointOptionsAction` 改为调用 textbooks/data-access
+
+### 5.2 中优先级（P1）
+
+6. **拆分 exams/ai-pipeline.ts**（912 行 → 4 个文件）
+   - ai-schema.ts（Zod schema）、ai-prompts.ts（prompt 常量）、ai-parser.ts（JSON 解析修复）、ai-pipeline.ts（核心生成逻辑）
+
+7. **将 homework/data-access.ts 中的业务逻辑提取到独立服务层**
+   - `getStudentDashboardGrades` 的排名计算逻辑提取到 `services/ranking-service.ts`
+   - `getHomeworkAssignmentAnalytics` 的错误率统计逻辑提取到 `services/analytics-service.ts`
+
+8. **将 grades/data-access.ts 中的统计计算逻辑提取到独立服务层**
+   - `getClassGradeStats` 的统计计算提取到 `services/stats-service.ts`
+   - `getGradeDistribution` 的分桶逻辑提取到 `services/distribution-service.ts`
+
+9. **减少组件 props 数量**
+   - `ExamAssembly`（10 props）和 `ExamPreviewQuestionEditor`（10 props）应考虑使用 Context 或组合模式减少 props
+
+### 5.3 低优先级（P2）
+
+10. **统一 auth 调用方式**
+    - `homework/data-access.ts` 的 `getDemoStudentUser` 使用 `auth()` 而非 `auth-guard.getAuthContext()`，应统一
+
+11. **补全 questions/data-access.ts 的写操作**
+    - 当前 data-access 仅有 `getQuestions`，所有写操作错放在 actions.ts
+
+---
+
+## 六、标杆模块推荐
+
+| 模块 | 推荐参考点 |
+|------|-----------|
+| **textbooks** | actions 层编排模式（权限校验 → 调用 data-access → revalidatePath） |
+| **textbooks** | data-access 层职责单一（仅访问本模块表，无业务逻辑） |
+| **grades** | actions 层拆分（actions.ts + actions-analytics.ts 按职责分文件） |
+| **grades** | data-access 层拆分（data-access.ts + data-access-analytics.ts + data-access-ranking.ts） |
+| **grades** | 跨模块解耦（通过外键引用 exams/homework，不直接访问其表） |
+
+---
+
+## 七、审查方法说明
+
+- **审查范围**：5 个核心业务模块的 actions/data-access/schema/types/components/hooks 全量文件
+- **审查工具**：源码全量阅读 + Grep 跨模块依赖扫描 + PowerShell 行数统计
+- **审查依据**：项目规则中"Server Action 必须使用 requirePermission()"、"单文件行数规范"、"模块职责单一"等规则
+- **未覆盖项**：未运行 lint/typecheck（本次为只读审查，不修改代码）；未审查组件内部实现细节（仅审查 props 数量和跨模块依赖）

docs/architecture/audit/management-modules-audit.md

@@ -0,0 +1,393 @@
+# 管理类模块职责与耦合审查报告
+
+> 审查范围：school / classes / scheduling / attendance / users / audit / course-plans / announcements
+> 审查日期：2026-06-17
+> 审查依据：单一职责原则（SRP）、模块边界清晰度、跨模块耦合度、企业级代码规范（单文件 ≤ 1000 行硬性上限）
+> 审查方式：只读源码分析，未修改任何代码
+
+---
+
+## 一、总体评价
+
+| 模块 | 行数（最大文件） | 职责单一性 | 耦合度 | 严重度 |
+|------|----------------|-----------|--------|--------|
+| school | 325 | ✅ 良好 | ✅ 低 | 🟢 合格 |
+| classes | **2104** | ❌ 严重违反 | ❌ 严重 | 🔴 严重 |
+| scheduling | 310（算法）/ 302（actions） | ✅ 算法独立 | ⚠️ 中 | 🟡 需改进 |
+| attendance | 271 | ✅ 良好 | ⚠️ 中 | 🟢 合格 |
+| users | 291（import-export） | ❌ 违反 | ❌ 高 | 🟠 较严重 |
+| audit | 212 | ⚠️ 部分违反 | ✅ 低 | 🟡 需改进 |
+| course-plans | 320 | ✅ 良好 | ✅ 低 | 🟢 合格 |
+| announcements | 242 | ⚠️ 部分违反 | ✅ 低 | 🟡 需改进 |
+
+**核心结论**：
+1. `classes` 模块是全项目耦合最严重的模块，单文件 2104 行远超 1000 行硬性上限，混入了 schedule、homework、grades 三个业务领域的逻辑。
+2. `users/import-export.ts` 违反单一职责，同时处理导入、导出、用户创建、班级注册四类逻辑。
+3. `scheduling/auto-scheduler.ts` 是算法独立化的**优秀范例**，纯函数、无 DB 访问、可独立测试。
+4. `announcements` 和 `audit` 模块的 data-access 层不完整，写操作或导出逻辑泄漏到 actions 层。
+
+---
+
+## 二、模块审查明细
+
+### 2.1 school 模块 — 🟢 合格
+
+**文件清单**：actions.ts (325 行) / data-access.ts (186 行) / schema.ts (51 行) / types.ts (42 行)
+
+**职责边界**：✅ 清晰。仅负责 schools / academicYears / departments / grades 的 CRUD。
+
+**优点**：
+- actions.ts 每个 Action 职责单一：权限校验 → 解析 → DB 写入 → 审计日志 → revalidatePath。
+- data-access.ts 仅包含只读查询，无跨模块写入。
+- 权限校验完整：SCHOOL_MANAGE / GRADE_MANAGE 均接入 requirePermission。
+
+**问题**：
+- ⚠️ **审计日志不一致**：仅 school 实体的 create/update/delete 调用了 `logAudit`，而 department / academicYear / grade 的 CRUD 均未记录审计日志。
+- ⚠️ `getStaffOptions` / `getGrades` 直接查询 users / roles / usersToRoles 表（跨模块读），但属于展示用关联查询，可接受。
+
+**建议**：为 department / academicYear / grade 的 CRUD 补充 `logAudit` 调用，保持审计一致性。
+
+---
+
+### 2.2 classes 模块 — 🔴 严重
+
+**文件清单**：actions.ts (765 行) / data-access.ts (**2104 行**) / types.ts (201 行)
+
+> ⚠️ `data-access.ts` 达 2104 行，**超出 1000 行硬性上限 2 倍**，违反项目代码质量规则。
+
+#### 2.2.1 职责混乱 — 混入三个外部业务领域
+
+`data-access.ts` 实际承载了四个业务领域的逻辑：
+
+| 行范围 | 逻辑 | 应属模块 |
+|--------|------|---------|
+| 49-145 | 教师身份解析、班级访问控制 | classes（合理） |
+| 156-601 | 班级列表/学生/教师查询 | classes（合理） |
+| 697-735 | 课表查询 `getClassSchedule` | **scheduling** |
+| 760-998 | `getClassHomeworkInsights` 班级作业洞察（238 行） | **homework** |
+| 1006-1300 | `getGradeHomeworkInsights` 年级作业洞察（294 行） | **homework** |
+| 1302-1775 | 班级 CRUD + 邀请码 + 注册 | classes（合理） |
+| 1838-1968 | 课表项 CRUD `createClassScheduleItem` 等 | **scheduling** |
+| 1970-2103 | `getStudentsSubjectScores` 学生科目成绩（133 行） | **grades / homework** |
+
+**关键问题**：
+- `getClassHomeworkInsights` 和 `getGradeHomeworkInsights` 合计 **532 行**作业统计逻辑，直接查询 `homeworkAssignments`、`homeworkSubmissions`、`homeworkAssignmentTargets`、`homeworkAssignmentQuestions`、`exams` 五张表，属于 homework 模块的核心业务，不应存在于 classes 模块。
+- 课表 CRUD（`createClassScheduleItem` / `updateClassScheduleItem` / `deleteClassScheduleItem`）与 scheduling 模块的 `applyAutoScheduleAction` 写入同一张 `classSchedule` 表，**两个模块对同一张表有写权限**，边界严重模糊。
+- `getStudentsSubjectScores` 直接关联 `homeworkSubmissions` + `exams` + `subjects` 计算学生科目分数，属于成绩分析逻辑。
+
+#### 2.2.2 types.ts 跨领域类型污染
+
+`types.ts` 定义了本应属于其他模块的类型：
+- `ClassHomeworkInsights` / `GradeHomeworkInsights` / `ClassHomeworkAssignmentStats` / `ScoreStats` / `AssignmentSummary` — 应属 homework 模块
+- `ClassScheduleItem` / `CreateClassScheduleItemInput` / `UpdateClassScheduleItemInput` / `StudentScheduleItem` — 与 scheduling 模块的 `types.ts` 存在概念重叠
+
+#### 2.2.3 actions.ts 跨模块直接查询
+
+`actions.ts` 多处直接查询 `grades` 表（属于 school 模块）进行权限验证，绕过了 school/data-access：
+
+| 行号 | 函数 | 直接查询 |
+|------|------|---------|
+| 60-68 | `createTeacherClassAction` | `db.select().from(grades)` 校验 gradeHead 权限 |
+| 186-194 | `createGradeClassAction` | `db.select().from(grades)` 校验年级管理权 |
+| 241-249 | `updateGradeClassAction` | `db.select().from(classes)` 绕过自身 data-access |
+| 251-272 | `updateGradeClassAction` | `db.select().from(grades)` 校验源/目标年级 |
+| 340-348 | `deleteGradeClassAction` | `db.select().from(grades)` 校验权限 |
+
+**问题**：权限校验逻辑散落在 actions 层，既未下沉到 data-access，也未通过 school 模块暴露的查询接口。
+
+#### 2.2.4 actions.ts 职责重复
+
+存在三组近乎重复的 Action 集合：
+- Teacher 系列：`createTeacherClassAction` / `updateTeacherClassAction` / `deleteTeacherClassAction`
+- Admin 系列：`createAdminClassAction` / `updateAdminClassAction` / `deleteAdminClassAction`
+- Grade 系列：`createGradeClassAction` / `updateGradeClassAction` / `deleteGradeClassAction`
+
+三者表单解析、字段校验逻辑高度重复，仅权限上下文不同。
+
+#### 2.2.5 data-access.ts 内调用 auth()
+
+`getSessionTeacherId`（行 49-62）在 data-access 层直接调用 `auth()` 获取会话，违反"data-access 不感知请求上下文"的分层原则。会话信息应由 actions 层传入。
+
+#### 2.2.6 组件层边界模糊
+
+`classes/components/` 包含 `schedule-view.tsx`、`schedule-filters.tsx`、`class-detail/class-schedule-widget.tsx` 等课表相关组件，与 `scheduling/components/` 的职责重叠。
+
+**整改建议**（优先级 P0）：
+1. 将 `getClassHomeworkInsights` / `getGradeHomeworkInsights` / `getStudentsSubjectScores` / `getClassStudentSubjectScoresV2` 迁移至 homework / grades 模块。
+2. 将课表 CRUD（`createClassScheduleItem` 等）迁移至 scheduling 模块，统一 `classSchedule` 表的写入口。
+3. 将 `data-access.ts` 拆分为 `data-access.ts`（班级 CRUD）+ `data-access-enrollments.ts`（注册/邀请码）+ `data-access-insights.ts`（如暂不迁移则隔离）。
+4. 将权限校验中的 `grades` 表查询改为调用 school/data-access 暴露的接口。
+5. 将 `getSessionTeacherId` 上移至 actions 层或 shared/lib。
+
+---
+
+### 2.3 scheduling 模块 — 🟡 需改进（算法层优秀）
+
+**文件清单**：actions.ts (302 行) / auto-scheduler.ts (310 行) / data-access.ts (272 行) / schema.ts / types.ts
+
+#### 2.3.1 auto-scheduler.ts — ✅ 优秀范例
+
+**这是全项目算法独立化的最佳实践**：
+- 纯函数：`findOptimalSlot` / `validateSchedule` / `autoSchedule` / `buildDefaultTimeSlots`
+- 无 `"server-only"` 副作用，无 DB 访问，无 `import { db }`
+- 仅依赖 types.ts 的类型导入
+- **可独立单元测试**：给定输入即可断言输出，无需 mock 数据库
+- 算法清晰：贪心 + 约束检查（午餐、每日上限、教师/教室冲突、避免连排）
+
+**建议**：以此为模板，指导其他模块的算法抽取（如 homework 的批改评分算法、grades 的统计算法）。
+
+#### 2.3.2 actions.ts — 跨模块直接写入
+
+| 行号 | 函数 | 问题 |
+|------|------|------|
+| 110-116 | `autoScheduleAction` | 直接 `db.select().from(users)` 查询教师，绕过 data-access 的 `getTeachersForScheduling` |
+| 168-180 | `applyAutoScheduleAction` | 直接 `db.transaction` 写入 `classSchedule` 表，**绕过 data-access 且跨模块写 classes 领域的表** |
+
+`applyAutoScheduleAction` 的问题尤为突出：它删除并重建 `classSchedule` 表数据，但该写操作既未经过 scheduling/data-access，也未经过 classes/data-access，形成**第三个对 classSchedule 表的写入口**（另两个在 classes/data-access 的 createClassScheduleItem 等）。
+
+#### 2.3.3 data-access.ts — 跨模块读查询
+
+包含 `getAdminClassesForScheduling` / `getTeachersForScheduling` / `getClassroomsForScheduling` / `getClassSubjectsForScheduling` 四个辅助查询，直接访问 `classes` / `classSubjectTeachers` / `subjects` / `users` / `classrooms` 表。
+
+这些是排课场景的只读辅助查询，耦合度可接受，但理想情况下应通过各所属模块的 data-access 暴露接口。
+
+#### 2.3.4 actions.ts 末尾 re-export
+
+```typescript
+export { getSchedulingRules, getScheduleChanges, ... } from "./data-access"
+```
+actions 层 re-export data-access 函数是反模式，应让消费方直接从 data-access 导入。
+
+**整改建议**：
+1. 将 `applyAutoScheduleAction` 中的 `classSchedule` 写入逻辑下沉到 data-access（或与 classes 协商统一写入口）。
+2. 将 `autoScheduleAction` 中的 users 查询改用 `getTeachersForScheduling`。
+3. 移除 actions.ts 末尾的 re-export。
+
+---
+
+### 2.4 attendance 模块 — 🟢 合格（结构典范）
+
+**文件清单**：actions.ts (271 行) / data-access.ts (271 行) / data-access-stats.ts (145 行) / schema.ts / types.ts
+
+**优点**：
+- **stats 独立拆分**：`data-access-stats.ts` 专门承载统计逻辑，是 classes 模块应学习的拆分模式。
+- actions.ts 每个 Action 职责单一：权限校验 → 解析 → 委托 data-access → revalidate。
+- `DataScope` 数据范围控制完整接入，支持 6 种 scope 类型。
+- 无写操作泄漏到 actions 层。
+
+**问题**：
+- ⚠️ `getClassStudentsForAttendance`（data-access.ts 行 206-217）直接查询 `classEnrollments` 表获取班级学生列表，属于 classes 模块数据，应通过 classes/data-access 暴露的接口调用。
+- ⚠️ data-access.ts 和 data-access-stats.ts 均直接 JOIN `classes` 表获取班级名称（只读展示，可接受）。
+
+**整改建议**：在 classes/data-access 暴露 `getClassStudentIds(classId)` 接口，供 attendance 调用。
+
+---
+
+### 2.5 users 模块 — 🟠 较严重
+
+**文件清单**：actions.ts (151 行) / data-access.ts (71 行) / import-export.ts (291 行)
+
+#### 2.5.1 import-export.ts — 四重职责混合
+
+该文件同时承载四类互不相关的职责：
+
+| 行范围 | 职责 | 应属位置 |
+|--------|------|---------|
+| 54-73 | `generateUserImportTemplate` 生成导入模板 | export 模块 |
+| 78-111 | `parseUserImportData` 解析+校验导入数据 | import 模块 |
+| 116-207 | `batchImportUsers` 批量导入（含用户创建） | **data-access** |
+| 212-291 | `exportUsersToExcel` 导出用户列表 | export 模块 |
+
+**核心问题**：
+1. **导入与导出未分离**：应拆分为 `import.ts` 与 `export.ts`。
+2. **用户创建逻辑泄漏**：`batchImportUsers`（行 158-167）直接 `db.insert(users)` + 密码哈希 + `db.insert(usersToRoles)`，这是 data-access 层的职责，不应存在于 import-export 工具文件中。
+3. **跨模块写 classEnrollments**：行 174-184，`batchImportUsers` 直接 `db.insert(classEnrollments)` 将学生注册到班级，**这是 classes 模块的写操作**，严重违反模块边界。
+4. **跨模块读 classes**：行 130-137，直接查询 `classes` 表根据邀请码查找班级，应通过 classes/data-access 暴露接口。
+
+#### 2.5.2 actions.ts — 绕过 data-access
+
+`updateUserProfile`（行 29-51）直接 `db.update(users)` 写入数据库，绕过了 data-access 层。data-access.ts 仅有 `getUserProfile` 一个读函数，写操作缺失。
+
+#### 2.5.3 data-access.ts — 过于单薄
+
+仅 71 行，只包含 `getUserProfile`。用户创建、更新、角色绑定等写操作均未在此层实现。
+
+**整改建议**（优先级 P1）：
+1. 将 `import-export.ts` 拆分为 `import.ts`（解析+校验）和 `export.ts`（模板生成+列表导出）。
+2. 将 `batchImportUsers` 中的用户创建逻辑迁移至 `data-access.ts` 的 `createUser` 函数，import.ts 仅负责编排。
+3. 将 classEnrollments 写入改为调用 classes/data-access 的注册接口（如 `enrollStudentByInvitationCode`）。
+4. 将 `updateUserProfile` 的 DB 写入下沉到 data-access。
+
+---
+
+### 2.6 audit 模块 — 🟡 需改进
+
+**文件清单**：actions.ts (212 行) / data-access.ts (260 行) / types.ts
+
+**问题**：
+- ⚠️ **Excel 导出逻辑内联在 actions 层**：`exportAuditLogsAction` / `exportLoginLogsAction` / `exportDataChangeLogsAction` 三个 Action 各自内联了 `exportToExcel` 调用及完整的列定义（表头、宽度、字段映射），每个约 40 行。这是展示/格式化逻辑，应抽取到独立的 `export.ts`。
+- ⚠️ 三个导出 Action 的结构高度重复（权限校验 → 查询 → 构造 columns → exportToExcel → 返回 buffer），可抽象为通用导出工厂。
+
+**优点**：
+- data-access.ts 职责清晰，仅包含日志查询，无跨模块问题。
+- 分页逻辑统一（clampPage / clampPageSize）。
+
+**整改建议**：抽取 `export.ts`，封装 `exportAuditLogsToExcel(items)` / `exportLoginLogsToExcel(items)` / `exportDataChangeLogsToExcel(items)`，actions 层仅负责编排。
+
+---
+
+### 2.7 course-plans 模块 — 🟢 合格
+
+**文件清单**：actions.ts (265 行) / data-access.ts (320 行) / schema.ts / types.ts
+
+**优点**：
+- actions.ts 使用 `handleError` / `revalidatePlanPaths` 辅助函数消除重复，是 actions 层的**良好范例**。
+- data-access.ts 职责清晰：课程计划 CRUD + 周计划项 CRUD + 排序。
+- 跨模块查询仅为 `classes` / `subjects` / `users` 的 LEFT JOIN 取展示名称（只读，可接受）。
+
+**小问题**：
+- ⚠️ `getSubjectOptions`（行 310-320）直接查询 `subjects` 表，subjects 无独立模块，暂可接受。
+
+**结论**：该模块结构可作为其他模块的参考模板。
+
+---
+
+### 2.8 announcements 模块 — 🟡 需改进
+
+**文件清单**：actions.ts (242 行) / data-access.ts (120 行) / schema.ts / types.ts
+
+**核心问题 — 写操作泄漏到 actions 层**：
+
+data-access.ts 仅包含两个**只读**函数（`getAnnouncements` / `getAnnouncementById`），所有写操作均直接在 actions.ts 中执行 `db.insert` / `db.update` / `db.delete`：
+
+| Action | 直接 DB 操作 | 行号 |
+|--------|-------------|------|
+| `createAnnouncementAction` | `db.insert(announcements)` | 53-63 |
+| `updateAnnouncementAction` | `db.update(announcements)` | 118-130 |
+| `deleteAnnouncementAction` | `db.delete(announcements)` | 154 |
+| `publishAnnouncementAction` | `db.update(announcements)` | 176-183 |
+| `archiveAnnouncementAction` | `db.update(announcements)` | 206-212 |
+
+这违反了"data-access 层封装所有 DB 操作"的分层约定，导致：
+- 写逻辑无法被其他 server 端代码复用
+- publishedAt 计算逻辑散落在 actions 中，难以测试
+
+**其他问题**：
+- ⚠️ 死代码：`updateAnnouncementAction` 行 108 计算 `wasPublished`，行 135 `void wasPublished` 显式丢弃，未实际使用。
+- ⚠️ `getAnnouncementsAction` 使用 `requireAuth()` 而非 `requirePermission(ANNOUNCEMENT_READ)`，与其他模块的权限模式不一致。
+
+**整改建议**：
+1. 在 data-access.ts 补充 `createAnnouncement` / `updateAnnouncement` / `deleteAnnouncement` / `publishAnnouncement` / `archiveAnnouncement` 写函数。
+2. actions 层仅保留权限校验 + 解析 + 委托调用。
+3. 清理 `wasPublished` 死代码。
+
+---
+
+## 三、跨模块直接查询汇总
+
+### 3.1 跨模块写操作（严重）
+
+| 源文件 | 目标表 | 操作 | 应通过 |
+|--------|--------|------|--------|
+| classes/data-access.ts | classSchedule | CRUD | scheduling/data-access |
+| scheduling/actions.ts | classSchedule | delete + insert | scheduling/data-access |
+| users/import-export.ts | classEnrollments | insert | classes/data-access |
+| users/import-export.ts | users, usersToRoles | insert | users/data-access |
+| announcements/actions.ts | announcements | insert/update/delete | announcements/data-access |
+| users/actions.ts | users | update | users/data-access |
+
+> ⚠️ `classSchedule` 表存在 **三个写入口**（classes/data-access、scheduling/actions、scheduling/data-access 间接），是数据完整性高风险点。
+
+### 3.2 跨模块读操作（需评估）
+
+| 源文件 | 目标表 | 用途 | 评估 |
+|--------|--------|------|------|
+| classes/data-access.ts | homeworkAssignments, homeworkSubmissions, homeworkAssignmentTargets, homeworkAssignmentQuestions, exams | 作业洞察统计 | ❌ 应迁移至 homework |
+| classes/data-access.ts | grades, schools | 年级/学校关联 | ⚠️ 应通过 school data-access |
+| classes/actions.ts | grades | 权限校验 | ⚠️ 应通过 school data-access |
+| scheduling/data-access.ts | classes, classSubjectTeachers, subjects, users, classrooms | 排课辅助查询 | 🟡 可接受（只读） |
+| attendance/data-access.ts | classEnrollments | 获取班级学生 | ⚠️ 应通过 classes data-access |
+| users/import-export.ts | classes | 邀请码查询 | ⚠️ 应通过 classes data-access |
+| course-plans/data-access.ts | classes, subjects, users | 展示名称 JOIN | 🟢 可接受 |
+
+---
+
+## 四、actions 层多职责问题汇总
+
+| Action | 混入职责 | 应拆分 |
+|--------|---------|--------|
+| `users/import-export.ts: batchImportUsers` | 用户创建 + 密码哈希 + 角色绑定 + 班级注册 | 拆为 createUser + enrollStudent |
+| `classes/actions.ts: updateGradeClassAction` | 班级更新 + 科任教师批量分配 | 拆为 updateClass + setClassSubjectTeachers（已部分拆分但仍在同一 Action 内编排） |
+| `classes/actions.ts: updateAdminClassAction` | 同上 | 同上 |
+| `audit/actions.ts: exportAuditLogsAction` | 查询 + Excel 列定义 + 导出 | 拆为 query + exportAuditLogsToExcel |
+| `audit/actions.ts: exportLoginLogsAction` | 同上 | 同上 |
+| `audit/actions.ts: exportDataChangeLogsAction` | 同上 | 同上 |
+| `announcements/actions.ts: createAnnouncementAction` | 解析 + publishedAt 计算 + DB 写入 | DB 写入下沉 data-access |
+
+---
+
+## 五、整改优先级
+
+### P0 — 立即整改（影响数据完整性 & 严重违反规范）
+
+1. **classes/data-access.ts 拆分**：2104 行远超硬性上限，且混入 homework/scheduling/grades 三个领域。优先迁移 `getClassHomeworkInsights` / `getGradeHomeworkInsights`（532 行）至 homework 模块。
+2. **统一 classSchedule 表写入口**：classes 与 scheduling 两个模块对该表有写权限，需协商归属并收敛为单一写入口。
+
+### P1 — 尽快整改（模块边界违反）
+
+3. **users/import-export.ts 拆分**：分离导入/导出，用户创建逻辑下沉 data-access，classEnrollments 写入改调 classes 接口。
+4. **announcements 写操作下沉**：在 data-access 补充写函数，actions 仅编排。
+5. **classes/actions.ts 权限校验**：grades 表查询改通过 school/data-access 接口。
+
+### P2 — 持续优化（代码质量）
+
+6. **audit 导出逻辑抽取**：内联的 Excel 列定义移至独立 export.ts。
+7. **school 审计日志补全**：department/academicYear/grade 的 CRUD 补充 logAudit。
+8. **attendance 跨模块查询**：`getClassStudentsForAttendance` 改调 classes 接口。
+9. **scheduling/actions.ts**：移除 re-export，DB 写入下沉 data-access。
+10. **announcements 死代码清理**：移除 `void wasPublished`。
+
+---
+
+## 六、优秀实践（建议推广）
+
+| 实践 | 模块 | 说明 |
+|------|------|------|
+| 算法纯函数化 | scheduling/auto-scheduler.ts | 无 DB 依赖，可独立测试，应作为算法抽取模板 |
+| stats 文件拆分 | attendance/data-access-stats.ts | 统计逻辑独立成文件，classes 应效仿 |
+| actions 辅助函数 | course-plans/actions.ts | handleError / revalidatePlanPaths 消除重复 |
+| DataScope 接入 | attendance/actions.ts | 6 种数据范围完整支持 |
+| 权限统一接入 | school / attendance / course-plans | 全部 Action 使用 requirePermission |
+
+---
+
+## 七、附：文件行数统计
+
+| 文件 | 行数 | 上限 | 状态 |
+|------|------|------|------|
+| classes/data-access.ts | 2104 | 1000 | 🔴 超限 2.1x |
+| classes/actions.ts | 765 | 800（建议） | 🟢 合规 |
+| classes/types.ts | 201 | 无限制 | 🟢 合规 |
+| school/actions.ts | 325 | 800（建议） | 🟢 合规 |
+| school/data-access.ts | 186 | 800（建议） | 🟢 合规 |
+| scheduling/auto-scheduler.ts | 310 | 无限制 | 🟢 合规 |
+| scheduling/actions.ts | 302 | 800（建议） | 🟢 合规 |
+| scheduling/data-access.ts | 272 | 800（建议） | 🟢 合规 |
+| attendance/actions.ts | 271 | 800（建议） | 🟢 合规 |
+| attendance/data-access.ts | 271 | 800（建议） | 🟢 合规 |
+| attendance/data-access-stats.ts | 145 | 800（建议） | 🟢 合规 |
+| users/import-export.ts | 291 | 800（建议） | 🟢 合规（但职责混合） |
+| users/actions.ts | 151 | 800（建议） | 🟢 合规 |
+| users/data-access.ts | 71 | 800（建议） | 🟢 合规 |
+| audit/actions.ts | 212 | 800（建议） | 🟢 合规 |
+| audit/data-access.ts | 260 | 800（建议） | 🟢 合规 |
+| course-plans/actions.ts | 265 | 800（建议） | 🟢 合规 |
+| course-plans/data-access.ts | 320 | 800（建议） | 🟢 合规 |
+| announcements/actions.ts | 242 | 800（建议） | 🟢 合规 |
+| announcements/data-access.ts | 120 | 800（建议） | 🟢 合规 |
+
+> 仅 `classes/data-access.ts` 突破硬性上限，需立即拆分。
+
+---
+
+*报告结束。本审查未修改任何源代码。*

docs/architecture/audit/new-and-other-modules-audit.md

@@ -0,0 +1,604 @@
+# 新增模块与其他模块架构审查报告
+
+> 审查范围：elective / proctoring / diagnostic / notifications / dashboard / messaging / parent / settings / files / auth / layout / student
+> 审查日期：2026-06-17
+> 审查依据：源码全量扫描 + 架构影响地图(004/005) + 差距审计报告(007)
+> 审查目标：识别职责不单一、过耦合、边界模糊、幽灵路由等问题
+
+---
+
+## 一、总体评估
+
+| 维度 | 模块数 | 严重问题 | 中等问题 | 轻微问题 | 总体评价 |
+|------|--------|---------|---------|---------|----------|
+| 新增模块 | 4 | 3 | 5 | 3 | ⚠️ 职责基本清晰，但存在跨模块耦合与未集成代码 |
+| 其他模块 | 8 | 1 | 4 | 3 | ⚠️ dashboard 跨模块直查问题突出 |
+| **合计** | **12** | **4** | **9** | **6** | **需重点修复 4 项严重问题** |
+
+### 严重问题清单（必须修复）
+
+1. **messaging 与 notifications 边界模糊、双向依赖** — 两个模块都写入 `messageNotifications` 表，notifications 反向依赖 messaging，类型系统不一致
+2. **dashboard/data-access.ts 直查 11 张跨模块表** — 违反模块封装原则
+3. **proctoring/exam-mode-config.tsx 未集成到考试表单** — DB schema 有 examMode 等字段但无 UI 录入入口，组件成为死代码
+4. **proctoring 事件上报存在 Server Action 与 REST API 双通道重复** — 同一逻辑两份代码
+
+---
+
+## 二、新增模块审查
+
+### 2.1 elective 模块（选课管理）
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 304 | 11 个 Server Action（CRUD + 选课 + 抽签 + 查询） |
+| `data-access.ts` | 242 | 课程 CRUD + 查询 + scope 过滤 |
+| `data-access-operations.ts` | 217 | 选课操作（select/drop/lottery） |
+| `data-access-selections.ts` | 189 | 选课记录查询 + 学生可用课程查询 |
+| `schema.ts` | 132 | Zod 校验 schema |
+| `types.ts` | 108 | 类型定义 + 标签常量 |
+
+#### 拆分为 3 个 data-access 文件是否合理？
+
+**结论：⚠️ 拆分意图合理，但存在代码重复**
+
+- **拆分意图合理**：operations（写操作）与 selections（读查询）职责分明，符合"按职责划分"原则
+- **代码重复问题**：`data-access.ts` 与 `data-access-selections.ts` 重复定义了 `mapCourseRow` 和 `buildCourseSelect` 两个函数（共约 60 行重复代码）
+  - `data-access.ts` 第 47-108 行
+  - `data-access-selections.ts` 第 28-88 行
+  - 两份代码完全相同，维护时易产生不一致
+
+**建议**：
+- 抽取共享的 `mapCourseRow` / `buildCourseSelect` 到 `data-access.ts` 并导出，`data-access-selections.ts` 复用
+- 或合并 `data-access-selections.ts` 到 `data-access.ts`（文件仅 189 行，合并后仍在 800 行上限内）
+
+#### 权限校验
+
+✅ 全部 Server Action 均使用 `requirePermission`：
+- 管理 Action 使用 `ELECTIVE_MANAGE`
+- 选课 Action 使用 `ELECTIVE_SELECT`
+- 查询 Action 使用 `ELECTIVE_READ`
+- 学生查看他人选课记录有额外 dataScope 校验（actions.ts 第 283-288 行）
+
+#### 其他发现
+
+- ✅ schema.ts 使用 Zod transform 统一处理空字符串转 null，规范
+- ⚠️ `data-access-operations.ts` 的 `runLottery` 使用 `Math.random()` 排序（第 40 行），结果不可复现，建议改用 DB 的 `ORDER BY RAND()` 或记录种子
+- ⚠️ `selectCourse` 在 FCFS 模式下先查后写（第 119-128 行），存在并发超卖风险，建议加事务或乐观锁
+
+---
+
+### 2.2 proctoring 模块（考试监考）
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 144 | 2 个 Server Action（上报事件 + 获取面板） |
+| `data-access.ts` | 388 | 事件记录 + 查询 + 摘要统计 + 学生状态 |
+| `types.ts` | 136 | 类型定义 + 标签常量 + 阈值常量 |
+| `components/anti-cheat-monitor.tsx` | - | 学生端防作弊监控 |
+| `components/exam-mode-config.tsx` | - | 考试模式配置表单（**未集成**） |
+| `components/proctoring-dashboard.tsx` | - | 教师监考面板 |
+
+#### 职责清晰度
+
+**结论：⚠️ 职责基本清晰，但存在 3 个严重问题**
+
+#### 严重问题 1：`exam-mode-config.tsx` 未集成到考试表单（死代码）
+
+- DB schema 已有 `examMode` / `durationMinutes` / `shuffleQuestions` / `allowLateStart` / `antiCheatEnabled` 字段（schema.ts 第 457-462 行）
+- `proctoring/components/exam-mode-config.tsx` 提供了完整的配置 UI 组件
+- **但 `exams/components/exam-form.tsx` 并未导入该组件**（grep 确认无 `ExamModeConfig` 引用）
+- `exams/components/exam-mode-selector.tsx` 是"手动组卷 vs AI 生成"的选择器，**与考试模式（homework/timed/proctored）无关**，命名易混淆
+- 结果：创建考试时无法设置监考模式，proctoring 模块的 `getExamForProctoring` 读取的 `examMode` 永远是默认值 `"homework"`
+
+**建议**：将 `exam-mode-config.tsx` 集成到 `exam-form.tsx`，或迁移到 exams 模块
+
+#### 严重问题 2：事件上报存在 Server Action 与 REST API 双通道重复
+
+- `proctoring/actions.ts` 第 58-105 行：`recordProctoringEventAction`（Server Action）
+- `app/api/proctoring/event/route.ts` 第 27-90 行：POST handler（REST API）
+- **两者逻辑完全相同**：都校验 submission 归属、调用 `recordProctoringEvent`
+- `AntiCheatMonitor` 组件使用 Server Action（第 58 行），REST API 路由无调用方
+
+**建议**：删除未使用的 `/api/proctoring/event` 路由，或让组件改用 REST API（适用于客户端轮询场景）
+
+#### 中等问题 3：跨模块读取 exams 表
+
+- `data-access.ts` 第 326-353 行：`getExamForProctoring` 直接查询 `exams` 表
+- 第 178-185 行：`getExamProctoringSummary` 直接查询 `examSubmissions` 表
+- 第 249-256 行：`getStudentProctoringStatuses` 直接 join `examSubmissions` 和 `users`
+
+**建议**：可接受（监考本质是考试模块的扩展），但应在架构图中标注依赖关系
+
+#### 其他发现
+
+- ✅ `recordProctoringEventAction` 使用 `requireAuth()` 而非 `requirePermission`，符合"学生上报自己事件"场景
+- ✅ `getProctoringDashboardAction` 使用 `EXAM_PROCTOR` 权限
+- ✅ 异常阈值 `ABNORMAL_EVENT_THRESHOLD = 3` 提取为常量，便于调整
+- ⚠️ `actions.ts` 第 11-13 行直接 import `db` 和 `examSubmissions`，应在 data-access 层封装 submission 校验逻辑
+
+---
+
+### 2.3 diagnostic 模块（学情诊断）
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 148 | 6 个 Server Action（生成/发布/删除/查询报告） |
+| `data-access.ts` | 254 | 知识点掌握度查询 + 从提交更新掌握度 |
+| `data-access-reports.ts` | 202 | 诊断报告 CRUD |
+| `types.ts` | 97 | 类型定义 |
+| `components/` | 4 个 | 学生/班级诊断视图 + 雷达图 + 报告列表 |
+
+#### 与 grades 模块的边界
+
+**结论：✅ 无职责重叠，但存在跨模块耦合**
+
+- **grades 模块**：管理 `gradeRecords` 表（分数记录），维度是"学生-班级-科目-考试"
+- **diagnostic 模块**：管理 `knowledgePointMastery` 表（知识点掌握度），维度是"学生-知识点"
+- 两者数据来源不同：grades 是教师录入的分数，diagnostic 是从 `submissionAnswers` 推导的正确率
+- **无任何代码重叠**：grep 确认 grades 模块无 `knowledgePoint` / `mastery` / `diagnostic` 关键字
+
+#### 中等问题 1：`data-access.ts` 跨模块直查 4 张表
+
+- 第 87-92 行：查询 `examSubmissions` 表（属 exams 模块）
+- 第 95-101 行：查询 `submissionAnswers` 表（属 exams/homework 模块）
+- 第 106-112 行：查询 `questionsToKnowledgePoints` 表（属 questions 模块）
+- 第 150-158 行：查询 `classEnrollments` + `classes` + `users` 表（属 classes 模块）
+
+`updateMasteryFromSubmission` 函数（第 87-147 行）直接读取提交答案和题目-知识点关联，将 diagnostic 模块与 exams/homework/questions 模块紧耦合。
+
+**建议**：
+- 短期：在架构图中标注此依赖关系
+- 长期：由 exams/homework 模块在提交评分后主动调用 diagnostic 模块的更新接口（事件驱动）
+
+#### 轻微问题 2：`data-access-reports.ts` 有未使用代码
+
+- 第 20 行定义 `round2` 函数
+- 第 201 行 `void round2` 仅为消除 lint 警告
+- **建议**：删除未使用的 `round2` 函数
+
+#### 轻微问题 3：班级报告字段复用不当
+
+- `data-access-reports.ts` 第 107 行：`studentId: generatedBy` — 班级报告将生成者 ID 存入 `studentId` 字段
+- 注释说明"schema 要求 NOT NULL"，但这是 schema 设计缺陷的 workaround
+- **建议**：修改 `learningDiagnosticReports` schema，将 `studentId` 改为可空，或增加 `classId` 字段
+
+#### 权限校验
+
+✅ 全部 Action 使用 `DIAGNOSTIC_MANAGE` 或 `DIAGNOSTIC_READ` 权限
+
+---
+
+### 2.4 notifications 模块（通知分发）
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 119 | 2 个 Server Action（单发 + 班级群发） |
+| `data-access.ts` | 86 | 用户偏好 + 联系方式 + 日志 |
+| `dispatcher.ts` | 152 | 渠道选择 + 并行分发 |
+| `types.ts` | 70 | 通知负载 + 渠道配置类型 |
+| `index.ts` | 38 | 对外导出入口 |
+| `channels/` | 5 个 | SMS/Email/WeChat/InApp 渠道实现 |
+
+#### 严重问题 1：与 messaging 模块双向依赖、边界模糊
+
+详见下文"三、messaging vs notifications 边界分析"。
+
+#### 中等问题 2：`sendClassNotificationAction` 跨模块直查
+
+- `actions.ts` 第 83-96 行：直接查询 `classes` 和 `classEnrollments` 表
+- 应通过 classes 模块的 data-access 获取班级学生列表
+
+**建议**：调用 `classes` 模块的 data-access 函数获取学生 ID 列表
+
+#### 中等问题 3：发送日志仅 console 输出
+
+- `data-access.ts` 第 71-77 行：`logNotificationSend` 使用 `console.info`
+- 代码注释承认"当前项目无 notification_logs 表"
+- **影响**：无法查询历史发送记录、无法统计发送成功率、无法排查发送失败
+
+**建议**：新增 `notification_logs` 表，记录 channel/userId/payload/success/error/sentAt
+
+#### 轻微问题 4：复用 MESSAGE_SEND 权限
+
+- `actions.ts` 第 34、67 行：使用 `Permissions.MESSAGE_SEND`
+- 代码注释说明"项目无独立 NOTIFICATION_SEND 权限点"
+- **影响**：无法单独控制"谁能发通知"vs"谁能发私信"
+
+**建议**：新增 `NOTIFICATION_SEND` 权限点，或确认复用是设计意图
+
+#### 设计亮点
+
+- ✅ 渠道抽象优秀：`NotificationChannelSender` 接口 + 工厂函数，新增渠道只需实现接口
+- ✅ Mock 实现完善：SMS/Email/WeChat 均有 Mock 实现，开发环境零配置可用
+- ✅ 动态 import 第三方 SDK（阿里云/腾讯云/nodemailer），避免增加构建体积
+- ✅ 渠道选择逻辑清晰（dispatcher.ts 第 59-95 行）
+
+---
+
+## 三、messaging vs notifications 边界分析（重点）
+
+### 3.1 现状对比
+
+| 维度 | messaging 模块 | notifications 模块 |
+|------|---------------|-------------------|
+| **核心职责** | 站内私信 + 站内通知列表 | 多渠道通知分发 |
+| **管理的表** | `messages` + `messageNotifications` + `notificationPreferences` | 无独有表（借用 messaging 的表） |
+| **写入 messageNotifications** | ✅ 直接写（`createNotification`） | ✅ 通过 in-app 渠道写 |
+| **通知类型枚举** | `NotificationType = "message" \| "announcement" \| "homework" \| "grade"` | `NotificationPayload.type = "info" \| "warning" \| "error" \| "success"` |
+| **UI 组件** | message-list / message-detail / message-compose / notification-dropdown / notification-list | 无 UI 组件 |
+| **偏好管理** | ✅ `notification-preferences.ts` | ❌ 借用 messaging 的 |
+| **渠道支持** | 仅站内 | 站内 + SMS + Email + WeChat |
+
+### 3.2 严重问题：双向依赖与职责重叠
+
+#### 问题 1：notifications 反向依赖 messaging
+
+```
+notifications/data-access.ts
+  → import { getNotificationPreferences } from "@/modules/messaging/notification-preferences"
+  → import type { NotificationPreferences } from "@/modules/messaging/types"
+
+notifications/channels/in-app-channel.ts
+  → import { createNotification } from "@/modules/messaging/data-access"
+```
+
+notifications 模块不拥有任何数据，全部依赖 messaging 模块。这违背了"模块应拥有自己的数据"原则。
+
+#### 问题 2：messaging 绕过 notifications 直接写通知
+
+`messaging/actions.ts` 第 66-72 行：
+
+```typescript
+// Notify the receiver about the new message
+await createNotification({
+  userId: input.receiverId,
+  type: "message",
+  title: input.subject ? `New message: ${input.subject}` : "New message",
+  content: input.content.slice(0, 200),
+  link: `/messages/${id}`,
+})
+```
+
+这直接调用 `messaging/data-access.ts` 的 `createNotification`，**完全绕过 notifications 模块的 dispatcher**，导致：
+- 用户设置的 SMS/Email 偏好被忽略
+- 新消息不会触发邮件/短信提醒
+- notifications 模块的多渠道能力形同虚设
+
+#### 问题 3：类型系统不一致
+
+- `messaging/types.ts` 第 23 行：`NotificationType = "message" | "announcement" | "homework" | "grade"`（按业务类别）
+- `notifications/types.ts` 第 20 行：`type: "info" | "warning" | "error" | "success"`（按严重级别）
+- `in-app-channel.ts` 第 49 行：`type: payload.type as "message" | "announcement" | "homework" | "grade"` — **强制类型转换，运行时可能写入非法值**
+
+DB schema 中 `messageNotifications.type` 为 `varchar(128)`，虽然不会报错，但语义混乱。
+
+#### 问题 4：notification-preferences 归属不清
+
+- `notificationPreferences` 表的 data-access 在 messaging 模块
+- 但 notifications 模块的 dispatcher 依赖此偏好决定渠道
+- settings 模块的 `notification-preferences-form.tsx` 调用 `messaging/actions.ts` 的 `updateNotificationPreferencesAction`
+- 三个模块都在操作同一份数据，职责归属不清
+
+### 3.3 建议方案
+
+**方案 A（推荐）：notifications 吞并 messaging 的通知部分**
+
+1. 将 `messageNotifications` 表和 `notificationPreferences` 表的所有权移交给 notifications 模块
+2. messaging 模块仅保留 `messages` 表（私信）
+3. messaging 的 `sendMessageAction` 改为调用 `notifications.sendNotification`
+4. messaging 的 UI 组件（notification-dropdown / notification-list）迁移到 notifications 模块
+5. 统一 `NotificationType` 枚举，支持业务类别 + 严重级别两个维度
+
+**方案 B：保持现状，明确依赖方向**
+
+1. 在架构图中标注 notifications → messaging 的单向依赖
+2. messaging 不再直接调用 `createNotification`，改为调用 `notifications.sendNotification`
+3. 消除双向依赖，但 notifications 仍不拥有数据
+
+---
+
+## 四、dashboard 模块审查（重点）
+
+### 4.1 严重问题：`data-access.ts` 直查 11 张跨模块表
+
+`dashboard/data-access.ts` 的 `getAdminDashboardData` 函数直接查询以下表：
+
+| 表名 | 所属模块 | 查询内容 |
+|------|---------|---------|
+| `sessions` | auth | 活跃会话数 |
+| `users` | users | 用户总数 + 最近注册用户 |
+| `usersToRoles` | users | 用户角色统计 |
+| `roles` | users | 角色名 |
+| `classes` | classes | 班级总数 |
+| `textbooks` | textbooks | 教材总数 |
+| `chapters` | textbooks | 章节总数 |
+| `questions` | questions | 题目总数 |
+| `exams` | exams | 考试总数（含 scope 过滤） |
+| `homeworkAssignments` | homework | 作业总数 + 已发布数 |
+| `homeworkSubmissions` | homework | 提交数 + 待批改数 |
+
+**问题分析**：
+- 违反模块封装原则：dashboard 直接依赖其他模块的 DB schema
+- 任何模块的表结构变更都需要同步修改 dashboard
+- 无法复用其他模块的 scope 过滤逻辑（dashboard 自己实现了 exam/homework 的 scope 过滤，第 31-73 行）
+
+### 4.2 学生/教师仪表盘的对比
+
+**学生仪表盘**（`app/(dashboard)/student/dashboard/page.tsx`）：
+- ✅ 正确做法：调用 `classes/data-access` 的 `getStudentClasses` / `getStudentSchedule`
+- ✅ 调用 `homework/data-access` 的 `getStudentDashboardGrades` / `getStudentHomeworkAssignments`
+- ✅ 不直接查询任何表
+
+**教师仪表盘**（`app/(dashboard)/teacher/dashboard/page.tsx`）：
+- ✅ 调用 `classes/data-access` 的 `getClassSchedule` / `getTeacherClasses`
+- ✅ 调用 `homework/data-access` 的 `getHomeworkAssignments` / `getHomeworkSubmissions` / `getTeacherGradeTrends`
+- ⚠️ 第 18-21 行直接查询 `users` 表获取教师姓名：`db.query.users.findFirst(...)` — 应使用 users 模块的 data-access
+
+### 4.3 建议方案
+
+**方案 A（理想）：聚合 API 模式**
+
+为每个模块添加 `getModuleStats(scope?)` 函数，dashboard 聚合调用：
+```typescript
+const [userStats, classStats, textbookStats, ...] = await Promise.all([
+  getUsersStats(scope),
+  getClassStats(scope),
+  getTextbookStats(),
+  ...
+])
+```
+
+**方案 B（务实）：接受 dashboard 作为跨模块聚合层**
+
+- 在架构图中明确标注 dashboard 对所有业务模块的依赖
+- 将 scope 过滤逻辑下沉到各模块的 `getStats` 函数
+- 至少消除 dashboard 中重复实现的 exam/homework scope 过滤（第 31-73 行）
+
+---
+
+## 五、其他模块审查
+
+### 5.1 messaging 模块
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 245 | 9 个 Server Action（私信 + 通知 + 偏好） |
+| `data-access.ts` | 252 | 私信 CRUD + 通知 CRUD + 收件人查询 |
+| `notification-preferences.ts` | 166 | 通知偏好 CRUD |
+| `schema.ts` | 17 | 私信发送校验 |
+| `types.ts` | 108 | 私信 + 通知 + 偏好类型 |
+
+#### 问题
+
+- ❌ **职责过多**：同时管理私信（messages）、站内通知（messageNotifications）、通知偏好（notificationPreferences）三类数据
+- ❌ **与 notifications 模块边界模糊**：详见第三节
+- ⚠️ `getRecipients` 函数（第 227-251 行）根据 dataScope 查询收件人，逻辑较复杂，可考虑下沉到 users 模块
+
+### 5.2 parent 模块
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `data-access.ts` | 234 | 子女关系 + 子女仪表盘数据聚合 |
+| `types.ts` | 57 | 类型定义 |
+| `components/` | 7 个 | 子女卡片 + 详情 + 仪表盘 |
+
+#### 评价
+
+- ✅ **职责单一**：仅负责家长视角的子女数据聚合与展示
+- ✅ **正确复用其他模块**：
+  - 调用 `classes/data-access` 的 `getStudentClasses` / `getStudentSchedule`
+  - 调用 `homework/data-access` 的 `getStudentDashboardGrades` / `getStudentHomeworkAssignments`
+  - 调用 `grades/data-access` 的 `getStudentGradeSummary`
+- ✅ 不直接查询业务表（仅查询 `parentStudentRelations` 自有表 + `users`/`classes`/`classEnrollments`/`grades` 用于基本信息）
+- ⚠️ `getChildBasicInfo` 第 74-105 行多次串行查询（grade → class），可优化为 join
+
+### 5.3 settings 模块
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `actions.ts` | 205 | AI Provider CRUD + 测试连通性 |
+| `actions-password.ts` | 113 | 修改密码 |
+| `components/` | 8 个 | 通用设置 + AI 配置 + 密码 + 主题 + 通知偏好 |
+
+#### 问题：职责混杂但可接受
+
+settings 模块混合了 5 类职责：
+1. AI Provider 管理（`actions.ts` + `ai-provider-settings-card.tsx`）
+2. 密码修改（`actions-password.ts` + `password-change-form.tsx`）
+3. 个人资料（`profile-settings-form.tsx`）
+4. 主题偏好（`theme-preferences-card.tsx`）
+5. 通知偏好表单（`notification-preferences-form.tsx` — **调用 messaging 模块的 Action**）
+
+**评价**：
+- ⚠️ AI Provider 管理与"用户设置"语义距离较远，可考虑独立为 `ai-config` 模块
+- ⚠️ `notification-preferences-form.tsx` 第 14 行 import `updateNotificationPreferencesAction` from `@/modules/messaging/actions` — 跨模块 UI 依赖
+- ✅ 密码修改有速率限制（`actions-password.ts` 第 33-37 行）
+- ✅ AI Provider 操作有 `AI_CONFIGURE` 权限校验
+- ✅ 密码修改仅要求 `requireAuth()`（自助操作），符合最小权限原则
+- ⚠️ 无 `data-access.ts` 文件，`actions.ts` 直接使用 `db` — 建议抽取 data-access 层
+
+### 5.4 files 模块
+
+#### 模块结构
+
+| 文件 | 行数 | 职责 |
+|------|------|------|
+| `data-access.ts` | 267 | 文件附件 CRUD + 批量删除 + 统计 |
+| `types.ts` | - | 类型定义 |
+| `components/` | 6 个 | 上传 + 列表 + 预览 + 管理 |
+
+#### 评价
+
+- ✅ **职责单一**：仅管理 `fileAttachments` 表
+- ✅ 不跨模块查询
+- ✅ 批量删除有容错处理（第 152-177 行，失败时回退到逐条删除）
+- ⚠️ 所有函数都用 try-catch 吞掉错误返回空数组/null，可能掩盖真实问题
+- ⚠️ 无 actions.ts 文件 — 文件上传通过 `app/api/upload/route.ts` 和 `app/api/files/[id]/route.ts` 实现，data-access 被路由直接调用
+
+### 5.5 auth 模块
+
+#### 模块结构
+
+| 文件 | 职责 |
+|------|------|
+| `components/auth-layout.tsx` | 认证页面布局 |
+| `components/login-form.tsx` | 登录表单 |
+| `components/register-form.tsx` | 注册表单 |
+
+#### 评价
+
+- ✅ **纯 UI 模块**：无 data-access / actions / types 文件
+- ✅ 认证逻辑由 NextAuth + `shared/lib/auth-guard` 统一处理
+- ✅ 职责清晰
+
+### 5.6 layout 模块
+
+#### 模块结构
+
+| 文件 | 职责 |
+|------|------|
+| `components/app-sidebar.tsx` | 侧边栏（根据权限渲染导航） |
+| `components/sidebar-provider.tsx` | 侧边栏状态 Context |
+| `components/site-header.tsx` | 顶部导航（含通知下拉） |
+| `config/navigation.ts` | 导航配置（4 个角色） |
+
+#### navigation.ts 幽灵路由审查
+
+**结论：✅ 无幽灵路由**（007 报告中提到的 13 个幽灵路由已全部修复）
+
+逐一核对导航配置中的所有 href 与 `src/app/` 下的实际页面：
+
+| 角色 | 导航项数 | 全部存在 | 备注 |
+|------|---------|---------|------|
+| admin | 19 | ✅ | 包括子菜单项 |
+| teacher | 22 | ✅ | 包括子菜单项 |
+| student | 12 | ✅ | 包括子菜单项 |
+| parent | 5 | ✅ | 包括子菜单项 |
+
+#### 存在但未纳入导航的页面
+
+| 路由 | 说明 | 建议 |
+|------|------|------|
+| `/admin/attendance` | 管理员考勤页面 | 如需管理员查看全校考勤，应加入 admin 导航 |
+| `/admin/files` | 管理员文件管理 | 应加入 admin 导航 |
+| `/parent/children/[studentId]` | 子女详情页 | 通过仪表盘卡片跳转，可不加入导航 |
+| `/settings/security` | 安全设置子页 | 通过 settings 页 Tab 切换，无需独立导航 |
+| `/profile` | 个人主页 | 通过 header 头像菜单跳转，无需独立导航 |
+
+#### 其他发现
+
+- ✅ `app-sidebar.tsx` 第 36-43 行根据权限动态选择角色导航配置，符合 RBAC
+- ⚠️ 第 39 行判断学生逻辑：`permissions.includes(Permissions.HOMEWORK_SUBMIT) && !permissions.includes(Permissions.EXAM_CREATE)` — 用权限反推角色，不够直观，建议改用 `hasRole("student")`
+
+### 5.7 student 模块
+
+#### 模块结构
+
+| 文件 | 职责 |
+|------|------|
+| `components/student-courses-view.tsx` | 学生课程视图 |
+| `components/student-schedule-filters.tsx` | 课表筛选器 |
+| `components/student-schedule-view.tsx` | 学生课表视图 |
+
+#### 评价
+
+- ✅ **纯 UI 模块**：无 data-access / actions / types
+- ✅ 数据由 `app/(dashboard)/student/learning/courses/page.tsx` 和 `app/(dashboard)/student/schedule/page.tsx` 通过 classes 模块的 data-access 获取
+- ⚠️ 与 classes 模块的 `schedule-view.tsx` / `schedule-filters.tsx` 可能存在功能重叠，建议核查
+
+---
+
+## 六、跨模块依赖关系图
+
+```
+dashboard ──直查──> users, classes, textbooks, questions, exams, homework (11 张表)
+parent ──调用──> classes, homework, grades (data-access)
+diagnostic ──直查──> examSubmissions, submissionAnswers, questionsToKnowledgePoints, classes
+notifications ──依赖──> messaging (偏好 + in-app 渠道)
+messaging ──绕过──> notifications (直接写 messageNotifications)
+proctoring ──直查──> exams, examSubmissions, users
+settings ──调用──> messaging (通知偏好 Action)
+```
+
+---
+
+## 七、修复优先级
+
+### P0（严重，应立即修复）
+
+| 序号 | 问题 | 模块 | 工作量 | 影响 |
+|------|------|------|--------|------|
+| 1 | messaging 绕过 notifications 直接写通知 | messaging | 小 | 用户通知偏好失效，多渠道通知无效 |
+| 2 | proctoring/exam-mode-config.tsx 未集成 | proctoring | 小 | 监考功能无法启用，组件为死代码 |
+| 3 | proctoring 事件上报双通道重复 | proctoring | 小 | 代码重复，维护成本 |
+| 4 | notifications 反向依赖 messaging | notifications | 中 | 架构耦合，难以独立演进 |
+
+### P1（中等问题，下个迭代修复）
+
+| 序号 | 问题 | 模块 | 工作量 |
+|------|------|------|--------|
+| 5 | dashboard 直查 11 张跨模块表 | dashboard | 大 |
+| 6 | diagnostic 跨模块直查 4 张表 | diagnostic | 中 |
+| 7 | notifications 无 notification_logs 表 | notifications | 中 |
+| 8 | sendClassNotificationAction 直查 classes 表 | notifications | 小 |
+| 9 | elective 两个 data-access 文件代码重复 | elective | 小 |
+| 10 | settings/notification-preferences-form 跨模块依赖 | settings | 小 |
+
+### P2（轻微问题，机会修复）
+
+| 序号 | 问题 | 模块 |
+|------|------|------|
+| 11 | diagnostic/data-access-reports.ts 有未使用代码 | diagnostic |
+| 12 | diagnostic 班级报告 studentId 字段复用 | diagnostic |
+| 13 | elective runLottery 使用 Math.random | elective |
+| 14 | teacher dashboard 直查 users 表 | dashboard |
+| 15 | files 模块 try-catch 吞错误 | files |
+| 16 | layout 用权限反推角色 | layout |
+
+---
+
+## 八、总结
+
+### 新增模块质量
+
+- **elective**：✅ 质量较好，拆分合理但有代码重复
+- **proctoring**：⚠️ 有死代码（exam-mode-config 未集成）和重复实现（双通道上报）
+- **diagnostic**：✅ 与 grades 无重叠，但跨模块耦合较重
+- **notifications**：⚠️ 渠道抽象优秀，但与 messaging 边界模糊、反向依赖
+
+### 重点问题回答
+
+1. **elective 拆分为 3 个 data-access 文件是否合理？**
+   合理，但需消除 `data-access.ts` 与 `data-access-selections.ts` 之间的代码重复
+
+2. **proctoring 模块职责是否清晰？**
+   基本清晰，但 `exam-mode-config.tsx` 应属于 exams 模块或集成到考试表单
+
+3. **diagnostic 与 grades 是否有职责重叠？**
+   无重叠。grades 管分数记录，diagnostic 管知识点掌握度，数据来源和维度均不同
+
+4. **notifications 与 messaging 边界是否清晰？**
+   不清晰。存在双向依赖、类型不一致、职责重叠三个问题，建议按方案 A 合并
+
+5. **dashboard 是否直查其他模块的表？**
+   是。`getAdminDashboardData` 直查 11 张跨模块表，是本次审查最严重的封装违规
+
+6. **settings 是否混入太多职责？**
+   混合了 5 类职责，但作为"设置"聚合点尚可接受。AI Provider 管理可考虑独立
+
+7. **navigation.ts 是否有幽灵路由？**
+   无。007 报告中的 13 个幽灵路由已全部修复

docs/architecture/audit/shared-audit.md

@@ -0,0 +1,196 @@
+# Shared 基础设施层审查报告
+
+> 审查日期：2026-06-17
+> 审查范围：`src/shared/`（db、lib、hooks、components、types）+ `src/auth.ts` + `src/proxy.ts`
+> 审查依据：职责单一性、函数复杂度、模块间耦合、架构文档完整性
+
+## 概览
+
+- 文件总数：69（不含测试文件）
+  - `db/`：3
+  - `lib/`：13
+  - `hooks/`：7
+  - `components/ui/`：34
+  - `components/a11y/`：4
+  - `components/`（顶层）：4
+  - `types/`：2
+  - `src/auth.ts`、`src/proxy.ts`：2
+- 发现问题数：15
+- 严重程度分布：高 3 / 中 9 / 低 3
+
+---
+
+## 职责单一性问题
+
+### 1. `src/shared/db/schema.ts`
+
+- **问题**：单个文件包含 54 张表定义，共 1111 行，**超过项目规则中"任何文件不超过 1000 行"的硬性上限**。文件涵盖用户、认证、题库、教学、学校、班级、考试、作业、AI、公告、审计、成绩、文件、课程计划、消息、考勤、排课、选课、监考、学情诊断等十余个业务域。此外分节编号混乱：section 12（Parent-Student Relations，行 958）出现在 section 14b（Notification Preferences，行 934）之后，P2 段落与主编号交错。
+- **严重程度**：高
+- **建议**：按业务域拆分为多个 schema 文件（如 `schema/auth.ts`、`schema/academic.ts`、`schema/exam.ts`、`schema/audit.ts` 等），通过 `schema/index.ts` 聚合导出。同时修正分节编号。
+
+### 2. `src/auth.ts`
+
+- **问题**：293 行，混合了多种职责：
+  1. NextAuth 配置（providers、callbacks、events）
+  2. 密码安全 DB 操作（`getOrCreatePasswordSecurity`、`recordFailedLogin`、`resetFailedLogin`，行 56-130）——这些是数据访问层逻辑，不应内联在认证配置中
+  3. 角色规范化工具（`normalizeRole`、`resolvePrimaryRole`，行 13-27）
+  4. bcrypt 哈希规范化（`normalizeBcryptHash`，行 29-33）
+  5. IP 解析（`resolveClientIp`，行 39-51）
+  6. `authorize` 回调内联了限流、锁定检查、密码比对、日志记录全流程（86 行）
+- **严重程度**：高
+- **建议**：将密码安全 DB 操作迁移到 `shared/lib/password-security-service.ts`（与纯函数的 `password-policy.ts` 区分）；角色规范化迁移到 `shared/lib/permissions.ts` 或新建 `shared/lib/role-utils.ts`；`resolveClientIp` 迁移到 `shared/lib/http-utils.ts`（与三个 logger 共用）。
+
+### 3. `src/shared/lib/ai.ts`
+
+- **问题**：218 行，混合了 5 类职责：
+  1. 请求负载解析与校验（`parseAiChatPayload`，行 70-96）
+  2. API Key 加密/解密（`encryptAiApiKey`/`decryptAiApiKey`，行 104-124）
+  3. Provider 配置 DB 查询（`getAiProviderConfig`，行 126-179）
+  4. AI 客户端创建与调用（`getAiClient`、`createAiChatCompletion`、`testAiProviderConfig`、`testAiProviderById`）
+  5. 错误格式化（`getAiErrorMessage`）
+  
+  其中加密/解密与 Provider 配置查询属于数据层，与 AI 调用本身是不同关注点。
+- **严重程度**：中
+- **建议**：将加密/解密拆到 `shared/lib/crypto.ts`（通用加密工具）；将 Provider 配置查询拆到 `shared/lib/ai-provider-repo.ts`（数据访问）。`ai.ts` 保留负载解析与 AI 调用编排。
+
+### 4. `src/shared/components/onboarding-gate.tsx`
+
+- **问题**：312 行组件，混合了：
+  1. 多步表单 UI
+  2. 角色推断业务逻辑（行 90-94）：通过权限反推角色（`isAdmin`/`isTeacher`/`isStudent`/`isParent`），逻辑脆弱且未使用 `usePermission().hasRole()`
+  3. 硬编码教学学科列表（`TEACHER_SUBJECTS`，行 20）——业务数据固化在 shared 基础设施
+  4. 直接 `fetch("/api/onboarding/status")` 和 `fetch("/api/onboarding/complete")`——耦合特定 API 路由
+- **严重程度**：中
+- **建议**：角色判断改用 `usePermission().hasRole()` 或 session 的 `role` 字段；学科列表迁移到 modules 层配置或 DB；API 调用通过 Server Action 封装。组件本身可考虑按步骤拆分子组件。
+
+### 5. `src/shared/components/global-search.tsx`
+
+- **问题**：221 行组件，混合了：
+  1. 搜索 UI 与下拉渲染
+  2. 硬编码业务类型（`ResultType = "question" | "textbook" | "exam" | "announcement"`，行 12）与图标/标签映射（行 30-42）——业务知识泄漏到 shared 层
+  3. 直接 `fetch("/api/search?...")`——耦合特定 API 路由与查询协议
+  4. 快捷键、点击外部、键盘导航等交互逻辑内联
+- **严重程度**：中
+- **建议**：搜索结果类型与图标映射应由 API 返回或从 modules 层注入；API 调用抽取为独立 hook（`useGlobalSearch`）；交互逻辑可拆为 `useSearchKeyboard` 等。
+
+### 6. `src/proxy.ts`
+
+- **问题**：75 行，硬编码了路由-权限映射（`ROUTE_PERMISSIONS`、`API_PERMISSIONS`，行 8-19），使用原始字符串如 `"school:manage"`、`"exam:read"`，**未复用 `Permissions` 常量**，违反项目规则"前端组件禁止硬编码 role/权限"的精神。`resolveDefaultPath`（行 21-27）将角色到默认路径的业务映射硬编码在代理中。
+- **严重程度**：中
+- **建议**：权限字符串改用 `Permissions.SCHOOL_MANAGE` 等常量；路由权限映射迁移到 `shared/lib/route-permissions.ts` 配置文件；角色-路径映射迁移到 modules 层或路由配置。
+
+### 7. `src/shared/lib/a11y.ts`
+
+- **问题**：`useA11yId`（行 7-10）是一个 React Hook，但放置在 `lib/` 目录而非 `hooks/` 目录。项目约定 `hooks/` 存放所有自定义 Hook，`lib/` 存放纯工具函数。该文件其余函数（`mergeA11yProps`、`describeInput`、`loadingAria`）是纯函数，放置正确。
+- **严重程度**：低
+- **建议**：将 `useA11yId` 迁移到 `shared/hooks/use-a11y-id.ts`，`a11y.ts` 保留纯函数。
+
+---
+
+## 过耦合函数
+
+### 1. `resolveDataScope` @ `src/shared/lib/auth-guard.ts:64-130`
+
+- **行数**：67
+- **参数数**：2（`userId: string`, `roleNames: string[]`）
+- **问题**：单个函数内根据角色分支查询 4 张不同的表（`grades`、`classes`、`classSubjectTeachers`、`parentStudentRelations`），将权限范围解析与数据访问混合。每个角色分支的查询逻辑独立，新增角色需修改此函数，违反开闭原则。
+- **建议**：将各角色的数据范围查询拆为独立函数（如 `resolveTeacherScope`、`resolveParentScope`），或迁移到各模块的 data-access 层，`resolveDataScope` 仅做分发。
+
+### 2. `getAiProviderConfig` @ `src/shared/lib/ai.ts:126-179`
+
+- **行数**：53
+- **参数数**：1（`providerId?: string`）
+- **问题**：函数内有三段几乎相同的 DB 查询分支（按 providerId、按 isDefault、fallback），每段都 select 相同的字段、解密 apiKey、返回相同结构，存在明显代码重复。
+- **建议**：提取公共 `mapProviderRow(row)` 函数，三个分支简化为查询条件不同。或合并为单查询带 OR 条件 + 排序优先级。
+
+### 3. `authorize`（NextAuth Credentials 回调）@ `src/auth.ts:143-229`
+
+- **行数**：86
+- **参数数**：1（`credentials`）
+- **问题**：单函数内串联了：邮箱密码校验 → 速率限制 → DB 用户查询 → 账户锁定检查 → 密码比对 → 失败计数 → 成功重置 → 角色查询 → 返回。流程长且混合了限流、安全策略、认证、日志多个关注点。内部还使用 `Promise.all` + 动态 `import`（行 165-168）加载 `@/shared/db` 和 schema，写法不寻常。
+- **建议**：将流程拆分为 `checkRateLimit`、`checkAccountLockout`、`verifyPassword`、`loadUserRoles` 等步骤函数，`authorize` 仅编排。动态 import 改为静态 import。
+
+### 4. `OnboardingGate` 组件 @ `src/shared/components/onboarding-gate.tsx:27-312`
+
+- **行数**：285（组件函数体）
+- **参数数**：0（无 props，内部消费 session）
+- **问题**：单组件承担了状态检查、4 步表单、角色推断、API 提交、路由跳转。组件内 9 个 `useState`，3 个 `useEffect`，逻辑密集。
+- **建议**：按步骤拆分为 `OnboardingRoleStep`、`OnboardingProfileStep`、`OnboardingRoleDetailStep`、`OnboardingCompleteStep` 子组件；提取 `useOnboarding` hook 封装状态与提交逻辑。
+
+### 5. `GlobalSearch` 组件 @ `src/shared/components/global-search.tsx:49-221`
+
+- **行数**：172（组件函数体）
+- **参数数**：2（`className?`, `placeholder?`）
+- **问题**：单组件承担了输入控制、防抖搜索、快捷键监听、点击外部关闭、键盘导航、结果渲染。6 个 `useState`，3 个 `useEffect`。
+- **建议**：提取 `useGlobalSearch(query)` hook 封装搜索请求与状态；提取 `useSearchKeyboard` 封装快捷键与导航。组件仅负责渲染。
+
+---
+
+## 模块间依赖问题
+
+### 1. shared 层与 `@/auth` 的循环依赖
+
+- **涉及模块**：`shared/lib/{audit-logger, change-logger, auth-guard}` → `@/auth` → `shared/lib/{login-logger, permissions, password-policy, rate-limit}` + `shared/db`
+- **问题类型**：循环依赖
+- **问题详情**：
+  - `shared/lib/audit-logger.ts`（行 7）`import { auth } from "@/auth"`
+  - `shared/lib/change-logger.ts`（行 6）`import { auth } from "@/auth"`
+  - `shared/lib/auth-guard.ts`（行 1）`import { auth } from "@/auth"`
+  - 而 `src/auth.ts` 反向依赖 `shared/lib/permissions`、`shared/lib/login-logger`、`shared/lib/password-policy`、`shared/lib/rate-limit`、`shared/db`
+  
+  这构成了 `shared/lib/*` → `auth` → `shared/lib/*` 的循环。虽然 NextAuth 的 `auth()` 函数是运行时调用而非模块级副作用，目前不会导致运行时错误，但架构上 shared 基础设施层不应反向依赖业务层的认证入口。
+- **建议**：将 `auth()` 的 session 获取抽象为接口或通过参数注入。logger 函数改为接收 `session` 参数（由调用方传入），而非内部调用 `auth()`。或创建 `shared/lib/session.ts` 封装 session 获取，`auth.ts` 和 logger 都依赖它，打破循环。
+
+### 2. shared 层对根模块 `@/auth` 的反向依赖
+
+- **涉及模块**：`shared/lib/*` → `@/auth`（根模块）
+- **问题类型**：反向依赖
+- **问题详情**：`src/auth.ts` 位于项目根目录，属于应用层（非 shared 层）。shared 层应是被依赖方，不应依赖应用层模块。三个文件（audit-logger、change-logger、auth-guard）直接 import `@/auth`，使 shared 层无法独立测试或复用。
+- **建议**：同上，通过依赖注入或提取 `shared/lib/session.ts` 解耦。
+
+### 3. 三个 logger 重复实现 IP/Header 提取
+
+- **涉及模块**：`shared/lib/audit-logger`、`shared/lib/change-logger`、`shared/lib/login-logger`、`src/auth.ts`
+- **问题类型**：过度耦合（DRY 违反）
+- **问题详情**：三个 logger 各自重复实现相同的 IP/User-Agent 提取逻辑：
+  - `audit-logger.ts`（行 27-32）：`headerList.get("x-forwarded-for") ?? headerList.get("x-real-ip") ?? "unknown"`
+  - `change-logger.ts`（行 27-31）：相同逻辑
+  - `login-logger.ts`（行 26-31）：相同逻辑
+  - `auth.ts`（行 39-51）：`resolveClientIp` 也是类似逻辑（取 `x-forwarded-for` 第一段）
+  
+  四处实现略有差异（auth.ts 取逗号分隔第一段，其他取全值），存在不一致风险。
+- **建议**：提取 `shared/lib/http-utils.ts`，导出 `getClientIp()` 和 `getUserAgent()` 统一复用。
+
+---
+
+## 架构文档改进建议
+
+1. **补充依赖关系图**：当前 004 文档以函数/常量为粒度列举导出，但缺少模块间依赖方向的可视化图。建议在 005 JSON 中增加 `dependencyMatrix` 节点，记录 `shared/lib/* → @/auth`、`@/auth → shared/lib/*` 等依赖边，并在 004 Markdown 中用 Mermaid 图渲染。本次审查发现的循环依赖（shared ↔ auth）在当前文档中完全不可见。
+
+2. **标注循环依赖与反向依赖**：004/005 文档应明确标注 `shared/lib/{audit-logger, change-logger, auth-guard}` 对 `@/auth` 的依赖，以及这与 `@/auth` 对 `shared/lib/*` 的依赖构成的循环。当前文档将 `auth` 模块与 `shared` 模块分别描述，未揭示二者双向依赖。
+
+3. **修正 schema.ts 分节编号**：004 文档的"数据库表"章节按表名平铺列举，未反映 schema.ts 源文件中的分节结构。建议文档增加 schema.ts 分节映射表，并修正源文件中 section 12 出现在 section 14b 之后的编号混乱。
+
+4. **增加 shared 层边界说明**：004 文档应明确 shared 层"不应依赖应用层模块（如 `@/auth`）"的架构约束，以及哪些文件属于 shared 层的对外公共 API。当前文档未说明 shared 与根模块（auth.ts、proxy.ts）的边界。
+
+5. **补充函数复杂度标注**：005 JSON 中每个函数已有签名记录，但缺少行数与参数数量字段。建议增加 `"lines"` 和 `"paramCount"` 字段，便于自动识别过耦合函数（如本次发现的 `authorize` 86 行、`resolveDataScope` 67 行）。
+
+6. **记录 proxy.ts 的路由权限映射**：004 文档未记录 `proxy.ts` 中的 `ROUTE_PERMISSIONS` 和 `API_PERMISSIONS` 硬编码映射，也未说明这些映射与 `Permissions` 常量的关系。建议在 005 JSON 的 `routes` 节点中补充代理层权限规则。
+
+---
+
+## 附：审查范围文件清单
+
+| 目录 | 文件数 | 最大文件（行数） | 备注 |
+|------|--------|------------------|------|
+| `src/shared/db/` | 3 | schema.ts (1111) | **超过 1000 行硬性上限** |
+| `src/shared/lib/` | 13 | ai.ts (218) | |
+| `src/shared/hooks/` | 7 | use-aria-live.ts (88) | |
+| `src/shared/components/ui/` | 34 | chart.tsx (329) | 多为标准 shadcn/ui 组件 |
+| `src/shared/components/a11y/` | 4 | focus-trap.tsx (110) | |
+| `src/shared/components/`（顶层） | 4 | onboarding-gate.tsx (312) | |
+| `src/shared/types/` | 2 | permissions.ts (92) | |
+| `src/auth.ts` | 1 | auth.ts (293) | |
+| `src/proxy.ts` | 1 | proxy.ts (75) | |
+
+> 注：`components/ui/` 下 34 个文件多为 shadcn/ui 标准生成组件（基于 Radix UI），职责单一，未发现结构性问题，故未逐一列入问题清单。`chart.tsx`（329 行）为标准 shadcn chart 组件，行数较高但属框架约定，可接受。