# 新增模块与其他模块架构审查报告

> 审查范围：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，类型系统不一致~~ ✅ 已修复（P0-5 + P1-6）
2. ~~**dashboard/data-access.ts 直查 11 张跨模块表** — 违反模块封装原则~~ ✅ 已修复（P0-4）
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-form.tsx`。

#### 严重问题 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 边界分析"。~~

**已完成修复**（2026-06-17，P0-5 + P1-6）：
- messaging/actions.ts 改用 `sendNotification` from `@/modules/notifications/dispatcher`（P0-5）
- notifications/channels/in-app-channel.ts 将静态 import 改为动态 `await import("@/modules/messaging/data-access")`，打破模块级静态反向依赖（P1-6）
- 依赖方向已统一：messaging → 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 边界分析（重点）✅ 已修复

> **状态**：双向依赖与绕过 dispatcher 问题已于 2026-06-17 修复（P0-5 + P1-6）。以下为修复前的现状记录，保留作为历史参考。

### 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/channels/in-app-channel.ts 将静态 import 改为动态 `await import("@/modules/messaging/data-access")`，打破模块级静态反向依赖。运行时调用链保持不变，但模块加载图无环。

#### 问题 2：messaging 绕过 notifications 直接写通知 ✅ 已修复

~~`messaging/actions.ts` 第 66-72 行：~~

```typescript
// ~~Notify the receiver about the new message~~
// ~~await createNotification({~~
// ~~  userId: input.receiverId,~~
// ~~  type: "message",~~
// ~~  ...~~
// ~~})~~
```

**修复方案**：messaging/actions.ts 改用 `sendNotification` from `@/modules/notifications/dispatcher`，通知现在会经过 dispatcher 的渠道选择逻辑，尊重用户偏好（SMS/Email/WeChat/In-App）。

#### 问题 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)`，虽然不会报错，但语义混乱。（P2 待统一）

#### 问题 4：notification-preferences 归属不清（保留）

- `notificationPreferences` 表的 data-access 在 messaging 模块
- 但 notifications 模块的 dispatcher 依赖此偏好决定渠道
- settings 模块的 `notification-preferences-form.tsx` 调用 `messaging/actions.ts` 的 `updateNotificationPreferencesAction`
- 三个模块都在操作同一份数据，职责归属不清（P2 待重构）

### 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` 函数直接查询以下表~~

**已完成修复**（2026-06-17，P0-4）：dashboard/data-access.ts 从大文件降至 42 行，改为并行调用 6 个模块的 stats 函数：

```typescript
const [usersStats, classesStats, textbooksStats, questionsStats, examsStats, homeworkStats] = await Promise.all([
  getUsersDashboardStats(),
  getClassesDashboardStats(),
  getTextbooksDashboardStats(),
  getQuestionsDashboardStats(),
  getExamsDashboardStats(scope),
  getHomeworkDashboardStats(scope),
])
```

不再直接查询任何业务表，完全通过各模块 data-access 暴露的聚合查询函数获取数据。

### 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~~ | ~~小~~ | ~~用户通知偏好失效，多渠道通知无效~~ | ✅ 已修复（P0-5） |
| 2 | proctoring/exam-mode-config.tsx 未集成 | proctoring | 小 | 监考功能无法启用，组件为死代码 | ⚠️ 用户决定保留 |
| 3 | proctoring 事件上报双通道重复 | proctoring | 小 | 代码重复，维护成本 | ❌ 待修复 |
| ~~4~~ | ~~notifications 反向依赖 messaging~~ | ~~notifications~~ | ~~中~~ | ~~架构耦合，难以独立演进~~ | ✅ 已修复（P1-6） |

### P1（中等问题，下个迭代修复）

| 序号 | 问题 | 模块 | 工作量 | 状态 |
|------|------|------|--------|------|
| ~~5~~ | ~~dashboard 直查 11 张跨模块表~~ | ~~dashboard~~ | ~~大~~ | ✅ 已修复（P0-4） |
| 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 的双向依赖已修复（P0-5 + P1-6）

### 重点问题回答

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 边界是否清晰？**
   ✅ 已修复。双向依赖通过动态 import 打破，messaging 改用 notifications/dispatcher 发送通知，依赖方向统一为 messaging → notifications

5. **dashboard 是否直查其他模块的表？**
   ✅ 已修复。`getAdminDashboardData` 改为并行调用各模块的 `get[Module]DashboardStats()` 函数，不再直接查询任何业务表

6. **settings 是否混入太多职责？**
   混合了 5 类职责，但作为"设置"聚合点尚可接受。AI Provider 管理可考虑独立

7. **navigation.ts 是否有幽灵路由？**
   无。007 报告中的 13 个幽灵路由已全部修复