# 审计系统 PRD
**版本**: v1.3.0
**状态**: ✅ 核心功能已实现｜⚠️ 真实接入覆盖率 **57.8%**（271/469 写操作，详见 §审计范围清单）
**SOX 合规**: ❌ **不达标** — `@Financial()` 全局 0 处使用 + 5 个业务模块装饰器 0 接入
**最后更新**: 2026-05-08（v1.3.0 全量重扫，更正 v1.2.0 的偏窄统计口径）
---

## 背景与目标

### 背景

FFOA 作为企业级办公自动化平台，处理大量敏感业务数据：

1. **人事数据** - 员工信息、组织架构、权限分配
2. **财务数据** - 加班工时、零件库存、费用审批
3. **审批流程** - 各类业务审批的完整流转过程
4. **表单数据** - 业务表单的创建、修改、提交

企业需要对这些操作进行完整的审计追踪，满足：

- **内部合规** - 谁在什么时间做了什么操作
- **外部审计** - 满足 SOX、GDPR 等法规要求
- **事故追溯** - 问题发生时能够追溯完整链路
- **法律存证** - 不可篡改的操作记录作为法律证据

### 目标

| 目标 | 描述 | 衡量指标 |
|------|------|----------|
| **全面记录** | 所有重要业务操作被记录 | 关键操作覆盖率 100% |
| **不可篡改** | 审计日志无法被修改或删除 | 完整性校验通过率 100% |
| **可追溯** | 任何操作可追溯到人和时间 | 5W1H 完整记录 |
| **高性能** | 不影响主业务性能 | 异步写入延迟 < 20ms |
| **SOX 合规** | 满足萨班斯-奥克斯利法案 | 财务记录保留 7 年 |
| **风险实时监控** 🚫本期不开发 | 异常操作自动发现与闭环处置 | 告警闭环率 100% |

---

## 边界声明

### 本模块职责

| 职责 | 说明 |
|------|------|
| 业务操作审计 | 记录创建、更新、删除等业务操作 |
| 权限变更审计 | 记录角色分配、权限变更 |
| 财务操作审计 | 记录所有财务相关操作（7 年保留） |
| 敏感操作审计 | 记录密码修改、登录失败等安全事件 |
| 数据变更捕获 | 记录数据库变更前后的完整快照 |
| 完整性保护 | 哈希链 + 数字签名确保不可篡改 |
| 审计查询 | 多维度查询审计历史 |
| 合规报表 | 自动生成合规审计报告 |
| 风险告警监控 🚫本期不开发 | 异常操作自动识别、分级、推送与闭环 |
| 告警闭环管理 🚫本期不开发 | 告警处理、意见填写、状态流转 |

### 非本模块职责（由日志系统负责）

| 职责 | 归属模块 |
|------|----------|
| HTTP 请求/响应日志 | [日志系统](../logging-system/PRD.md) |
| 应用运行日志 | [日志系统](../logging-system/PRD.md) |
| 错误调试日志 | [日志系统](../logging-system/PRD.md) |
| 性能监控日志 | [日志系统](../logging-system/PRD.md) |

---

## SOX 合规要求

### 萨班斯-奥克斯利法案核心要求

| 要求 | 说明 | 实现方式 |
|------|------|----------|
| **完整性** | 所有财务相关操作必须被记录 | 自动捕获 + `@Financial()` 标记 |
| **不可更改** | 审计日志不能被修改或删除 | 哈希链 + 数据库规则 |
| **可追溯** | 能够追溯到具体操作人和时间 | 5W1H 完整记录 |
| **访问控制** | 严格的日志访问权限管理 | 基于角色的权限控制 |
| **保留期限** | 财务记录至少保留 7 年 | 自动归档 + 冷热分离 |
| **定期审查** | 需要定期审计和报告 | 自动完整性检查 + 报表 |

---

## 功能需求

### F1: 自动审计记录

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F1.1 装饰器自动记录 | P0 | ✅ | `@Auditable()` 装饰器自动记录 |
| F1.2 敏感操作标记 | P0 | ✅ | `@Sensitive()` 标记敏感操作 |
| F1.3 财务操作标记 | P0 | ✅ | `@Financial()` 标记财务操作（7 年保留） |
| F1.4 HTTP 拦截器 | P0 | ✅ | 自动捕获 HTTP 请求上下文 |
| F1.5 手动记录 API | P1 | ✅ | `auditService.log()` 手动记录 |
| F1.6 设备信息采集 | P0 | ✅ | 自动采集设备型号、浏览器、操作系统 |

### F2: 5W1H 完整记录

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F2.1 Who（谁） | P0 | ✅ | 操作用户 ID、用户名、所属部门 |
| F2.2 What（什么） | P0 | ✅ | 操作类型、目标实体、业务单号 |
| F2.3 When（何时） | P0 | ✅ | 精确到毫秒的时间戳 |
| F2.4 Where（何地） | P0 | ✅ | IP 地址、地理位置、设备信息、浏览器信息 |
| F2.5 Why（为何） | P1 | ✅ | 业务原因/备注 |
| F2.6 How（如何） | P1 | ✅ | API/UI/CLI/系统触发 |
| F2.7 Region（区域） | P0 | ✅ | 部署区域（cn/us/eu 等） |
| F2.8 TenantId（租户） | P0 | ✅ | 租户 ID（多租户隔离） |

