# 审计系统（Audit System）

> **负责人**: FFOA 开发团队  
> **版本**: v1.1.0  
> **状态**: 🟢 生产就绪  
> **SOX 合规**: ✅ 满足  
> **最后更新**: 2026-05-07

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2026-05-07 |
| [架构设计](./03-architecture.md) | ✅ | 2025-12-12 |
| [API 文档](./07-api.md) | ✅ | 2025-12-19 |
| [配置指南](./10-configuration.md) | ✅ | 2025-12-19 |
| [开发路线图](./10-roadmap.md) | ✅ | 2025-12-07 |
| [集成示例](./11-integration-guide.md) | ✅ | 2025-12-18 |
| [故障排查](./12-troubleshooting.md) | ✅ | 2025-12-18 |
| [使用指南](./11-user-guide.md) | ✅ | 2026-05-11 |
| [变更日志](./99-changelog.md) | ✅ | 2025-12-19 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新

> **v1.1.0 (2026-05-07)**：PRD「各模块审计要求」扩写至覆盖 `docs/modules/` 下全部模块，新增「无需接入」表与「跨模块共用财务操作」表。详见 [01-prd.md](./01-prd.md#各模块审计要求)。

---

## 📌 概述

审计系统是 FFOA 平台的合规基础设施模块，负责记录所有重要业务操作，确保操作可追溯、数据不可篡改，满足 SOX/GDPR 等法规的合规要求。

### 核心特性

1. **自动审计** - 使用 `@Auditable()` 装饰器自动记录所有业务操作
2. **5W1H 完整记录** - 谁（Who）、什么（What）、何时（When）、何地（Where）、为何（Why）、如何（How）
3. **双重完整性保护** - SHA-256 哈希链 + HMAC 数字签名
4. **防篡改** - 应用层不暴露 update/delete API + 哈希链 tamper-evident（任何修改重算哈希后会与存储值不匹配，单条/批量校验可检出）。DB 层触发器属规划项，待补
5. **敏感操作标记** - `@Sensitive()` 标记高风险操作
6. **财务操作合规** - `@Financial()` 标记，7年保留期
7. **SOX/GDPR 合规报表** - 自动生成合规审计报表
8. **实时告警系统** - 高风险操作自动检测和通知
9. **多维度查询** - 按用户、实体、模块、时间查询
10. **多区域隔离** - 支持多租户、多区域数据隔离

### 业务价值

- **合规保障**: 满足 SOX、GDPR、ISO 27001 等法规要求
- **操作可追溯**: 所有业务变更完整记录，支持审计追溯
- **数据防篡改**: 哈希链和数字签名确保日志不可篡改
- **风险预警**: 实时检测异常操作，自动告警
- **集成覆盖率**: 44个模块、234个操作、181个敏感操作

---

## 🏗️ 技术信息

### 代码位置

- **前端**: `frontend/src/app/audit/` - 审计日志查看器
- **后端**: `backend/src/audit/`
- **数据库**: `platform_audit` Schema（4张表）

### API 端点

- **Base URL**: `/api/v1/audit`
- **主要接口组**: 
  - 查询接口（12个）- 日志查询、统计、完整性验证
  - 合规报表接口（4个）- SOX/GDPR 报表生成
  - 告警接口（4个）- 批量检查、异常检测
- **总计**: 20+ 个接口

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS
- **后端**: NestJS + Prisma + PostgreSQL
- **安全**: SHA-256哈希链 + HMAC签名 + 触发器
- **其他**: 定时任务（完整性检查）、装饰器自动记录

---

## 🔗 相关模块

- [日志系统](../logging-system/README.md) - 技术运维日志
- [通知系统](../notification-engine/README.md) - 告警通知集成
- [权限系统](../organization/README.md) - RBAC 权限控制

---

## 🚀 快速开始

### 1. 装饰器自动记录（推荐）

在 Controller 方法上添加 `@Auditable()` 装饰器：

```typescript
import { Controller, Post, Body, Delete, Param } from '@nestjs/common';
import { Auditable, Sensitive } from '@/audit/decorators/auditable.decorator';

@Controller('users')
export class UsersController {
  
  @Post()
  @Auditable()  // ✅ 自动记录创建操作
  async create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
  
  @Post(':id/password')
  @Auditable()
  @Sensitive()  // ⚠️ 标记为敏感操作
  async changePassword(@Param('id') id: string, @Body() dto: ChangePasswordDto) {
    return this.usersService.changePassword(id, dto);
  }
  
  @Delete(':id')
  @Auditable()
  @Sensitive()  // ⚠️ 删除操作都是敏感操作
  async remove(@Param('id') id: string) {
    return this.usersService.remove(id);
  }
}
```

### 2. 装饰器说明

| 装饰器 | 用途 | 保留期限 |
|--------|------|---------|
| `@Auditable()` | 标记需要审计的操作 | 1-3 年 |
| `@Sensitive()` | 标记敏感操作（密码、权限、删除） | 3-5 年 |
| `@Financial()` | 标记财务操作（支付、退款） | 7 年 |

### 3. 查看审计日志

```bash
# 查询所有审计日志
GET /api/v1/audit/logs

# 查询用户操作历史
GET /api/v1/audit/user/:userId

# 查询实体变更历史
GET /api/v1/audit/entity/:type/:id

# 生成 SOX 合规报表
POST /api/v1/audit/reports/sox
```

详见 [API 文档](./07-api.md) 和 [集成示例](./11-integration-guide.md)

---

## 📊 数据模型

### 核心表结构

```
platform_audit schema:
├── audit_log                    # 主审计日志表（28 字段）
├── database_change_log          # 数据库变更表
├── sensitive_operation_log      # 敏感操作表
└── integrity_check_log          # 完整性检查表
```

### 审计日志字段分类

- **5W1H 信息** (6字段): who, what, when, where, why, how
- **操作详情** (4字段): module, action, entityType, entityId
- **变更内容** (3字段): oldValue, newValue, changes
- **上下文信息** (4字段): userId, region, tenantId, traceId
- **环境信息** (4字段): ipAddress, userAgent, requestId, duration
- **SOX 合规** (4字段): isFinancial, isSensitive, retentionYears, riskLevel
- **完整性保护** (3字段): previousHash, currentHash, chainVerified

详见 [架构设计](./03-architecture.md)

---

## 🔒 SOX 合规

| 合规要求 | 实现方式 |
|----------|----------|
| **完整性** | 5W1H 完整记录（28 字段） |
| **不可更改** | SHA-256 哈希链 + 数据库约束 |
| **可追溯** | 多维度查询（用户、实体、模块、时间） |
| **访问控制** | 基于角色的权限（`audit:read` 等） |
| **保留期限** | HIGH: 7年 / MEDIUM: 5年 / LOW: 3年 |
| **定期审查** | 每日/每周自动完整性检查 |

---

## 📈 集成覆盖率

| 指标 | 数量 | 覆盖率 |
|------|------|--------|
| 已集成模块 | 44 个 | 83% |
| 自动记录操作 | 234 个 | - |
| 敏感操作标记 | 181 个 | - |
| Controller 覆盖 | 44/53 | 83% |

---

## 🔧 审计系统 vs 日志系统

| 维度 | 审计系统 | 日志系统 |
|------|----------|----------|
| **定位** | 业务合规、法规要求 | 技术运维、故障排查 |
| **记录内容** | 业务操作、数据变更 | HTTP 请求、错误日志 |
| **保留期限** | 3-7 年（按合规级别） | 14-30 天 |
| **可修改性** | 不可删除、不可修改 | 可清理、可归档 |
| **合规要求** | SOX、ISO 合规 | 无特殊要求 |
| **完整性保护** | 哈希链防篡改 | 无 |
| **查询方式** | 多维度业务查询 | 技术日志查询 |

---

## ✅ 使用检查清单

### Controller 层集成
- [ ] 导入装饰器：`import { Auditable, Sensitive, Financial } from '@/audit/decorators/auditable.decorator'`
- [ ] POST/PUT/PATCH/DELETE 方法添加 `@Auditable()`
- [ ] 敏感操作添加 `@Sensitive()`（密码、权限、删除）
- [ ] 财务操作添加 `@Financial()`（支付、退款）

### Service 层集成（可选）
- [ ] 注入 `AuditService`（如需记录详细变更）
- [ ] 记录 oldValue、newValue、changes
- [ ] 异常情况也记录审计日志（status: FAILED）

### 验证
- [ ] 执行操作后，访问 `/audit/logs` 能看到记录
- [ ] 审计日志包含完整的 5W1H 信息
- [ ] 敏感操作正确标记为 `isSensitive: true`

---

## 🧪 测试

详见测试用例文档（待补充）

---

## 🆘 遇到问题？

- 📖 查看 [故障排查指南](./12-troubleshooting.md)
- 💡 查看 [集成示例](./11-integration-guide.md)
- 📧 联系开发团队

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team

---

**创建时间**: 2025-11-15  
**更新时间**: 2025-12-25  
**状态**: ✅ 生产就绪  
**版本**: v1.0.0