# 数据库访问层重构专项 - 审计框架 v1

> 创建日期：2026-07-07
> 目标：对全项目 86 个 `data-access*.ts` + ~30 个 `actions.ts` 进行深度审计，输出可执行的分级治理路线图
> 推进路径：先审计后治理（用户已确认）
> 执行方案：纯深读（用户已确认方案 B）

---

## 一、审计范围

### 1.1 文件范围

| 类型 | 路径模式 | 文件数（约） | 备注 |
|---|---|---|---|
| 数据访问层 | `src/modules/**/data-access*.ts` | 86 | 主审计对象 |
| Server Actions | `src/modules/**/actions.ts` | ~30 | 辅查（权限校验、业务逻辑归属） |
| 辅助文件 | `src/modules/**/schema.ts`、`types.ts` | 按需 | 仅当 data-access 引用时查看 |

### 1.2 排除范围

- `src/app/**`：仅在 A-05 规则（app 直访 DB）触发时反向查看
- `src/shared/**`：仅在 A-07 规则（shared 反向依赖）触发时查看
- 已有的模块级 audit 报告（`docs/architecture/audit/*-audit-report.md`）：作为参考但不直接复用，因本次为横切关注点

### 1.3 模块分组（并行执行单元）

| 组 | 模块 | data-access 文件数 | sub-agent |
|---|---|---|---|
| **G1 核心教学 A** | lesson-preparation（12）+ questions + textbooks | ~16 | agent-1 |
| **G2 核心教学 B** | exams + homework（7）+ grades（6）+ diagnostic + adaptive-practice（3） | ~21 | agent-2 |
| **G3 教学管理** | classes（6）+ school + scheduling + attendance（3）+ course-plans + proctoring | ~16 | agent-3 |
| **G4 用户与沟通** | users + messaging + notifications + parent + audit + auth + rbac（3） | ~12 | agent-4 |
| **G5 扩展与设置** | elective（5）+ settings（5）+ dashboard + files + search + onboarding + ai + announcements + error-book（3） | ~21 | agent-5 |

---

## 二、审计维度与检查规则

### 2.1 维度 1：模式标准化（Pattern Standardization）

| 规则 ID | 检查项 | 期望状态 | 检测方式 |
|---|---|---|---|
| P-01 | `import "server-only"` 文件头 | 每个文件首行 | 静态 |
| P-02 | 类型导入使用 `import type` | 类型导入与值导入分离 | 静态 |
| P-03 | 读函数是否走 `cacheFn` 包装（Raw + Wrapper 配对） | 全部覆盖 | 深读 |
| P-04 | 函数返回类型显式标注 `Promise<T>` | 无隐式推断 | 深读 |
| P-05 | 错误处理一致 | data-access 层用 throw，actions 层用 ActionState | 深读 |
| P-06 | 分页参数命名统一 | `page`/`pageSize` 或 `limit`/`offset` 全局统一 | 深读 |
| P-07 | 日期序列化走 helper | `serializeDate`/`toISODateString` | 深读 |
| P-08 | 列表项映射走 `mapListItem` 模式 | 避免 inline mapping 重复 | 深读 |
| P-09 | `as` 断言出现次数 | 0（除 unknown 收窄） | 静态 |
| P-10 | `any` 出现次数 | 0 | 静态 |

### 2.2 维度 2：性能与查询优化（Performance）

| 规则 ID | 检查项 | 期望状态 | 检测方式 |
|---|---|---|---|
| F-01 | 循环内 SQL 调用（N+1） | 改批量查询 + Map 解析 | 深读 |
| F-02 | `LIKE '%xxx%'` 全表扫描 | 改 FULLTEXT 或前缀匹配 | 深读 |
| F-03 | SELECT * 未指定列 | 显式列枚举 | 深读 |
| F-04 | JOIN 表数量 > 3 | 评估拆分或冗余字段 | 深读 |
| F-05 | 大表查询无 LIMIT | 添加默认 LIMIT | 深读 |
| F-06 | 重复查询同表/同条件 | 走 cacheFn 或合并查询 | 深读 |
| F-07 | 缺失索引（高频 WHERE 字段） | 提示加索引 | 深读 |
| F-08 | 跨模块多次调用 `getXxxNamesByIds` | 批量化 | 深读 |
| F-09 | 事务范围过大（含网络调用） | 收紧事务 | 深读 |
| F-10 | `count()` 全表统计无过滤 | 添加过滤条件 | 深读 |

### 2.3 维度 3：架构违规治理（Architecture）

| 规则 ID | 检查项 | 期望状态 | 检测方式 |
|---|---|---|---|
| A-01 | data-access 含 `requirePermission` 调用 | 移至 actions | 静态 |
| A-02 | data-access 含业务逻辑（条件分支、状态机） | 移至 actions 或 lib | 深读 |
| A-03 | data-access 含 `"use server"` 标记 | 移至 actions | 静态 |
| A-04 | data-access 含 `revalidatePath` 调用 | 移至 actions | 静态 |
| A-05 | app/ 直接 import `@/shared/db` | 违规，改走 data-access | 静态 |
| A-06 | modules 间直接 import 对方 `@/shared/db/schema` 表 | 改走对方 data-access | 静态 |
| A-07 | shared/ 反向 import `@/auth`/`@/proxy`/`modules/*` | 违规 | 静态 |
| A-08 | actions.ts 漏调 `requirePermission` | 补齐 | 深读 |
| A-09 | actions.ts 含直接 DB 查询 | 移至 data-access | 深读 |
| A-10 | data-access 含 `console.log` 调试代码 | 删除 | 静态 |

### 2.4 维度 4：结构与可维护性（Structure）

