feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s

- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(always/on_success/outcome/log_only/none),未声明按 log_only
- 人工、开放接口、个人客户、外部系统发起的动作始终写审计表
- log_only 写所在服务 app.log(logger=audit),不含快照
- 对接日志不再补写 integration.attempt_started,无上游审计时 audit_event_id 为空
- 新增 audit.persist_overrides 按动作覆盖策略
- 审计覆盖扫描要求机器动作必须声明策略
- 新增 OpenSpec 提案 refactor-audit-log-persistence 与技术方案文档

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
邹进
2026-11-05 18:27:24 +09:00
parent 96ff9c1e35
commit b7a7430cc3
21 changed files with 1720 additions and 4 deletions

View File

@@ -0,0 +1,95 @@
## MODIFIED Requirements
### Requirement: 采集记录
系统 SHALL 把每次流量采集按结果分别写入两张表。
**成功表 `tb_card_traffic_collection`**
- 只写读数结果为有效的采集。
- 记录内容:采集时间、采集 ID、来源、场景、运营商账户、运营商原始读数、入队后的队列、写入判断(已写入、建起点、队列未满、读数下降、乱序、激活前结算用已有快照)。
- 写入成功时,还记录换算后的本月累计、是否触发防旧值、本次增量与流量事件 ID。
- 只为采集时刻有套餐的卡写成功记录;没有套餐的卡 MUST NOT 写成功记录。
**失败表 `tb_card_traffic_collection_failure`**
- 写读数结果为失败、限流、响应无效、无读数、读数无效的采集。
- 记录内容:采集时间、采集 ID、来源、场景、运营商账户、ICCID、失败类型、错误类别、上游返回码、上游返回信息(截断)、耗时。
- 失败记录 MUST 为所有被采集的卡写入,不判断卡是否有套餐。
**原始数据**
- 两张表都 SHALL 保存本次网关调用的原始数据:加密前的明文业务请求、HTTP 状态码、网关响应的 `code`、`msg`、`trace_id`、原始响应体,以及网关客户端内部重试次数。
- 原始响应能解析为 JSON 时按 JSON 保存,否则按文本保存。超过 4 KB 时截断,并标记已截断。
- 网关客户端内部发生过重试时,保存最后一次的请求与响应。
- 系统 MUST NOT 保存加密后的报文、签名、应用标识、密钥或请求头。
**通用规则**
- 采集 ID 等于对接日志的 `integration_id`,MUST 随流量事件与扣费审计传递,使扣费可追溯到对应采集记录。
- 采集记录写入失败 MUST 只记录告警,不影响扣减与卡状态。
#### Scenario: 被队列拦下的采集
- **WHEN** 有套餐的卡本次读数使队列出现下降
- **THEN** 系统在成功表写一条采集记录,判断为读数下降,记录队列内容与原始响应,不写快照
#### Scenario: 从扣费追到采集
- **WHEN** 维护者从一笔扣费排查
- **THEN** 可经流量事件的采集 ID 找到成功表中对应的原始读数、队列与原始响应
#### Scenario: 没套餐的卡采集成功
- **WHEN** 没套餐的卡被采集且读数有效
- **THEN** 系统不写成功记录
#### Scenario: 没套餐的卡采集失败
- **WHEN** 没套餐的卡查流量超时
- **THEN** 系统在失败表写一条记录,失败类型为失败,错误类别为超时,HTTP 状态码为空
#### Scenario: 上游返回业务错误
- **WHEN** 网关返回非成功的业务码
- **THEN** 失败表记录上游返回码、返回信息、`trace_id` 与原始响应体
#### Scenario: 原始响应过长
- **WHEN** 网关原始响应体超过 4 KB
- **THEN** 系统保存前 4 KB,并标记已截断
#### Scenario: 不保存敏感报文
- **WHEN** 任一采集记录写入原始数据
- **THEN** 记录中不含加密报文、签名、应用标识与密钥
## ADDED Requirements
### Requirement: 采集记录在线保留与到期归档
采集成功表与失败表 SHALL 按采集时间按月分区,在线保留当月加最近 2 个整月。月分区的月末早于"当前时间减 2 个月"时即为到期。
到期分区 SHALL 由 leader worker 的分区维护任务按以下顺序处理:
1. 把分区从父表摘出,使其不再参与在线查询;
2. 按采集时间与 ID 排序,流式导出为带表头的 CSV,并以 gzip 压缩,写入 worker 运行目录下的 `archive/traffic-collection/`;
3. 重新读取压缩包统计行数,与分区行数比对;同时生成同名说明文件,记录表名、月份、行数、最早与最晚采集时间、文件大小、SHA-256 与导出时间;
4. 行数一致后删除已摘出的分区。
约束:
- 压缩包与说明文件 MUST 先以临时文件名写入,校验通过后再改为正式文件名。
- 导出或校验失败时,系统 MUST 保留已摘出的分区,记录错误日志,并在下一轮维护时重试;MUST NOT 在没有完成校验的压缩包时删除分区。
- 本地 SHALL 只保留最近 3 个月的压缩包,个数可配置。
- 维护任务 SHALL 继续预建未来月份的分区。
#### Scenario: 到期分区归档
- **GIVEN** 当前为 2027-01-01,成功表存在 2026-10 分区
- **WHEN** 分区维护任务运行
- **THEN** 系统生成 `tb_card_traffic_collection_202610.csv.gz` 与说明文件,行数与分区一致后删除该分区
#### Scenario: 导出失败
- **WHEN** 归档过程中写压缩包失败
- **THEN** 已摘出的分区保留,不生成正式文件名的压缩包,下一轮维护重试
#### Scenario: 在线查询不包含已归档月份
- **WHEN** 查询的时间范围落在已归档月份
- **THEN** 接口返回空结果,不报错
#### Scenario: 本地压缩包超过保留个数
- **WHEN** 本地已有压缩包的月份数超过配置的保留个数
- **THEN** 系统删除最早月份的压缩包与说明文件