### F3: 数据变更捕获

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F3.1 变更前快照 | P0 | ✅ | 记录变更前的完整数据 |
| F3.2 变更后快照 | P0 | ✅ | 记录变更后的完整数据 |
| F3.3 变更字段列表 | P1 | ✅ | 识别具体变更的字段 |
| F3.4 敏感字段脱敏 | P0 | ✅ | 密码等敏感字段自动脱敏 |
| F3.5 变更对比渲染 | P0 | ✅ | 左右分栏对比，改动字段高亮着色 |

### F4: 完整性保护

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F4.1 哈希链 | P0 | ✅ | SHA-256 哈希链保护 |
| F4.2 数字签名 | P2 | ✅ | HMAC-SHA256 签名验证 |
| F4.3 定期校验 | P0 | ✅ | 每日/每周自动完整性检查 |
| F4.4 数据库规则 | P1 | ✅ | PostgreSQL 触发器禁止 UPDATE/DELETE |
| F4.5 单条日志校验 | P0 | ✅ | 详情页支持一键校验是否被篡改 |

### F5: 审计查询

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F5.1 按用户查询 | P0 | ✅ | 查询用户操作历史 |
| F5.2 按实体查询 | P0 | ✅ | 查询实体变更历史 |
| F5.3 按时间范围查询 | P0 | ✅ | 指定时间段查询 |
| F5.4 按模块查询 | P1 | ✅ | 按业务模块筛选 |
| F5.5 按操作类型查询 | P1 | ✅ | CRUD、审批、财务等 |
| F5.6 财务日志查询 | P0 | ✅ | 专门的财务操作查询 |
| F5.7 敏感日志查询 | P0 | ✅ | 专门的敏感操作查询 |
| F5.8 追踪链路查询 | P1 | ✅ | 通过 traceId 追踪 |
| F5.9 按业务单号查询 | P0 | ✅ | 支持审批/财务单号直接检索 |

### F6: 报表与导出

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F6.1 统计分析 | P1 | ✅ | 操作统计和趋势分析 |
| F6.2 日志导出 | P1 | ✅ | 导出为 CSV/Excel/JSON |
| F6.3 合规报表 | P2 | ✅ | SOX/GDPR 合规报表自动生成 |
| F6.4 异常报告 | P2 | ✅ | 异常操作自动检测和报告 |
| F6.5 告警统计报表 🚫本期不开发 | P1 | 📋 | 告警类型、级别、处理率统计 |

### F7: 告警与通知（新增·风险告警中心 · 🚫 本期不开发）
| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F7.1 完整性告警 | P1 | ✅ | 完整性校验失败告警 |
| F7.2 敏感操作告警 | P2 | ✅ | 高风险操作实时告警服务 |
| F7.3 异常模式告警 | P2 | ✅ | 异常操作模式自动识别 |
| F7.4 告警通知发送 | P2 | 📋 | 与通知系统集成（邮件/站内消息） |
| F7.5 异常自动盯盘 | P0 | ✅ | 异常登录、批量删数据、大额财务、权限篡改自动监控 |
| F7.6 告警分级 | P0 | ✅ | 高危/中级/普通三色区分展示 |
| F7.7 告警闭环 | P0 | ✅ | 必须处理、填写处理意见，状态可流转 |
| F7.8 告警查询 | P0 | ✅ | 按级别、时间、处理状态、模块筛选 |

### F8: 前端界面

| 功能点 | 优先级 | 状态 | 说明 |
|--------|--------|------|------|
| F8.1 审计日志查看器 | P1 | ✅ | 管理界面查看日志（logs/page.tsx, logs/[id]/page.tsx） |
| F8.2 实体历史追溯 | P1 | ✅ | 查看数据变更历史（search/page.tsx） |
| F8.3 统计仪表盘 | P2 | ✅ | 可视化统计分析（statistics/page.tsx） |
| F8.4 财务审计页面 | P1 | ✅ | 财务操作专用页面（financial/page.tsx） |
| F8.5 敏感操作页面 | P1 | ✅ | 敏感操作监控页面（sensitive/page.tsx） |
| F8.6 完整性验证页面 | P1 | ✅ | 哈希链验证界面（integrity/page.tsx） |
| F8.7 日志导出功能 | P2 | ✅ | 支持 CSV/Excel/JSON 导出 |
| F8.8 审计日志详情页（优化） | P0 | ✅ | 完整5W1H、改前改后对比、防篡改校验、业务单号跳转 |
| F8.9 风险告警中心（新增） 🚫本期不开发 | P0 | 📋 | 告警列表、详情、处理、统计（alarm-center/page.tsx） |

---

## 页面优化与新增

