NextEdu/docs/architecture/audit/archive/data-access-audit-framework-v1.md

数据库访问层重构专项 - 审计框架 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 数组，每条问题：

{
  "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