View File

@@ -0,0 +1,20 @@
## ADDED Requirements
### Requirement: 停复机指令调用前结束的跳过记录
停复机指令在调用上游之前结束时,系统 SHALL 写一条结果为跳过(`skipped`)的停复机记录,并在原因中写明结束原因。适用情况:
- 执行前判断卡已是目标状态;
- 执行前判断停复机条件不再满足;
- 卡不允许停复机(如关闭轮询、规则不允许)。
被本系统限流推迟、稍后会再次执行的指令 MUST NOT 写跳过记录;限流推迟仍按现有分钟计数观测。跳过记录 MUST NOT 写统一审计。
#### Scenario: 执行前已是目标状态
- **GIVEN** 一条停机指令待执行
- **WHEN** 执行前判断卡已经是停机状态并结束指令
- **THEN** 系统写一条结果为跳过、原因为已是目标状态的停复机记录,不调用上游
#### Scenario: 限流推迟
- **WHEN** 停机指令因所在限流组本秒额度用尽被推迟
- **THEN** 系统不写停复机记录

View File

@@ -0,0 +1,116 @@
## ADDED Requirements
### Requirement: 记录查询公共约定
系统 SHALL 为每类独立业务记录提供一个后台列表接口,接口遵循以下约定。
**查询范围**
- 资产标识选填。传入时只查该卡或该资产,支持虚拟号、ICCID、MSISDN,设备支持 IMEI、SN;不传时查全部。
- 资产标识解析不到资产时,接口 MUST 返回空页,不报错。
- 原有的单卡、单套餐接口 SHALL 保留,与列表接口使用同一查询逻辑。
**时间范围**
- 开始时间与结束时间 MUST 必填,跨度不超过 31 天,按上海时间解析;结束时间不含。
- 单卡、单套餐接口未传时间时,默认取最近 31 天。
- 查全部时除时间范围外,MUST NOT 要求其他筛选条件。
**分页与排序**
- 页码默认 1;每页条数默认 20,最大 100。采集成功记录沿用现有上限 200。
- 返回总数、页码、每页条数与当前页记录。
- 按记录时间倒序排列,时间相同时按 ID 倒序。
**其他**
- 系统 SHALL 为本能力列出的筛选条件建立所需索引,使带时间范围的查询不扫描时间范围外的分区。
- 接口 MUST 需要平台账号登录。
- 接口 MUST 在路由声明中登记输入与输出结构,并同步生成接口文档。
#### Scenario: 查单卡
- **WHEN** 请求带 ICCID 和 7 天时间范围
- **THEN** 系统只返回该卡在范围内的记录,并分页、按时间倒序返回
#### Scenario: 查全部
- **WHEN** 请求只带 7 天时间范围
- **THEN** 系统返回范围内全部记录的第一页与总数
#### Scenario: 缺少时间范围
- **WHEN** 列表接口请求未带开始或结束时间
- **THEN** 系统拒绝请求并提示时间范围必填
#### Scenario: 时间跨度超限
- **WHEN** 请求的时间跨度超过 31 天
- **THEN** 系统拒绝请求并提示跨度上限
#### Scenario: 标识找不到资产
- **WHEN** 请求的资产标识不存在
- **THEN** 系统返回总数为 0 的空页
### Requirement: 流量采集记录查询
系统 SHALL 提供两个采集记录列表接口:
- 采集成功记录:`GET /traffic-collections`。筛选条件:资产标识、运营商账户、写入判断、来源、场景、是否产生增量、是否触发防旧值。
- 采集失败记录:`GET /traffic-collection-failures`。筛选条件:资产标识、运营商账户、失败类型、错误类别、上游返回码、来源、场景。
两者都 MUST 返回原始请求与原始响应字段。单卡采集记录接口 SHALL 支持"包含失败"参数:默认只返回成功记录;开启时合并成功与失败记录,并按采集时间倒序返回。
#### Scenario: 按运营商账户查失败
- **WHEN** 查询某运营商账户近 1 天、错误类别为超时的采集失败记录
- **THEN** 系统返回该账户下所有卡的超时失败记录,含上游返回与原始数据
#### Scenario: 查产生增量的采集
- **WHEN** 查询近 1 天产生增量的采集成功记录
- **THEN** 系统只返回增量大于 0 的记录
#### Scenario: 单卡合并查看
- **WHEN** 单卡采集记录接口开启"包含失败"
- **THEN** 成功与失败记录合并后按采集时间倒序分页返回,每条标明是成功还是失败
### Requirement: 停复机记录查询
停复机记录列表 SHALL 支持以下筛选条件:资产标识(不再只支持 ICCID)、运营商账户、动作、来源、场景、原因、结果(含跳过)、错误类别、指令号。单卡停复机历史 SHALL 支持动作、结果、来源筛选。
#### Scenario: 按场景与原因查
- **WHEN** 查询近 7 天场景为退款、结果为跳过的停复机记录
- **THEN** 系统返回匹配记录,并带跳过原因
#### Scenario: 用虚拟号查
- **WHEN** 用卡的虚拟号查询停复机记录
- **THEN** 系统返回该卡的停复机记录
### Requirement: 流量与冲正记录查询
系统 SHALL 提供以下列表接口:
| 记录 | 筛选条件 |
|---|---|
| 套餐日流量详单 | 资产标识、套餐使用记录、套餐、运营商账户、日期范围 |
| 卡日流量 | 资产标识、运营商账户、日期范围、用量下限 |
| 套餐流量冲正流水 | 资产标识、套餐使用记录、操作人、调整方向(补扣或退回)、时间范围 |
现有套餐日流量详单接口 SHALL 增加分页。现有单套餐冲正流水接口 SHALL 增加时间范围筛选。
#### Scenario: 查异常大流量
- **WHEN** 查询近 3 天、单日用量不低于 10240 MB 的卡日流量
- **THEN** 系统返回所有满足条件的卡与日期,按日期倒序分页
#### Scenario: 查全部冲正
- **WHEN** 查询近 30 天的全部退回类冲正流水
- **THEN** 系统返回所有卡的退回类冲正记录,含操作人与调整前后用量
### Requirement: 退款后处理尝试查询
系统 SHALL 提供退款后处理尝试记录列表接口。筛选条件:退款单 ID、退款单号、资产标识、处理步骤、结果、错误码、触发方式、时间范围。
退款列表 SHALL 增加后处理状态筛选,可筛出"需人工处理"。退款列表与详情 SHALL 返回后处理次数、最后错误与下次重试时间。
#### Scenario: 查需人工处理的退款
- **WHEN** 退款列表按后处理状态"需人工处理"筛选
- **THEN** 系统返回所有已转人工的退款单,并带最后错误
#### Scenario: 查一张退款单的全部尝试
- **WHEN** 按退款单号查询尝试记录
- **THEN** 系统按时间倒序返回该单每一次尝试的步骤、结果、错误码与触发方式