> 本节聚焦页面级需求（What & 验收点），不写实现步骤。UI 细节（布局、组件选型、交互态）以 `05-ui-interaction-spec.md` 为准。

### 页面 1：审计日志详情页（现有页面优化）

**路径**：`/audit/logs/[id]`（对应 F8.8）

**优化点**：

| 编号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| P1.1 | 5W1H 完整呈现 | P0 | 顶部信息卡展示：操作人（姓名+工号+部门）、时间（精确到毫秒）、设备（型号+OS+浏览器）、IP（含地理位置）、操作原因、来源（API/UI/CLI/系统） |
| P1.2 | 改前/改后左右对比 | P0 | 双栏 diff 视图，新增字段标绿、删除字段标红、修改字段标黄；只显示发生变化的字段，未变字段折叠 |
| P1.3 | 防篡改校验入口 | P0 | 详情页提供"校验完整性"按钮，调用 F4.5 单条校验接口，返回结果以绿色✓"未篡改" / 红色✗"已被篡改"展示，点击查看哈希链上下文 |
| P1.4 | 业务单号跳转 | P0 | `businessKey` 字段渲染为可点击链接，根据单号前缀路由到原审批单 / 财务单 / 表单页 |

**验收**：
- [ ] 任一审计记录详情页能看全 Who/What/When/Where/Why/How（Why 为可选字段，按 F2.5 P1 处理，缺失时显示"—"）
- [ ] 字段级 diff 与后端 `oldValue` / `newValue` 完全一致，颜色编码符合规范
- [ ] 防篡改校验对未被篡改的日志返回成功；人为修改 DB 后能检出失败
- [ ] 业务单号跳转目标页 URL 正确，跨模块跳转无 404

---

### 页面 2：风险告警中心（新增 · 🚫 本期不开发）

> ⚠️ **范围说明**：风险告警中心（含异常盯盘、告警分级、闭环处理、多通道推送、规则配置等）**暂不纳入本期开发范围**，文档保留作为后续立项参考。
>
> 受影响的条目同步标记为「规划中」、不进入本期排期：
> - 目标 `风险实时监控`
> - 边界声明 `风险告警监控` / `告警闭环管理`
> - F6.5 告警统计报表
> - F7.5–F7.8（异常自动盯盘、告警分级、告警闭环、告警查询）
> - F8.9 风险告警中心入口
> - 下方 P2.1–P2.7 全部功能项

**路径**：`/audit/alarm-center`（对应 F8.9）

**功能定位**：将散落在审计日志中的异常行为集中呈现，支持告警分级、闭环处置、消息推送。

**核心功能**：

| 编号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| P2.1 | 异常自动盯盘 | P0 | 系统内置规则引擎，自动识别：**异常登录**（同账号短时间多 IP / 异地登录）、**批量删除**（单次操作 ≥ N 条数据）、**大额财务**（金额超阈值）、**权限篡改**（角色/权限点变更）|
| P2.2 | 告警分级展示 | P0 | 三级颜色区分：🔴 **高危**（异地登录、批量删数据、大额付款、超管权限变更）、🟡 **中级**（敏感操作高频、非工作时间操作）、🔵 **普通**（一般异常模式）|
| P2.3 | 告警闭环处理 | P0 | 每条告警必须由责任人**确认 + 填写处理意见**才能关闭；状态流转：`待处理 → 处理中 → 已闭环 / 已忽略（需备注原因）` |
| P2.4 | 多通道消息推送 | P0 | 告警生成时按级别推送到：**站内信**、**钉钉**、**邮件**；高危告警必推全通道，中级可配置，普通仅站内消息 |
| P2.5 | 规则配置 | P1 | 管理员可配置告警规则阈值（如批量操作行数、大额金额、登录间隔），无需改代码 |
| P2.6 | 告警统计与筛选 | P0 | 按级别 / 时间 / 处理状态 / 模块 / 责任人 筛选；首页展示"待处理告警数"红点 |
| P2.7 | 告警与原始日志关联 | P0 | 每条告警可一键跳转到触发它的原始审计日志详情页 |

**告警闭环流程**：

```
触发规则 → 生成告警 → 分级推送（站内 + 企微/钉钉/邮件）
       ↓
   责任人接收 → 进入处理中 → 调查（关联审计日志）
       ↓
   填写处理意见 → 闭环（已处理 / 已忽略）→ 计入闭环率
```

**验收**：
- [ ] 4 类异常行为（异常登录、批量删数据、大额财务、权限篡改）均能自动触发告警
- [ ] 高危告警 1 分钟内推送到企微/钉钉/邮件三通道
- [ ] 告警未填写处理意见时无法关闭
- [ ] 告警闭环率统计准确，与日志数据一致
- [ ] 规则阈值修改后下一次触发即生效（无需重启）
- [ ] 告警 → 原始日志跳转链路无断点

---

## 审计范围清单

