# 运营审计当前行为

## Purpose

描述审计调查、资源活动与审计时间线的当前可观察行为。

## Requirements

### Requirement: 审计时间线

系统 SHALL 支持按事件、操作者、资源、请求、关联标识和资金维度查询已记录的审计事实。新建的 `tb_integration_log` 在已取得稳定审计事件时 SHALL 写入其内部 ID 作为 `audit_event_id`，并且该日志的非空 `integration_id` SHALL 出现在对应事件列表和事件详情的 `investigation_refs.integration_refs` 中；关联生成失败时系统 MUST 保留 Integration Log 并记录可排查告警，且 MUST NOT 按名称、时间或摘要推断关联。历史 Integration Log 不在本要求的回填范围内。审计事件的构造、校验或持久化失败 MUST 记录可关联的结构化错误日志和二次失败记录，且 MUST NOT 改变已通过业务校验的业务操作结果或接口响应。尚无完成物理清理记录时，审计调查接口 MUST 继续查询在线审计事实，且返回的留存边界不得将数据标记为已归档。

#### Scenario: 审计时间线

- **GIVEN** 审计事实已存在
- **WHEN** 使用对应维度查询
- **THEN** 返回匹配的事实与稳定动作编码，不用访问日志替代

#### Scenario: 事件返回已关联外部交互引用

- **GIVEN** 一个在线审计事件有 `tb_integration_log.audit_event_id` 指向其内部 ID 的外部交互记录
- **WHEN** 查询全局审计事件列表或该事件详情
- **THEN** 该事件的 `investigation_refs.integration_refs` 返回该记录的 `integration_id`

#### Scenario: 事件没有关联外部交互引用

- **GIVEN** 一个在线审计事件没有稳定关联的外部交互记录
- **WHEN** 查询全局审计事件列表或该事件详情
- **THEN** `investigation_refs.integration_refs` 返回空数组

#### Scenario: 新外部交互日志具有稳定审计关联

- **GIVEN** 系统即将记录一次新的外部调用、入站回调或未发送裁决
- **WHEN** 写入对应 Integration Log
- **THEN** 该记录保存非空 `audit_event_id`，且其目标 Audit Event 已存在

#### Scenario: 缺少审计关联时保留外部交互日志

- **GIVEN** 一次新的外部交互日志没有稳定审计事件关联
- **WHEN** 系统尝试写入该 Integration Log
- **THEN** 系统持久化该 Integration Log、记录可排查告警，并返回空 `integration_refs`

#### Scenario: 审计写入失败不阻断业务

- **GIVEN** 一个业务操作已通过自身输入、权限和状态校验
- **WHEN** 该操作的审计事件构造、校验或持久化失败
- **THEN** 系统提交或返回该业务操作原本的结果，并以请求关联标识、动作编码和资源标识记录审计失败

#### Scenario: 尚无物理清理记录时查询在线审计

- **GIVEN** 审计或外部交互日志尚无完成物理清理的归档运行记录
- **WHEN** 调用任一依赖留存边界的审计调查接口
- **THEN** 系统返回当前在线数据或空列表
- **AND** 响应中的 `archived_before` 为空
- **AND** 系统不得因空留存边界返回服务端错误

### Requirement: 轮询审计事实保留边界

系统 SHALL 仅为产生业务事实变化、轮询失败、结果未知或人工触发的轮询操作持久化统一审计事件及资源快照。成功且无业务变化的自动轮询 MUST 不创建 `tb_audit_event` 或 `tb_audit_event_resource`，审计调查接口仅返回实际已保留的历史事实。

#### Scenario: 自动轮询成功但无业务变化
- **GIVEN** 一次自动轮询成功且没有改变任何业务状态、有效流量或风险结论
- **WHEN** 系统结束该轮询处理
- **THEN** 审计事件和审计资源表不新增该次轮询记录

#### Scenario: 自动轮询改变业务事实
- **GIVEN** 一次自动轮询产生可应用的业务状态或有效流量变化
- **WHEN** 系统提交该变化
- **THEN** 系统保留对应的审计事实与资源快照

### Requirement: 审计归档与日留存受控执行

系统 SHALL 提供独立的审计归档与日留存任务总开关。总开关关闭时，系统 MUST 不调度、不消费且安全跳过已入队的 Audit 日归档、Integration Log 日归档和日志日留存任务，不扫描或修改在线日志表。总开关开启时，每次任务执行 MUST 至多处理一个已结束的上海自然日；维护者可在低峰期重复执行以推进历史积压。

#### Scenario: 归档与留存总开关关闭
- **GIVEN** 审计归档与日留存任务总开关关闭
- **WHEN** 定时器触发或 Worker 取得已入队的归档或留存任务
- **THEN** 系统跳过该任务，不扫描 `tb_audit_event`、`tb_audit_event_resource` 或 `tb_integration_log`，且不创建归档或清理记录

#### Scenario: 总开关开启时处理积压
- **GIVEN** 审计归档与日留存任务总开关开启，且存在多个未处理的已结束自然日
- **WHEN** Worker 执行一次归档或留存任务
- **THEN** 系统至多处理一个自然日，并保留其余日期供后续受控执行