View File

@@ -0,0 +1,160 @@
## MODIFIED Requirements
### Requirement: 审计时间线
系统 SHALL 支持按事件、操作者、资源、请求、关联标识和资金维度查询已记录的审计事实。新建的 `tb_integration_log` 在已取得稳定审计事件时 SHALL 写入其内部 ID 作为 `audit_event_id`;没有上游审计事件时 `audit_event_id` SHALL 为空,系统 MUST NOT 为补齐关联而另写审计事件,并且该日志的非空 `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** 该记录的 `audit_event_id` 为空
- **AND** 审计事件表不新增 `integration.attempt_started` 事件
#### 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 NOT 创建 `tb_audit_event` 或 `tb_audit_event_resource`,无论成功、失败或结果未知;其可查证据由采集记录、采集失败记录、停复机记录、日流量记录与应用日志提供。审计调查接口仅返回实际已保留的历史事实。
#### Scenario: 自动轮询成功但无业务变化
- **GIVEN** 一次自动轮询成功且没有改变任何业务状态、有效流量或风险结论
- **WHEN** 系统结束该轮询处理
- **THEN** 审计事件和审计资源表不新增该次轮询记录
#### Scenario: 自动轮询同步流量并扣减
- **GIVEN** 一次自动轮询读到有效增量并完成扣减
- **WHEN** 系统提交该变化
- **THEN** 审计事件表不新增流量同步或扣减事件
- **AND** 采集记录保存该次读数、扣减判定、增量与原始响应
#### Scenario: 自动轮询调用失败
- **WHEN** 一次自动轮询查流量超时或返回无效响应
- **THEN** 审计事件表不新增记录
- **AND** 采集失败记录保存该次失败的错误类别、上游返回与原始数据
#### Scenario: 轮询导致套餐到期
- **GIVEN** 轮询或定时任务判定一个套餐已到期
- **WHEN** 系统把套餐置为已过期
- **THEN** 系统保留套餐到期的审计事实与资源快照
#### Scenario: 人工触发刷新
- **WHEN** 后台账号手动刷新一张卡
- **THEN** 系统为该操作写审计事件
## ADDED Requirements
### Requirement: 审计动作落库策略
系统 SHALL 在统一审计注册表中为每个动作声明落库策略,取值为:总是写(`always`)、只写成功(`on_success`)、只写结论(`outcome`)、只写应用日志(`log_only`)、不写(`none`)。
- 操作者为后台账号、个人客户、OpenAPI 或外部系统时,系统 MUST 按"总是写"处理,不受动作策略限制。
- 操作者为系统任务或定时任务、且动作未声明策略时,系统 MUST 按"只写应用日志"处理。
- 审计覆盖扫描 MUST 在存在可由系统任务或定时任务发起、但未声明落库策略的动作时失败。
- 系统 SHALL 提供按动作编码覆盖落库策略的运行时配置;覆盖只作用于系统任务与定时任务操作者。
- 是否写入审计 MUST NOT 改变业务操作的结果或接口响应。
#### Scenario: 人工操作始终写审计
- **GIVEN** 动作 `order.create` 对系统任务声明为只写应用日志
- **WHEN** 后台账号创建订单
- **THEN** 系统写入审计事件与资源快照
#### Scenario: 新增机器动作未声明策略
- **WHEN** 系统任务写一个未声明落库策略的动作
- **THEN** 审计事件表不新增记录,应用日志新增一行该动作的结构化日志
#### Scenario: 覆盖扫描发现未声明策略
- **GIVEN** 一个可由系统任务发起的动作没有声明落库策略
- **WHEN** 运行审计覆盖扫描
- **THEN** 扫描失败并列出该动作编码
#### Scenario: 运行时覆盖
- **GIVEN** 运行时配置把 `package_usage.expire` 覆盖为只写应用日志
- **WHEN** 定时任务使一个套餐到期
- **THEN** 审计事件表不新增记录,应用日志新增一行
- **AND** 删除该覆盖后,下一次到期重新写审计事件
### Requirement: 系统过程动作写应用日志
落库策略为"只写应用日志",或"只写成功"时的失败结果,系统 SHALL 在所在服务的应用日志中写一行结构化日志,并 MUST NOT 写入审计事件表与资源表。
- 日志行 MUST 带固定 logger 名 `audit`。
- 日志行 MUST 包含:动作编码、操作者类型与标识、来源、结果、资源类型与资源键、关联标识、请求标识、错误码、摘要。
- 日志行 MUST NOT 包含变更前后快照、主体数据、密钥、令牌或加密报文。
- 成功写 Info 级别,失败写 Warn 级别。
- 应用日志写入失败 MUST NOT 重试,也 MUST NOT 影响业务结果。
#### Scenario: 网络状态同步
- **WHEN** 系统任务同步一张卡的网络状态
- **THEN** 应用日志新增一行 `logger=audit`、动作编码为 `iot_card.worker_network_sync` 的记录
- **AND** 该行不含变更前后快照
#### Scenario: 不新增审计表数据
- **WHEN** 系统任务写任一只写应用日志的动作
- **THEN** `tb_audit_event` 与 `tb_audit_event_resource` 均无新增
### Requirement: 自动重试动作只写结论
落库策略为"只写结论"的动作,系统 SHALL 只在最终结论产生时写一条审计事件。最终结论指最终成功,或重试用尽转人工处理。
- 中间失败 MUST NOT 写审计事件,只写应用日志;日志行 MUST 带尝试序号与对应尝试记录标识。
- 结论事件的元数据 MUST 包含总尝试次数、首次失败时间与最后错误码。
- 同一业务对象的同一结论 MUST 只有一条审计事件。
- 每一次尝试的细节 MUST 由对应业务尝试记录保存,并可分页查询。
#### Scenario: 重试后成功
- **GIVEN** 一张退款单的资产后处理前两次失败、第三次成功
- **WHEN** 第三次处理完成
- **THEN** 审计事件表只有一条结论为成功的事件,元数据中总尝试次数为 3
- **AND** 尝试记录中有三条记录
#### Scenario: 重试用尽转人工
- **GIVEN** 一张退款单的资产后处理连续失败达到上限
- **WHEN** 系统将其标记为需人工处理
- **THEN** 审计事件表写入一条结论为失败的事件,包含最后错误码
#### Scenario: 结论重复写入
- **WHEN** 同一退款单的成功结论被重复提交
- **THEN** 审计事件表仍只有一条该结论事件

View File

@@ -0,0 +1,42 @@
## ADDED Requirements
### Requirement: 退款资产后处理尝试记录
系统 SHALL 在每次执行退款资产后处理时写一条尝试记录,只新增,不修改、不删除。
- 记录内容:退款单、处理步骤(套餐失效、接续激活、停机评估或停机)、资产类型与资产 ID、ICCID、尝试序号、触发方式(Outbox 投递、补偿扫描、人工重试)、结果、错误码、错误信息(截断)、关联的停复机记录、耗时、记录时间。
- 尝试记录 SHALL 按月分区。
- 尝试记录写入失败 MUST 只记录告警,不影响后处理结果。
#### Scenario: 一次尝试失败
- **WHEN** 退款资产后处理在套餐失效步骤失败
- **THEN** 系统写一条尝试记录,步骤为套餐失效,结果为失败,并带错误码与错误信息
#### Scenario: 一次尝试成功
- **WHEN** 退款资产后处理全部步骤成功
- **THEN** 系统写一条结果为成功的尝试记录
### Requirement: 退款资产后处理重试上限
系统 SHALL 在退款单上维护资产后处理的当前状态、已尝试次数、最后错误与下次重试时间。
- 后处理失败时,系统 SHALL 按指数退避计算下次重试时间,间隔最长 1 小时。
- 已尝试次数达到 10 次仍未成功时,系统 MUST 把状态置为"需人工处理",并停止自动重试。
- Outbox 投递与补偿扫描 MUST 按上述状态与下次重试时间判断是否执行:未到下次重试时间的不执行,"需人工处理"的不执行。
- 后台人工重试 SHALL 允许重新执行"需人工处理"的退款单,并记为人工重试触发;执行前已尝试次数不清零。
- 重复执行 MUST 保持既有幂等:不重复失效套餐,不重复处理资产。
#### Scenario: 退避重试
- **GIVEN** 一张退款单的资产后处理第 3 次失败
- **WHEN** 补偿扫描在下次重试时间之前运行
- **THEN** 系统不执行该退款单的后处理
#### Scenario: 达到上限转人工
- **GIVEN** 一张退款单的资产后处理已失败 9 次
- **WHEN** 第 10 次仍失败
- **THEN** 退款单状态为需人工处理,Outbox 与补偿扫描不再执行它,审计写一条结论为失败的事件
#### Scenario: 人工重试成功
- **GIVEN** 一张需人工处理的退款单
- **WHEN** 运营在后台发起人工重试并成功
- **THEN** 退款单状态为已完成,尝试记录新增一条触发方式为人工重试、结果为成功的记录