> **硬性要求**：以下业务域和操作类型**必须**接入审计系统，新模块上线前需对照本清单进行 Code Review。
>
> **接入现状**（截至 2026-05-08，全量 `backend/src` Controller 写操作扫描）：
> - 总 controller：**96 个**
> - 总写操作 endpoint（POST/PUT/PATCH/DELETE）：**469 个**
> - 已接入审计装饰器（@Auditable / @Financial / @Sensitive 任一）：**271 个**
> - **真实覆盖率：57.8%**
> - **`@Financial()` 装饰器使用：0 处（全局违规）**

### 按模块覆盖率（v1.3.0 实测）

| 业务模块 | 路径 | Files | Writes | 已审计 | 覆盖率 | 评估 |
|---------|------|------:|------:|------:|------:|------|
| **organization**（IAM/权限/同步） | modules/organization | 21 | 101 | 70 | 69% | ⚠️ 31 个缺口（需细分子目录） |
| **engines**（审批/表单/process-admin） | modules/engines | 13 | 85 | 69 | 81% | ⚠️ 16 个缺口（管理端） |
| **performance**（绩效/校准/KPI/360） | modules/performance | 9 | 53 | 0 | **0%** | ❌ 整模块未接入（含薪资 grade）|
| **meeting-attendance**（会议考勤/PTO） | modules/meeting-attendance | 11 | 45 | 0 | **0%** | ❌ 整模块未接入 |
| **parts**（零件/库存/仓位）= mfg_inventory | modules/parts | 10 | 45 | 45 | 100% | ✅ |
| **robot-manager**（机器人台账） | modules/robot-manager | 8 | 44 | 32 | 73% | ⚠️ 12 个缺口 |
| **tickets**（工单） | modules/tickets | 2 | 20 | 20 | 100% | ✅ |
| **ai-assistant** | modules/ai-assistant | 7 | 15 | 15 | 100% | ✅ |
| **site-attendance**（现场考勤/工资） | modules/site-attendance | 3 | 11 | 0 | **0%** | ❌ 整模块未接入（涉工资）|
| **knowledge-base** | modules/knowledge-base | 1 | 10 | 0 | **0%** | ❌ 整模块未接入 |
| **core/messaging** | core/messaging | 1 | 7 | 7 | 100% | ✅ |
| **flow-diagram** | modules/flow-diagram | 1 | 6 | 5 | 83% | ⚠️ 1 个缺口 |
| **core/compute** | core/compute | 1 | 6 | 6 | 100% | ✅ |
| **devtracker** | modules/devtracker | 2 | 5 | 0 | **0%** | ❌ 整模块未接入 |
| **feedback** | modules/feedback | 1 | 1 | 1 | 100% | ✅ |
| **ops-center/m365-dormant** | modules/ops-center | 1 | 1 | 1 | 100% | ✅ |
| **core/observability/audit** | core/observability | 2 | 14 | 0 | — | ⓘ **豁免**（审计模块自身的查询/导出/告警，不审计自己） |
| **合计** | — | **96** | **469** | **271** | **57.8%** | — |

> **状态图例**：✅ 100% / ⚠️ 部分接入 / ❌ 0% 接入 / 📋 模块未实现 / ⓘ 豁免

### 业务域 ↔ 实际模块映射（修正 v1.2 误判）

| 业务域（PRD 抽象） | 实际代码模块 | 实现状态 |
|---|---|---|
| 身份与权限 | modules/organization/{users,roles,positions,departments,organizations,iam-governance,...} | ✅ 已实现 |
| 审批流程 | modules/engines/approval, modules/engines/process-admin | ✅ 已实现 |
| 表单管理 | modules/engines/forms, modules/engines/form-management | ✅ 已实现 |
| **库存管理 = `mfg_inventory`** | modules/parts（即此模块）| ✅ 已实现，**100% 覆盖** |
| **人事管理 = `corp_hr`** | modules/performance + modules/organization 部分 | ⚠️ 已实现，**绩效模块 0% 接入** |
| **考勤请假 = `corp_request`** | modules/meeting-attendance（PTO/会议）+ modules/site-attendance（现场+工资）| ⚠️ 已实现，**两个模块均 0% 接入** |
| 财务相关 | 散落在 site-attendance（工资）、performance（grade）、未来报销 | ❌ `@Financial()` 全局未使用 |
| 系统配置 / 外部同步 | modules/organization/{dingtalk,sync,adp,emergency-bypass} | ⚠️ 部分接入，需逐项核对 |

### 必须审计的操作类型

| 操作类别 | 操作类型 | 说明 |
|----------|----------|------|
| **写操作** | `CREATE` / `UPDATE` / `DELETE` | 所有业务数据变更 |
| **批量操作** | `BULK_UPDATE` / `BULK_DELETE` | 批量操作需逐条记录 |
| **权限操作** | `ROLE_CHANGE` / `PERMISSION_CHANGE` | 包括角色分配、权限点变更 |
| **财务操作** | `PAYMENT` / `REFUND` / `INVOICE_GENERATE` / `FINANCIAL_CLOSE` | 必须标记 `@Financial()` |
| **安全事件** | `LOGIN_FAILED` / `PASSWORD_CHANGE` | 必须标记 `@Sensitive()` |
| **系统配置** | `CONFIG_CHANGE` / `BACKUP` / `RESTORE` | 影响系统行为的变更 |
| **管理员操作** | 代审批、强制终止、数据修复 | 需详细记录操作原因 |
| **高危告警触发** | 异常登录、批量删除、大额操作 | 自动触发告警，记录原因（按 F2.5 P1 可选） |

