Files
邹进 b7a7430cc3
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
- 审计注册表为可由系统任务、定时任务发起的动作声明落库策略(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>
2026-11-05 18:27:24 +09:00

5.0 KiB
Raw Blame History

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 系统删除最早月份的压缩包与说明文件