| 规则 ID | 检查项 | 期望状态 | 检测方式 |
|---|---|---|---|
| S-01 | 文件行数 > 800 行警告，> 1000 行必须拆分 | 拆分 | 静态 |
| S-02 | 单文件导出函数数 > 20 | 警告，考虑拆分 | 静态 |
| S-03 | 重复 helper（多模块各自实现 serializeDate/buildScopeFilter 等） | 提取到 shared/lib | 深读 |
| S-04 | 过细拆分（同模块 ≥ 5 个子文件且单文件 < 100 行） | 评估合并 | 静态 |
| S-05 | 未使用导出（dead code） | 删除 | 深读 |
| S-06 | 公共导出函数缺 JSDoc | 补齐 | 深读 |
| S-07 | 跨模块重复查询逻辑 | 提取共享 data-access | 深读 |
| S-08 | 模块内 data-access 与 actions 职责混淆 | 重新分层 | 深读 |

---

## 三、严重性分级

| 级别 | 含义 | 示例 | 治理窗口 |
|---|---|---|---|
| **P0 Critical** | 架构硬违规、安全漏洞、必定性能问题 | app 直访 DB、跨模块 schema 直查、actions 漏权限、N+1 循环 SQL | 立即 |
| **P1 High** | 显著性能/可维护性问题 | 超长文件（>1000 行）、缺 cacheFn 的热路径读函数、LIKE 全表扫描 | Phase 1 |
| **P2 Medium** | 模式偏差、可优化 | 错误处理不一致、缺 JSDoc、重复 helper、分页命名不统一 | Phase 2 |
| **P3 Low** | 风格问题、可选优化 | 单行格式、import 顺序、注释措辞 | Phase 3 |

---

## 四、执行流程

### 4.1 阶段 A：sub-agent 分组深读（并行）

每个 sub-agent 接收：
- 该组所有 `data-access*.ts` + 同模块 `actions.ts` 文件清单
- 完整规则表（4 维度 × 38 条规则）
- 统一输出格式（见 4.3）

每个 sub-agent 执行：
1. 完整读取每个文件（不使用 limit/offset）
2. 按规则表逐条检测
3. 命中即记录到问题清单
4. 对每个问题给出修复建议与预估工作量

### 4.2 阶段 B：主 agent 汇总

- 收集 5 个 sub-agent 的结构化输出
- 去重（同一问题被多 agent 命中时合并）
- 跨模块统计（如重复 helper 在多少模块出现）
- 生成优先级矩阵
- 编写治理路线图

### 4.3 sub-agent 输出格式

每个 sub-agent 产出 JSON 数组，每条问题：

```json
{
  "id": "G1-001",
  "file": "src/modules/lesson-preparation/data-access.ts",
  "lines": "L123-L145",
  "ruleId": "F-01",
  "severity": "P0",
  "dimension": "performance",
  "title": "循环内调用 getClassNamesByIds",
  "description": "在 for 循环内对每个 classId 单独查询 className，应改为批量查询后用 Map 解析",
  "recommendation": "提取 classIds 数组，一次调用 getClassNamesByIds(classIds)，循环内改为 map.get(classId)",
  "effort": "S (≤30 分钟)"
}
```

工作量分级：
- **XS**：≤ 15 分钟（如删除 console.log、补 import type）
- **S**：≤ 30 分钟（如替换 as 断言为类型守卫）
- **M**：≤ 2 小时（如 N+1 改批量、提取 helper）
- **L**：≤ 1 天（如拆分超长文件、跨模块重构）
- **XL**：> 1 天（如架构层重构）

---

## 五、报告输出

### 5.1 主报告

文件：`docs/architecture/audit/data-access-audit-v1.md`

结构：
1. **执行摘要**：总文件数、问题总数、P0/P1/P2/P3 分布、模块热度图
2. **量化指标仪表盘**：cacheFn 覆盖率、平均行数、`as` 断言数、违规 import 数等
3. **按维度分组的问题清单**：每条含 文件:行号、规则 ID、严重性、现状描述、修复建议、预估工作量
4. **按模块分组的问题清单**：每个模块的累计问题数与 Top 问题
5. **P0-P3 优先级矩阵**：四象限图（影响 × 紧迫度）
6. **分阶段治理路线图**：Phase 1 (P0) → Phase 2 (P1) → Phase 3 (P2) → Phase 4 (P3)
7. **附录**：完整规则表、sub-agent 原始输出索引

### 5.2 结构化数据

文件：`docs/architecture/audit/data-access-audit-v1-data.json`

字段：`issues[]`、`metrics{}`、`moduleSummary{}`、`roadmap{}`

### 5.3 速查手册同步

发现的新模式问题需追加到 `docs/troubleshooting/known-issues.md`（速查手册格式）。

---

## 六、质量约束

- **零误报**：每条问题必须给出文件:行号 + 代码证据，避免臆测
- **零遗漏**：86 个 data-access 文件必须全部深读，不得抽样
- **可执行**：每条修复建议必须具体到代码示例或操作步骤
- **不修改代码**：审计阶段只产出报告，不做任何源码修改
- **架构同步**：审计过程中发现的架构图遗漏（004/005 文档）记录到报告附录，治理阶段统一补图

---

## 七、后续衔接

审计报告 v1 完成后：

1. **用户审查报告**：确认问题清单与优先级
2. **制定治理路线图**：基于 P0-P3 分级，输出 `data-access-refactor-roadmap-v1.md`
3. **分阶段执行治理**：每阶段完成后运行 `npm run lint` + `npx tsc --noEmit` 验证
4. **同步架构文档**：每阶段完成后同步 004/005 文档与 known-issues.md