### 未接入装饰器明细（截至 2026-05-08）

> 以下 endpoint 已实现但未挂装饰器，**须在下一次发版前补齐**。
> **总缺口：198 个**，按风险等级分批处理。

#### P0 · 整模块 0% 接入（共 124 个 endpoint，必须最优先处理）

| 模块 | 缺口数 | 关键风险 | 推荐装饰器组合 |
|---|---:|---|---|
| **performance**（9 controller / 53 writes） | 53 | 含 grade-config（薪资等级）、calibration（绩效校准）、result（绩效结果）—— 直接关联薪酬 | `@Auditable()` 全部，grade 相关 + `@Financial()`，calibration 管理端 + `@Sensitive()` |
| **meeting-attendance**（11 controller / 45 writes） | 45 | PTO 假期变更、会议签到、Outlook 同步、用户档案 | `@Auditable()` 全部，PTO/Outlook-sync + `@Sensitive()` |
| **site-attendance**（3 controller / 11 writes） | 11 | 打卡数据驱动工资计算 | `@Auditable() @Financial()` 全部 |
| **knowledge-base**（1 controller / 10 writes） | 10 | 知识库内容增删改 | `@Auditable()` |
| **devtracker**（2 controller / 5 writes） | 5 | 内部研发追踪，可豁免或 LOW | 评估后决定，倾向 `@Auditable()` LOW |

#### P1 · 部分接入模块的剩余缺口（共 ~64 个 endpoint）

| 模块 | 缺口数 | 备注 |
|---|---:|---|
| **organization**（21 controller / 31 缺） | ~31 | 集中在 dingtalk/sync/adp/ai-tools/emergency-bypass 等子模块，须逐 controller 核对 |
| **engines / approval + process-admin** | 16 | 详见下方原 v1.2 列出的具体行号 |
| **robot-manager** | 12 | 8 个 controller 中部分写操作未挂；含 attachment 上传/admin 配置 |
| **flow-diagram** | 1 | 单个写操作缺装饰器 |

**organization 子模块缺口须逐项核对**（v1.3.0 暂未细列到行号，下次扫描或合并到补丁 PR 时补出）：

- `dingtalk`、`sync`、`adp` —— 外部同步类，建议 `@Auditable() @Sensitive()`
- `emergency-bypass` —— 紧急旁路，**强制** `@Auditable() @Sensitive()`，且必填操作原因
- `ai-tools` —— AI 工具配置变更，建议 `@Auditable()`
- `iam-audit`（IAM 治理审计）、`role-data-scopes`、`data-scopes`、`field-permissions` —— 数据权限范围变更，建议 `@Auditable()`

**engines 域已知缺口（沿用 v1.2 明细）**：

**approval.controller.ts —— 管理员操作（7 个，须 `@Auditable() @Sensitive()`）**

| 行号 | HTTP | Path | 方法 |
|------|------|------|------|
| 135 | POST | `/approval/admin/instances/export` | exportAdminInstances |
| 171 | PUT | `/approval/admin/settings` | updateAdminSettings |
| 182 | POST | `/approval/admin/:instanceId/terminate` | — |
| 202 | POST | `/approval/admin/:instanceId/resume-with-approvers` | — |
| 224 | POST | `/approval/admin/:instanceId/approve` | — |
| 244 | POST | `/approval/admin/:instanceId/reject` | — |
| 264 | POST | `/approval/admin/:instanceId/reassign` | — |

**approval.controller.ts —— 流程定义管理（3 个，须 `@Auditable()`）**

| 行号 | HTTP | Path | 方法 |
|------|------|------|------|
| 294 | POST | `/approval/definitions` | createDefinition |
| 316 | PUT | `/approval/definitions/:key` | updateDefinition |
| 329 | DELETE | `/approval/definitions/:key` | deleteDefinition |

**process-admin.controller.ts —— 流程同步（3 个，须 `@Auditable() @Sensitive()`）**

| 行号 | HTTP | Path | 方法 |
|------|------|------|------|
| 20 | POST | `/approval/process-admin/sync` | syncAll |
| 33 | POST | `/approval/process-admin/sync/:key` | syncOne |
| 46 | POST | `/approval/process-admin/rollback/:key/:version` | rollback |

#### 表单管理域（2 个，须 `@Auditable()`）

| 文件 | 行号 | HTTP | Path |
|------|------|------|------|
| forms.controller.ts | 248 | POST | `/form/:formIdentifier/duplicate` |
| form-management.controller.ts | 220 | POST | `/form-management/definitions/:id/preview-process` |

#### `@Financial()` 全局缺失（需排查所有涉及金额的模块）

