---
title: 按 schema 名做覆盖率调研会严重低报缺口
date: 2026-05-08
tags: [audit, survey, methodology]
---

## 现象

为审计装饰器接入率做调研时，第一次让 Explore agent 按 PRD 列的 7 个 schema 名（`platform_iam` / `corp_approval` / `platform_form` / `mfg_inventory` / `corp_hr` / `corp_request` / 财务）查找模块，得出 **92.8%（91/97）** 覆盖率，结论"基本合规"。

按 `backend/src/modules/` 目录全量重扫后，真实数字是 **57.8%（271/469）**，差距 **35 个百分点**，缺口 ~184 个 endpoint。

## 根因

1. **PRD 抽象的"业务域名"≠ 代码目录名**：
   - `mfg_inventory` 实际就是 `modules/parts/`（已 100% 接入，但被误判为"无模块"）
   - `corp_hr` 实际拆在 `modules/performance/` + `modules/organization/`
   - `corp_request` 实际拆在 `modules/meeting-attendance/` + `modules/site-attendance/`
2. **agent 找不到同名目录就报告"无模块"**，跳过了实际承载该业务的模块
3. PRD 表面看起来"在范围里的都接入了"，但实际**有 5 个业务模块的 controller 0% 接入**（performance / meeting-attendance / site-attendance / knowledge-base / devtracker）

## 复用方案（覆盖率调研标准动作）

**禁止以 PRD 抽象名为入口。** 标准动作改为：

1. **先列代码事实**：`find backend/src -name "*.controller.ts"` 把所有 controller 全列出来
2. **以 controller 路径为单位统计**：每个文件 `@Post/@Put/@Patch/@Delete` 数 vs `@Auditable/@Financial/@Sensitive` 数
3. **再回头映射业务域**：把代码模块反向归到 PRD 业务域，缺失的业务模块单独列
4. **明确豁免范围**：审计模块自身（core/observability）的查询/导出/告警 endpoint 是审计基础设施，不审计自己——必须写在表里，不写就会被当成缺口

## 可复用脚本片段

```python
# 解析 controller 文件，按"装饰器累积 + 遇到方法定义触发"的状态机统计
# 关键：累积 @ 装饰器，碰到 async\s+\w+\(  或  方法签名时收口
# 重置触发条件：空行/注释 OK 不重置，遇到非 @ 非空非注释的代码行才重置
```

完整脚本在本次会话的 Bash 调用历史中（aggregate audit decorator coverage per module）。

## 教训

> **"PRD 怎么写"和"代码怎么组织"几乎从不一致**。任何"按 PRD 章节扫覆盖率"的请求，都要先做代码侧的全量盘点，再回头跟 PRD 对齐。

## 价值评估

- **重复出现概率**：高 — 任何"是否全接入 X"的合规调研（埋点、日志、metrics、追踪、权限）都会踩
- **适用范围**：跨项目通用（审计 / 监控 / 灰度 / feature flag 覆盖率全适用）
- **是否提炼 skill**：建议加到 `test-backend` 或新建 `coverage-survey` skill 时引用本文档作为反面教材