44 lines
6.7 KiB
Markdown
44 lines
6.7 KiB
Markdown
## Why
|
||
|
||
功能 ID：`feature-504-multi-view-audit-center`
|
||
|
||
现有账号、资产 operation log、Access Log、Integration Log 与资金/订单等业务事实彼此割裂，无法稳定回答“谁在何时从哪个入口对哪些资源做了什么、为何产生资金或状态变化、外部系统经历了哪些尝试”。现在需要建立统一、不可变且可关联多资源的内部 Audit Event，并在不混淆四类事实边界的前提下提供操作者、资源、请求、业务链路、资金、风险和外部集成等多视角调查接口。由于 Audit Event 和 Integration Log 每日数据量可能很大，还需要把两类数据库日志按日压缩归档到对象存储，并在归档校验通过后按月删除 PostgreSQL 上月数据。
|
||
|
||
## What Changes
|
||
|
||
- 新建统一 `Audit Event + Event Resource` 写入能力：所有非查询业务操作，以及已识别主要业务资源后的成功、失败、拒绝、部分成功、系统自动状态变化和外部回调引发的内部变化，均按明确事务策略记录；普通查询和参数解析前失败不产生 Audit Event，Action Registry 明确登记的敏感读取除外。
|
||
- 建立动作、资源类型、资源角色、结果、风险、来源和外部可见性注册契约；每个事件至少关联一个主要资源，多资源操作为各资源保存事件发生时的业务标识快照及各自的前后变化。
|
||
- 建立平台多视角审计调查接口，覆盖全局事件、操作者、资源时间线、请求链路、业务关联链路、资金审计和风险事件；平台账号第一阶段均可读取完整业务审计数据，不实施细粒度权限码或平台数据范围过滤。
|
||
- 冻结前端审计导航契约：逐项列明业务列表/详情接口、`response.data` 字段路径、平台/代理/企业目标接口和参数映射；平台调查节点统一返回可跳转引用，缺少稳定标识时隐藏入口而不猜测。
|
||
- 为现有 Integration Log 建立只读调查中心，提供组合筛选、详情、尝试序列、资源外部交互轨迹和跨 Audit/Integration/Outbox/任务/Domain Ledger 的关联时间线；不提供重试、补偿、绑定或恢复写操作。
|
||
- 为代理和企业提供独立的安全资源活动投影：只允许查询自身数据范围内的资源，不暴露平台内部操作者、原因、备注、Audit Event ID 或外部交互细节，仅展示允许其感知的业务结论。
|
||
- 业务敏感字段对平台完整展示；密码、验证码、Token、Secret、私钥、回调凭据、Authorization、Cookie、签名 URL 和支付密钥等系统安全凭据在写入前删除，任何接口均不返回。
|
||
- 批量操作写一条批次根事件，并为每个实际变化的资源写子事件；跨请求、Outbox、Asynq、外部回调和后续业务步骤通过 `request_id`、`correlation_id` 和 `parent_event_id` 串联。
|
||
- 新增内部日志留存任务：按 `Asia/Shanghai` 自然日将 Audit Event/Event Resource 和 Integration Log 生成 `JSON Lines + gzip` 对象及 manifest；每月初仅在上月每日分片全部存在、数量和 SHA-256 校验一致后，受控删除 PostgreSQL 上月 Audit/Integration 数据。对象存储中的每日/月度备份长期保留且不被本任务删除；数据库删除后的历史不再由审计接口在线查询。Access Log 继续由应用服务器上的 Lumberjack 轮转和保留，不上传对象存储。
|
||
- **BREAKING**：统一 Audit Event 切换完成后，旧账号和资产 operation log 停止新增；旧表原样保留，不回填、不转换、不接入新审计中心，既有历史查询保持独立。新审计中心只展示切换后产生的 Audit Event。手动轮询日志继续承担任务运行事实，不被误当作统一业务审计表。
|
||
- 第一阶段不提供面向用户的审计导出、对象存储历史查询/恢复、敏感二次查看、风险处置、恢复操作、任意关系图或 Audit Event 修改/删除能力；内部自动归档不属于审计导出 API。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `audit-event-recording`: 定义不可变 Audit Event、多资源关联、操作者与入口快照、资源级前后变化、批次父子事件、事务可靠性和安全凭据删除规则。
|
||
- `audit-investigation-queries`: 定义平台全局、操作者、资源、请求、业务链路、资金和风险等多视角只读调查接口及通用资源时间线。
|
||
- `integration-log-investigation`: 定义 Integration Log 的组合筛选、详情、尝试序列、资源轨迹、异常总览和跨事实关联查询。
|
||
- `scoped-resource-activity`: 定义代理和企业按自身数据范围查询资源活动、安全结论投影和平台内部信息不可见规则。
|
||
- `audit-governance-cutover`: 定义全仓领域/资源/写入口盘点、Action Registry 覆盖、旧 Writer 停写、旧历史隔离、发布切换、监控与前向修复门禁。
|
||
- `audit-log-retention`: 定义 Audit Event 和 Integration Log 的每日压缩归档、manifest 校验、月初数据库物理删除、失败闭环及在线查询边界。
|
||
|
||
### Modified Capabilities
|
||
|
||
- `account-operation-audit`: 将账号操作从裸 goroutine 写旧表改为统一 Audit Event 同事务/失败短事务记录，并由统一多视角查询替代旧表新增。
|
||
- `asset-audit-readable-content`: 将资产可读字段从旧日志 JSON 补丁升级为统一资源快照与资源角色契约，使卡、设备、绑定、换货旧新资产和店铺可在多个资源时间线中交叉查询。
|
||
|
||
## Impact
|
||
|
||
- 新增 PostgreSQL 审计事件、事件资源及归档运行记录表、GORM Model、Repository、Action/Resource Registry、写入 Port/Adapter、审计上下文和 Query 投影；不建立外键或 GORM 关联标签，不新增依赖。
|
||
- 触及后台、代理、企业、个人客户、Open API、Application、旧 Service、Worker、定时任务和回调的非查询写入口；复杂写继续收口 Domain/Application，简单写使用 Application 事务脚本，读取统一进入 `internal/query`。
|
||
- 新增平台审计、Integration Log 调查和代理/企业资源活动 Handler、DTO 与 RouteSpec，并同步 `internal/bootstrap`、`cmd/api/docs.go`、`cmd/gendocs/main.go` 和中文 API/功能文档。
|
||
- 复用 Access Log、`pkg/sanitizer`、现有 Integration Log、现有 S3 兼容对象存储、公共 Asynq Scheduler、Domain Ledger、Outbox、数据范围中间件和统一错误响应；Access Log 继续面向开发排障，不进入数据库审计查询。
|
||
- 实施前必须以当前代码重新盘点全部领域、资源和写入口，不能把七月旧 490 项清单或旧 22 张 Ticket 直接视为现行契约；规划与验证覆盖真实 PostgreSQL 事务、分页索引、无 N+1、P95/P99、身份隔离、凭据不落库和旧写归零。
|