排查范围：所有写操作中含 `amount` / `cost` / `salary` / `payment` / `reimbursement` / `invoice` 字段或参数的 endpoint。已知候选模块：
- 加班申请 / 请假 / 出差报销（corp_request 相关）
- 站点出勤工资（site-attendance）
- 任何带"金额"语义的导入/同步任务

**操作**：先列清单 + 评估每个 endpoint 是否需要 7 年保留，再统一补 `@Financial()`，**不得擅自批量加**——加错一律走法务回退。

---

### 审计接入检查清单（DoD · 适用于所有新模块/新接口）

> **强制门槛**：以下任一项不通过，禁止合入 develop 分支。新模块上线前由 reviewer 逐项确认。

**装饰器接入**

- [ ] 所有 Controller 写操作（POST/PUT/PATCH/DELETE）已添加 `@Auditable()` 装饰器
- [ ] 涉及金额变动的接口已添加 `@Financial()` 装饰器（保留期 7 年）
- [ ] 涉及密码、Token、登录失败、权限变更等接口已添加 `@Sensitive()` 装饰器
- [ ] 管理员特权操作（代审批、强制终止、批量操作）同时挂 `@Auditable() @Sensitive()`

**记录质量**

- [ ] 批量操作记录了每条数据的前后快照（不能只记一条聚合记录）
- [ ] 管理员特权操作在请求体或日志 metadata 中记录了"操作原因"
- [ ] 涉及外部系统同步（钉钉 / Entra ID / LDAP）的操作记录了同步结果与冲突信息
- [ ] 敏感字段（密码、Token、身份证、银行卡、CVV）已通过 `oldValue/newValue` 脱敏（参见 §数据隐私与脱敏）

**契约对齐**

- [ ] 操作类型枚举命中 §"必须审计的操作类型"列表（CREATE/UPDATE/DELETE/BULK_*/ROLE_CHANGE/PAYMENT/...）
- [ ] `region` + `tenantId` 字段非空（多区域多租户隔离）
- [ ] 模块的 `09-test-scenarios.md` 中包含至少 1 条审计验证场景

**未实现业务域的特殊要求**

新建 `mfg_inventory` / `corp_hr` / `corp_request` 等模块时，第一个 PR **必须**同时包含：
1. 业务 controller + service 实现
2. 上述全部装饰器
3. 集成测试验证 audit_log 表 +1（参考 [interceptor.integration.test.ts](../../../testing/backend/integration/audit/interceptor.integration.test.ts)）

缺任意一项视为不完整，reviewer 必须打回。

---

## 审计级别定义

| 级别 | 说明 | 典型场景 | 对应策略 |
|------|------|----------|----------|
| **HIGH** | 高风险，直接影响财务报表、安全或权限 | 财务操作、权限变更、系统配置、盘点 | 保留 7 年；必须记录 old/new；可配置告警 |
| **MEDIUM** | 中风险，影响业务数据正确性 | 一般业务数据的增删改、审批结果 | 保留 5 年；记录前后快照 |
| **LOW** | 低风险，主要用于追踪行为 | 查询、非关键字段更新、草稿保存 | 保留 3 年；可以只记录概要 |

### 各级别详细说明

#### HIGH（高风险）

- **触发条件**：财务金额变动、权限/角色变更、系统配置修改、盘点差异
- **记录内容**：完整的 `oldValue` 和 `newValue`，详细变更字段
- **保留期限**：7 年（SOX 合规要求）
- **告警配置**：可配置实时告警（如大额付款、批量删除）
- **审计人员**：需要定期抽查

#### MEDIUM（中风险）

- **触发条件**：常规业务数据的创建/修改/删除、审批流转
- **记录内容**：完整的前后快照
- **保留期限**：5 年
- **告警配置**：按需配置
- **审计人员**：异常时追溯

#### LOW（低风险）

- **触发条件**：数据查询、非关键字段更新、草稿/临时数据
- **记录内容**：操作概要（可省略详细快照）
- **保留期限**：3 年
- **告警配置**：通常不需要
- **审计人员**：问题排查时使用

---

## 各模块审计要求

> 下列为各模块**应有**的审计行为；当前实际接入状态见 §审计范围清单。模块未实现时，本节作为实现 DoD。

### 组织架构模块（platform_iam）✅ 已实现 100%

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 用户创建/修改/删除 | HIGH | 完整记录变更前后数据 |
| 角色分配/移除 | HIGH | 谁给谁分配/移除了什么角色 |
| 权限变更 | HIGH | 角色权限点变化 |
| 部门创建/修改/删除 | MEDIUM | 组织架构调整 |
| 外部同步（Entra ID/LDAP） | MEDIUM | 同步时间、结果、冲突 |

### 审批引擎模块（corp_approval）⚠️ 67%，管理端 + 流程定义 + process-admin 缺装饰器

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 提交审批 | MEDIUM | 发起人、表单数据 |
| 审批/驳回/退回 | MEDIUM | 审批人、意见、结果 |
| 代审批 | HIGH | 管理员代审批需详细记录原因 |
| 强制终止 | HIGH | 管理员强制操作需详细记录原因 |
| 转交 | MEDIUM | 原审批人、新审批人 |