### Requirement: 审计在线数据逐日物理留存

系统 SHALL 以 Asia/Shanghai 已结束的自然日为单位处理统一审计事件及其资源快照的在线留存。每次留存执行 SHALL 从最早尚未完成清理的归档日开始，至多处理一个已结束的自然日；Integration Log 的 `pending` 记录不得阻断已通过完整性校验的审计事件及资源快照清理。任一审计归档日未通过完整性校验时，系统 MUST 保留该日及其后续日期的在线审计数据，且不得将它们标记为已清理。系统 MUST 先删除该日的审计资源快照，再删除该日的审计事件，并保留对象存储归档对象及清单作为恢复凭证。

#### Scenario: 已验证日期完成物理清理
- **GIVEN** 某已结束自然日的审计归档成功，归档对象和清单可读取且与在线记录范围、数量和校验摘要一致
- **WHEN** 日留存任务处理该日期
- **THEN** 系统分批删除该日在线审计资源快照和审计事件，并将该归档日标记为已清理

#### Scenario: Integration Log pending 不阻断审计清理
- **GIVEN** 某已结束自然日的审计归档已通过完整性校验，且同日存在 pending Integration Log
- **WHEN** 日留存任务处理该日期
- **THEN** 系统仍完成该日在线审计资源快照和审计事件的物理清理

#### Scenario: 归档校验失败阻断连续清理
- **GIVEN** 某尚未清理的归档日缺少归档、归档校验失败或清单与在线数据不一致
- **WHEN** 日留存任务处理该日期
- **THEN** 系统不删除该日或更晚日期的在线审计数据，并将失败信息写入独立日留存日志

#### Scenario: 失败后从未完成日期续跑
- **GIVEN** 日留存任务在某个归档日失败，较早日期已经标记为已清理
- **WHEN** 后续日留存任务再次执行
- **THEN** 系统从最早未完成清理的归档日继续处理，不重复删除已完成日期的数据

### Requirement: 日留存独立运行日志

系统 SHALL 将日留存的日期推进、清理成功和阻断失败写入独立轮转日志。该日志 MUST 位于 Worker 工作目录下配置的 `logs/audit-retention.log`，每条失败记录 MUST 包含归档日期、数据来源、失败分类和安全错误摘要。日留存和日归档路径 MUST NOT 将失败详情写入 `tb_log_archive_run.error_summary`。

#### Scenario: 留存日期被阻断
- **GIVEN** 日留存处理某个归档日时发生缺失账本、pending 记录、归档校验或删除错误
- **WHEN** 系统停止该日期推进
- **THEN** `logs/audit-retention.log` 记录该日期、来源、失败分类和错误摘要
- **AND** 对应账本记录的 `error_summary` 不写入该失败详情

#### Scenario: 留存日期清理成功
- **GIVEN** 某归档日通过全部校验并完成在线数据物理删除
- **WHEN** 系统完成该日期处理
- **THEN** `logs/audit-retention.log` 记录归档日期、各来源清理数量和耗时

### Requirement: 审计调查留存边界连续

系统 SHALL 仅将连续完成物理清理的审计归档日期间公开为已归档边界。在线审计调查接口 MUST 继续允许查询任何尚未物理清理的较早日期，且不得因某个较晚日期已归档而将仍在线的日期错误标记为已归档。

#### Scenario: 清理链存在未完成日期
- **GIVEN** 某较早归档日尚未完成清理
- **WHEN** 后续日期的归档已成功生成
- **THEN** 审计调查接口仍将较早未清理日期视为在线可查询数据

## 可达操作索引

本节只用于入口导航，不是行为 Requirement；业务义务以上述 Requirements 为准。

### 审计调查

`GET /api/admin/audit/actors/{kind}/{id}/events`（查询操作者行为时间线）；`GET /api/admin/audit/correlations/{correlation_id}/timeline`（查询业务关联时间线）；`GET /api/admin/audit/events`（查询全局审计事件）；`GET /api/admin/audit/events/{event_id}`（查询审计事件详情）；`GET /api/admin/audit/finance/timeline`（查询资金调查时间线）；`GET /api/admin/audit/integrations`（查询外部集成交互列表）；`GET /api/admin/audit/integrations/{integration_id}`（查询外部集成交互详情）；`GET /api/admin/audit/integrations/overview`（查询外部集成交互总览）；`GET /api/admin/audit/requests/{request_id}/timeline`（查询请求关联时间线）；`GET /api/admin/audit/resources/{resource_type}/{resource_id}/timeline`（查询通用资源时间线）；`GET /api/admin/audit/resources/search`（精确搜索注册资源）；`GET /api/admin/audit/risks/events`（查询风险事件明细）；`GET /api/admin/audit/risks/overview`（查询风险调查总览）。

### 资源活动

`GET /api/admin/agent/resource-activities/{resource_type}/{identifier}`（查询代理资源活动）；`GET /api/admin/enterprise/resource-activities/{resource_type}/{identifier}`（查询企业资源活动）。