# 审计模块接入缺口梳理（28 个 controller）

**日期**: 2026-05-08
**扫描方式**: `bash scripts/ops/check-controller-auditable.sh --mode warn --all`
**审计替代路径检查**: 已对每个文件 grep `IamAuditService` / `prisma.auditLog` / `prisma.iamAuditLog` —— **零文件**走替代路径，全部为真漏标。

---

## A. 必补 @Auditable（核心业务写操作）— 共 22 文件

### A1. performance（8）—— SOX 相关，**最高优先级**

| 文件 | 主要写操作 |
|---|---|
| `controllers/cycle.controller.ts` | POST 创建周期 / PUT 更新 / DELETE 删除（带 `CYCLE_CREATE/UPDATE/DELETE` 权限） |
| `controllers/result.controller.ts` | PATCH overall-comment / POST calculate / POST export / POST my/:id/confirm（员工确认绩效结果——合规关键） |
| `controllers/kpi.controller.ts` | KPI 创建/更新/自评 |
| `controllers/grade-config.controller.ts` | 等级配置变更 |
| `controllers/evaluation360.controller.ts` | 360 评估提交 |
| `controllers/evaluation360-template.controller.ts` | 360 模板写 |
| `controllers/calibration.controller.ts` | 绩效校准（管理员调整最终评级——高敏） |
| `controllers/strategic-objective.controller.ts` | 战略目标写 |

### A2. meeting-attendance（6）—— 业务管理

| 文件 | 主要写操作 |
|---|---|
| `controllers/users.controller.ts` | POST 用户 / PUT / DELETE / 重置密码 / 永久删除（含 `@Sensitive()` 候选） |
| `controllers/templates.controller.ts` | 会议模板 CRUD |
| `controllers/meetings.controller.ts` | 会议创建/更新/删除 |
| `controllers/outlook-sync.controller.ts` | Outlook 同步触发 |
| `controllers/pto.controller.ts` | PTO 假期申请/审批 |
| `controllers/series.controller.ts` | 系列会议管理 |
| `controllers/checkin.controller.ts` | 实际打卡（误判为 webhook，应补） |

### A3. devtracker（2）

| 文件 | 主要写操作 |
|---|---|
| `controllers/items.controller.ts` | POST 创建 / PUT 更新 / PATCH status / DELETE |
| `controllers/release-notes.controller.ts` | 发版说明写 |

### A4. organization 同步集成（2）—— system actor 触发，仍应记录

| 文件 | 备注 |
|---|---|
| `dingtalk/dingtalk.controller.ts` | DingTalk 组织同步触发；who 字段填 `system` 即可 |
| `adp/adp.controller.ts` | ADP 同步触发；同上 |

### A5. 其他（4）

| 文件 | 备注 |
|---|---|
| `engines/approval/process-admin.controller.ts` | POST sync / rollback 影响审批引擎全局，**强烈建议 + `@Sensitive()`** |
| `knowledge-base/knowledge-base.controller.ts` | 知识库内容写 |
| `robot-manager/robot-attachment.controller.ts` | 机器人附件管理 |
| `meeting-attendance/checkin.controller.ts` | 见 A2 |

---

## B. 可合理跳过（外部回调 / 内部服务）— 共 3 文件

| 文件 | 理由 | 建议 |
|---|---|---|
| `meeting-attendance/outlook-webhook.controller.ts` | 全部 `@Public()` Outlook 外部 webhook 通知/lifecycle | **跳过**：外部系统已记录；如需关联，在内部处理服务里补 |
| `engines/form/form-approval-callbacks.controller.ts` | `@UseGuards(InternalServiceGuard)` 内部 approval 引擎回调 | **跳过**：approval 引擎自身已审计上游事件 |
| `site-attendance/shared-checkin.controller.ts` | 多个 `@Public()` dispatch/validate-ticket 公共票据操作；但 partners CRUD（POST/PATCH/DELETE）属业务写 | **混合**：partners 操作必补 @Auditable，公共票务可跳 |

---

## C. 公共/匿名打卡（特殊场景）— 共 1 文件

| 文件 | 理由 | 建议 |
|---|---|---|
| `site-attendance/checkin.controller.ts` | 全部 `@Public()` 公共打卡，含 guest-checkin（匿名场景） | **建议补**：审计 who=anonymous 仍有合规价值（防伪打卡溯源），保留期可设 LOW |

---

## 推进建议

1. **批量补 A 类（22 文件）的可行做法**：
   - 一个模块一个 PR（performance / meeting-attendance / devtracker / organization-sync / 其他散件）共 5-6 个 PR
   - 每个 PR：在每个写操作方法上加 `@Auditable()`；删除/敏感操作再叠 `@Sensitive()`；不需要额外文档
   - 模板（performance 示例）：
     ```ts
     @Post()
     @RequirePermissions(PERFORMANCE_PERMISSIONS.CYCLE_CREATE)
     @Auditable()
     async create(@Body() dto: CreateCycleDto) { ... }

     @Delete(':id')
     @RequirePermissions(PERFORMANCE_PERMISSIONS.CYCLE_DELETE)
     @Auditable()
     @Sensitive()
     async remove(@Param('id') id: string) { ... }
     ```

2. **B 类建立显式跳过白名单**（避免每次扫描都被点名）：
   在 `scripts/ops/check-controller-auditable.sh` 顶部增加 `AUDIT_SKIP_PATHS` 数组，列入 outlook-webhook + form-approval-callbacks，并在每个文件头部加 `// audit-skip: webhook（外部系统已记录）` 注释作为 in-source 标记。

3. **C 类（site-attendance/checkin）做需求层决策**：
   - 选项 1：补 @Auditable，who=anonymous，保留期 LOW
   - 选项 2：保持现状，由 attendance 表自身充当审计源
   - 推荐选项 1（防伪打卡 + SOX 内控可追溯）

4. **升级 pre-commit 到 block 模式的前提**：
   - A 类全部消化（28 → 0）
   - B 类显式 skip 机制就位
   - 否则 block 模式会直接卡住任何修改这些 controller 的 PR

---

## 工作量估算

| 阶段 | 估算 |
|---|---|
| A1 performance 8 文件 | 0.5 天（含写少量手动验证：触发 cycle create 看 audit_log +1） |
| A2 meeting-attendance 6 文件 | 0.5 天 |
| A3-A5 + organization sync 共 8 文件 | 0.5 天 |
| B 类白名单机制 | 1 小时 |
| C 类决策 + 实施 | 0.5 小时 |
| **合计** | **~1.5 工作日** |

升级 pre-commit 到 block 模式的"零债"目标可在一周内达成。