### 表单管理模块（platform_form）⚠️ 92%，复制/预览流程缺装饰器

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 表单发布 | MEDIUM | 版本号、发布人 |
| 表单停用 | MEDIUM | 停用原因 |
| 版本变更 | LOW | 变更内容 |

### 库存管理模块（mfg_inventory）📋 待实现

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 入库 | MEDIUM | 零件、数量、操作人 |
| 出库 | MEDIUM | 零件、数量、领用人 |
| 盘点 | HIGH | 盘点结果、差异，涉及资产核实 |
| 调拨 | MEDIUM | 源/目标位置、数量 |

### 人事管理模块（corp_hr）📋 待实现

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 入职 | HIGH | 新员工档案、入职日期、岗位 |
| 离职 | HIGH | 离职日期、原因、交接结果 |
| 调岗 | HIGH | 原岗位、新岗位、生效日期 |
| 调薪 | HIGH + `@Financial()` | 原薪资、新薪资、生效日期、批准人（7 年保留） |
| 转正 | HIGH | 试用期评估、转正日期 |

### 考勤请假模块（corp_request）⚠️ 已部分实现，须逐项核对装饰器

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 加班申请 / 审批 | MEDIUM | 申请人、时长、加班费类型 |
| 请假申请 / 审批 | MEDIUM | 申请人、起止时间、假期类型 |
| 出差申请 / 审批 | MEDIUM | 申请人、目的地、起止时间 |
| 报销关联（涉及金额） | HIGH + `@Financial()` | 报销金额、票据、审批人（7 年保留） |

### 财务相关模块 ⚠️ `@Financial()` 全局缺失

| 操作 | 审计级别 | 说明 |
|------|----------|------|
| 报销提交/审批 | HIGH + `@Financial()` | 金额、费用类型 |
| 付款执行 | HIGH + `@Financial()` | 付款金额、收款方 |
| 发票开具 | HIGH + `@Financial()` | 发票号、金额 |
| 财务关账 | HIGH + `@Financial()` | 关账期间、操作人 |
| 调账 | HIGH + `@Financial()` | 调整前后金额、原因 |

---

## 数据隐私与脱敏

> **GDPR / 隐私合规**：审计日志在记录业务操作的同时，必须保护个人隐私数据。

### 禁止存储原文的数据

以下数据在审计日志中**禁止存储原文**，必须脱敏或不记录：

| 数据类型 | 处理方式 | 示例 |
|----------|----------|------|
| 密码、Password Hash | 不记录 | `password: "***REDACTED***"` |
| Token / Refresh Token | 不记录 | `token: "***REDACTED***"` |
| 身份证号 / SSN | 掩码 | `idCard: "310***********1234"` |
| 完整银行卡号 | 掩码 | `bankCard: "6222************1234"` |
| CVV / 安全码 | 不记录 | 不记录 |
| API Key / Secret | 不记录 | `apiKey: "***REDACTED***"` |

### 个人联系方式处理

| 数据类型 | 处理方式 | 示例 |
|----------|----------|------|
| 手机号 | 掩码 | `phone: "132****5678"` |
| 邮箱 | 掩码 | `email: "z***@example.com"` |
| 家庭地址 | 仅记录变更事实 | `address: "[已变更]"` |

### 审计日志数据原则

1. **最小必要原则**：仅记录业务关键字段和标识 ID，不复制大体量业务明细
2. **脱敏优先**：敏感数据在写入时即完成脱敏，API 不返回原文
3. **不做第二份业务库**：审计日志用于追溯和合规，不应成为业务数据的备份存储

---

## 多区域与多租户隔离

> **核心原则**：审计日志必须支持按区域和租户的完全隔离，满足数据主权和合规要求。

### 必需字段

| 字段 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `region` | String | 部署区域，不可为空 | `cn` / `us` / `eu` / `ap` |
| `tenantId` | String | 租户 ID，不可为空 | `tenant-001` |

### 数据隔离策略

1. **存储隔离**：不同 region 的审计日志可部署在不同的数据库实例/集群
2. **查询隔离**：所有查询 API 必须带上 `region` 和 `tenantId` 过滤条件
3. **权限隔离**：租户管理员只能查看本租户的审计日志
4. **归档隔离**：按 region + tenantId 分别归档，满足不同地区的数据保留法规

### 数据保留策略（按区域）

| 区域 | 适用法规 | 财务日志保留期 | 一般日志保留期 |
|------|----------|---------------|---------------|
| `cn` | 中国《会计档案管理办法》 | 10 年 | 5 年 |
| `us` | SOX (萨班斯-奥克斯利) | 7 年 | 3 年 |
| `eu` | GDPR + 各成员国法规 | 7 年 | 3 年 |
| `ap` | 因国家而异 | 7 年（默认） | 3 年（默认） |

---

## 审计日志不可修改策略

> **核心原则**：审计日志一旦写入，任何人（包括 DBA 和系统管理员）都不能修改或删除。

### 数据库层保护

1. **禁止 UPDATE/DELETE**：审计日志表通过数据库 Trigger 或 Rule 禁止 `UPDATE` 和 `DELETE` 操作
2. **应用层限制**：Service 层不提供任何修改/删除审计日志的 API
3. **权限隔离**：生产环境 DBA 账号对审计表仅有 `SELECT` 和 `INSERT` 权限
4. **租户隔离**：不同租户的审计日志物理或逻辑隔离，防止跨租户访问

### 数据清理与归档

1. **分区迁移**：历史数据通过表分区方式迁移到归档表/冷存储，不修改原始记录
2. **只读备份**：归档数据以只读方式存储，保留完整哈希链
3. **合规删除**：超过保留期限的数据，通过分区 DROP 方式删除整个分区，不做逐行删除

### 异常处理

- 如果因极端情况（如数据修复）需要修改审计日志，必须：
  1. 提交书面申请并获得审计委员会/法务批准
  2. 在新的审计记录中记录"对原记录的修正"及修正原因
  3. 原记录保持不变，新增修正记录

---

## 非功能需求

### 数据保留

| 数据类型 | 合规级别 | 保留期限 |
|----------|----------|----------|
| 财务操作日志（`@Financial()`） | HIGH | 7 年 |
| 高风险操作日志（权限变更、系统配置） | HIGH | 7 年 |
| 一般操作日志（业务数据增删改） | MEDIUM | 5 年 |
| 低风险操作日志（查询、草稿） | LOW | 3 年 |
| 完整性校验日志 | - | 1 年 |

### 查询时间跨度限制

| 接口 | 时间跨度限制 | 说明 |
|------|-------------|------|
| 通用查询 `/audit/logs` | ≤ 90 天 | 防止大范围全量扫描 |
| 财务查询 `/audit/financial` | ≤ 1 年 | startDate/endDate 必填 |
| 完整性验证 `/audit/verify-integrity` | 建议 ≤ 30 天 | 同步校验，超过可能超时 |
| 导出 `/audit/export` | 无硬限制 | 超过 10 万条返回错误 |

### 性能要求

| 指标 | 要求 |
|------|------|
| 审计日志写入 | < 20ms（异步） |
| 查询响应 | < 200ms |
| 完整性检查 | < 5秒/万条 |

### 可用性要求

| 指标 | 要求 |
|------|------|
| 日志写入可用性 | 99.9% |
| 日志查询可用性 | 99% |
| 数据丢失率 | 0% |

---

## 验收标准

### 功能验收

- [x] 重要操作自动记录审计日志
- [x] 5W1H 信息完整记录
- [x] 变更前后数据完整保存
- [x] 敏感字段自动脱敏
- [x] 哈希链完整性保护
- [x] 多维度查询支持
- [x] 前端审计日志查看器

### 合规验收

- [x] 财务操作 7 年保留
- [x] 审计日志不可删除（应用层 + 数据库层）
- [x] 审计日志不可修改（数据库层 Trigger）
- [x] HMAC 数字签名验证
- [x] 定期完整性检查
- [x] SOX 合规报表生成
- [x] GDPR 数据访问报告

### 性能验收

- [x] 异步写入不阻塞业务
- [x] 写入延迟 < 20ms
- [x] 查询响应 < 200ms

### 覆盖率验收

- [ ] 对典型端到端业务流程（如：入职 → 调岗/调薪 → 报销/付款 → 出入库 → 关账）进行实际走单，验证每个关键节点均生成审计记录
- [ ] 关键操作覆盖率达到 100%（当前 **57.8%**，缺口见 §审计范围清单/未接入装饰器明细）
- [ ] `@Financial()` 装饰器在所有金额变动接口落地（当前 **0 处**，须全量排查 site-attendance / performance / 未来报销模块）
- [ ] 新模块上线前完成审计接入检查清单（DoD）
- [ ] CI 流水线集成"装饰器接入扫描"脚本（建议）：扫描所有 controller 写操作，未挂 `@Auditable()` 时 Pull Request 失败

---

## 与日志系统的关系

| 维度 | 审计系统 | 日志系统 |
|------|----------|----------|
| **定位** | 业务合规 | 技术运维 |
| **目标** | 操作追溯、合规存证 | 调试、监控、问题排查 |
| **内容** | 业务操作、数据变更 | HTTP 请求/响应、错误 |
| **保留期** | 3-7 年 | 14-30 天 |
| **可修改** | 不可删除、不可修改 | 可清理 |
| **合规要求** | SOX 合规 | 无特殊要求 |
| **完整性保护** | 哈希链 | 无 |

---

## 相关文档

- [ARCHITECTURE.md](ARCHITECTURE.md) - 架构设计文档
- [API.md](API.md) - API 接口文档
- [TODO.md](TODO.md) - 开发待办
- [日志系统 PRD](../logging-system/PRD.md) - 技术运维日志

---

**文档维护**: FFOA 开发团队  
**更新频率**: 功能变更时更新