Files
junhong_cmp_fiber/docs/2026-11-05-审计日志写入改造技术方案.md
邹进 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

38 KiB
Raw Permalink Blame History

审计日志写入改造技术方案

日期:2026-11-05 状态:方案已定,未实施(结论见第 10 节) 关联:openspec/changes/add-audit-integration-write-switches(全局写入开关,本方案是其后的"按动作分级") 范围:本方案基于 Iteration/8-11 迭代实施,只部署到测试环境(推送 8-11 由 .gitea/workflows/deploy.yaml 自动部署)。本方案不修改生产环境的代码、配置或服务;第 1 节的生产数据只用来说明问题和估算效果。

1. 背景

1.1 现状数据(生产近 14 天,只读统计)

指标 数值
tb_audit_event 日均新增 约 122 万条(含停机重试风暴);扣掉风暴约 20 万条
机器发起(system_task / scheduled_job)占比 99% 以上
人、开放接口、个人客户、外部系统发起 约 1,210 条/天
每条事件含索引 约 1.9 KB;每条资源快照约 1.2 KB;平均 2–3 条资源
日均新增存储 约 6 GB(风暴期)/ 约 1 GB(平时)
索引数 tb_audit_event 14 个、tb_audit_event_resource 7 个、tb_integration_log 13 个

测试环境日均约 12.6 万条,几乎全是系统任务:流量同步 5.6 万、扣减 2.6 万、网络状态同步 2.5 万、优先轮询约 1.4 万。

1.2 问题

  1. 审计表被当成过程日志用。 每次轮询同步、每次扣减、每次对接调用开始、每次失败重试都写一条事件加 2–3 条资源快照。一次业务动作产生多次写入,而且每次写入要维护 21 个索引。
  2. 失败重试没有收敛。 退款后处理停机失败(refund.process_asset)和自动停机失败(iot_card.auto_stop),每重试一次就写一条审计。11-05 10:16–11:47,86 张卡产生了 26.1 万次停机失败,一个风暴就占了当天审计量的六成以上。
  3. 对接日志顺带写审计。 integrationlog.Repository.Start 在没有上游审计事件时,会补写一条 integration.attempt_started(internal/infrastructure/integrationlog/repository.go:119),这一项每天约 45.6 万条。它与 tb_integration_log 本身完全重复。
  4. 后果。 11-03 生产 PostgreSQL IO 打满,轮询停摆约 1.7 天,审计和对接日志的写入与留存扫描是主要 IO 来源之一。

1.3 老系统做法(/home/zoujin/works/golang/kg/qc,供参考)

  • 人工后台操作:写 tbl_system_log。
  • 业务过程:按业务各写一张表,如 tbl_order_log、tbl_card_wallet_auto_renew_log、tbl_next_month_log,以及充值、短信日志。
  • 下游代理调用我方接口:只这一类写 tbl_agent_pool_api_call_log。
  • 网关调用和轮询:全部写 log4j 按天滚动的文本日志,不进数据库。

2. 目标与原则

目标:审计表只回答两个问题:

  1. 人(或代表人的外部系统)做了什么;
  2. 钱和套餐、卡的业务状态是怎么变的。

审计日均降到几千条,一年不到 10 GB,不再依赖归档和清理来扛量。

原则:

原则 说明
人工操作全留 后台账号、个人客户、开放接口、外部系统发起的动作,成功和失败都写审计
机器动作只留"结果" 系统任务和定时任务只在资金或业务状态真正改变时写审计;无变化、同步、读取不写
每次失败都可查,审计只记结论 自动重试的每一次尝试都完整记在业务尝试记录表里(时间、第几次、错误码、上游返回),可分页查询;审计只记这件事的最终结论:成功,或重试用尽转人工
过程数据去业务表 已有专门记录表的(停复机记录、采集记录、扣减效果、日流量),审计不再重复写
排查用的走文本日志 只用于排查、不需要按业务查询的,写入现有应用日志 app.log,沿用现有轮换,由日志同步服务器归集
不改变业务结果 写不写审计,都不影响业务事务成功与否(与现状 Append 吞错一致)

3. 数据分层

层 存储 放什么 保留
L1 审计 tb_audit_event + tb_audit_event_resource 人工操作;机器发起的资金、套餐生命周期、停复机成功等状态变化 按现有留存策略
L2 业务记录 各业务专表 停复机调用 tb_card_stop_resume_record、流量采集 tb_card_traffic_collection、扣减效果与日流量、对接调用 tb_integration_log、退款单上的后处理状态 按各表策略
L3 文本日志 现有应用日志 app.log(zap JSON + lumberjack 轮换) 机器过程类动作的结构化日志,例如停机原因更新、网络状态同步、通知投递、优先轮询、流量重置明细 沿用 logging.app_log 轮换;长期留存由日志同步服务器负责
L4 不写 — 与 L1/L2 完全重复的,例如 integration.attempt_started —

4. 动作去向清单

4.1 保留在审计(L1)

人工及外部发起(约 1,210 条/天,全部保留):

发起方 日均 主要动作
后台账号 约 404 手动刷新卡、设备切卡、回收、设 WiFi、手动复机、改套餐到期、设备重启、下单、退款、审批、登录等
开放接口 约 612 下单、代理钱包扣款、开放接口复机
个人客户 约 182 绑资产、建手机号关联、更新微信身份、绑手机号
外部系统 约 9 支付确认、外部回调接收

机器发起但改变资金或业务状态(方案 A 约 3,510 条/天):

动作 日均 方案 B 去向
iot_card.auto_start 自动复机 1,127 移到 L2 停复机记录
package_usage.reset_traffic 流量重置 1,049 移到 L2(套餐自身的重置时间加日流量记录)
iot_card.auto_stop 自动停机,仅成功 380 移到 L2 停复机记录
commission.calculate 分佣计算 238 保留
package_usage.expire / activate / 退款失效 176 / 90 / 6 保留
导入建卡、建设备、设备分配 93 / 52 / 44 保留
系统下单、订单套餐失效明细、员工代收账单 77 / 74 / 51 保留
外部回调接收、审批同步、退款批准、佣金回溯判定 27 / 13 / 6 / 6 保留
refund.process_asset,仅成功 4 保留

4.2 移出审计

动作 现在日均(估算) 去向 说明
integration.attempt_started 约 45.6 万 L4 不写 tb_integration_log 已有同样内容;audit_event_id 留空
refund.process_asset 失败 约 32.6 万 L2 退款后处理尝试记录 每次尝试一条,记在新表 tb_refund_post_process_attempt;退款单上保留当前状态、次数和最后错误;审计只在最终成功或转人工时写一条
iot_card.auto_stop 失败 约 31.5 万 L2 停复机记录 tb_card_stop_resume_record 每次实际调用一条,已含错误分类
iot_card.auto_stop_reason_update 约 3.8 万 L3 文本 只改停机原因、不改停复机状态
iot_card.worker_traffic_sync 约 3.1 万(正常时 6–8 万) L2 采集记录 tb_card_traffic_collection 已经记录每次采集
iot_card.worker_network_sync 约 2.6 万(正常时 6–8 万) L3 文本 结果就是卡上的网络状态字段
package_usage.deduct_traffic 约 2.1 万 L2 采集记录、扣减效果、日流量三张表已经能还原
notification.deliver、polling_priority.* 等 约 0.5 万 L3 文本 —

4.3 方案选择

采用方案 B。停复机和流量重置都已经有更合适的业务表,审计里只留人工操作和资金、套餐生命周期类动作。

方案 审计事件/天 占现在 每天新增存储
现在 约 122 万 100% 约 6 GB
方案 A:4.1 全留 约 4,700 0.39% 约 24 MB
方案 B:停复机、流量重置移到 L2 约 2,200 0.18% 约 11 MB

5. 技术设计

5.1 注册表增加"落库策略"

internal/infrastructure/audit/registry.go 的 ActionDefinition 新增字段:

// PersistPolicy 决定动作是否写入审计表。
type PersistPolicy string

const (
	PersistAlways    PersistPolicy = "always"     // 成功失败都写(人工动作默认)
	PersistOnSuccess PersistPolicy = "on_success" // 只写成功;失败写文本日志
	PersistOutcome   PersistPolicy = "outcome"    // 只写最终结论:成功、或重试用尽转人工;中间失败不写审计(每次尝试在业务尝试记录表)
	PersistLogOnly   PersistPolicy = "log_only"   // 不写表,写 L3 文本日志
	PersistNone      PersistPolicy = "none"       // 什么都不写
)

type ActionDefinition struct {
	// ……现有字段
	Persist PersistPolicy // 为空时按操作者决定,见 5.2
}

动作的策略在注册表中集中定义,调用方不改代码。这样一份清单就能看清哪些动作进审计,评审和后续调整也只需改这一处。

5.2 默认规则

Persist 为空时,按本次写入的操作者类型决定:

操作者 actor_kind 默认策略
account、personal_customer、openapi、external_system always
system_task、scheduled_job log_only

因此新增机器动作默认不进审计,要进审计必须在注册表显式声明 always、on_success 或 outcome。这能防止后面新增的轮询、同步类动作再次把审计表写满。

同一动作可能同时由人和机器触发,例如 order.create、iot_card.manual_start 与开放接口复机。策略按"动作 + 操作者"判断:注册表里的 Persist 只约束机器操作者,人工操作者始终是 always。

5.3 Writer 改造

只改 internal/infrastructure/audit/writer.go 的 AppendAndGet,在注册校验通过后、组装事件前分流:

action, ok := w.registry.Action(input.ActionCode)
// ……现有校验
switch w.persistDecision(ctx, tx, action, input) {
case decisionSkip:
	return nil, nil
case decisionLog:
	w.machineLog.Info("audit", auditLogFields(action, input)...)
	return nil, nil
}
// ……现有写表逻辑

要点:

  1. 调用方兼容:Append 本来就吞错并返回 nil,调用方不受影响。AppendAndGet 有 11 处调用(refund/clawback.go、refund/service.go、businessusergroup、packagetrafficalert、distribution、refund_channel、integrationlog),实施时逐一确认能处理返回的 nil 事件。这 11 处大多是人工或资金动作,仍然是 always,实际不会拿到 nil。
  2. outcome 的判定:由调用方在写审计时标明这次是不是最终结论,AppendInput 增加 Final bool。
    • 中间失败(Final=false)不写审计表,只写一行应用日志,日志里带尝试记录 ID 方便对照;
    • 最终成功,或重试用尽转人工(Final=true)写一条审计,metadata 带总尝试次数、首次失败时间、最后错误码;
    • 用业务键作 EventID(例如 refund-asset:{refund_id}:outcome),保证同一件事的结论只有一条。
    • 每一次尝试的细节都不丢,都在业务尝试记录表里(见 5.5),可分页查询(见 5.9)。
  3. 文本日志写入现有应用日志:不新建日志文件,也不新增轮换配置。Writer 直接使用 logger.GetAppLogger().Named("audit"),写入现有的 app.log,轮换沿用 logging.app_log(测试环境配置见 5.8),由日志同步服务器自动归集。NewWriter 签名不变,调用方不用改。
    • 每行固定 "logger":"audit"、"msg":"audit_event",便于在同步端按 logger 名过滤和建索引;
    • 字段:action_code、actor_kind、actor_id、source、result、resource_type、resource_key、correlation_id、request_id、error_code、summary;中间失败额外带 attempt(第几次)和尝试记录 ID;
    • 级别:成功为 Info,失败为 Warn;
    • 不写 before/after 快照与主体数据,避免敏感数据进入文本日志;需要变化值的动作(如流量重置前后用量)只写必要的数值字段。
  4. 运行时覆盖:在 add-audit-integration-write-switches 的全局开关之外,增加一个按动作覆盖的配置 audit.persist_overrides(动作编码 → 策略)。出问题时不发版就能把某个动作临时降为 log_only,或恢复为 always。

5.4 对接日志不再补写审计

internal/infrastructure/integrationlog/repository.go 的 Start:

  • 删除 input.AuditEventID == nil 时补写 integration.attempt_started 的逻辑(第 118–120 行)。上游有审计事件时照常关联;没有时 audit_event_id 留空。
  • 注册表里的 integration.attempt_started 设为 none,作为兜底。
  • auditEventIDForSeries 按 trigger_series 回查审计的逻辑保留,但需要确认它不会走慢查询(它会查审计表)。

5.5 失败重试收敛(与停机风暴止血配套)

审计只记结论之后,排查问题靠的是每一次尝试的记录,同时重试本身要收敛。这两件可以单独开 Change,但必须先于或同时上线:

  1. 退款后处理(internal/service/refund/approval_decision.go 的 ProcessAssetPostProcessing,stopAsset → ManualStopCard):
    • 退款单增加或复用后处理字段:asset_post_status、asset_post_attempts、asset_post_last_error、asset_post_next_at,表示当前状态;
    • 新增尝试记录表 tb_refund_post_process_attempt,每次尝试一条,不修改、不删除。字段:refund_id、step(停机、套餐失效、钱包回收等)、asset_type、asset_id、iccid、attempt、trigger(outbox 投递、补偿扫描、人工重试)、result、error_code、error_message、stop_resume_record_id(关联到那次停机调用)、duration_ms、created_at。按月分区。每单最多 10 次,量可控;
    • 失败按指数退避,超过 N 次(建议 10 次)标记为"需人工处理",不再自动重试;
    • outbox 与 RecoverRefundPostProcessing 都按这几个字段判断,不再无限重投。
  2. 自动停机:8-11 上的停机已经走停复机指令队列(stop-resume-command-queue),按错误分类处理:终态不可操作不重试,限流按退避处理。退款停机只请求停机评估。本次不改这部分。
    • 每次实际调用上游,已经在 tb_card_stop_resume_record 记一条,包括第几次、错误类别、上游返回码与信息、耗时。
    • 指令在调用上游前就结束的情况(已是目标状态、条件不再满足、卡不允许停复机)现在没有记录。改为在停复机记录里写 result=skipped,并写明原因,保证"为什么没停"也能查到。限流推迟后还会再执行,不写记录,沿用现有的分钟计数。

5.6 方案 B 的业务表补位

移出的动作 补位方式 现状
iot_card.auto_start / auto_stop 成功 tb_card_stop_resume_record(每次实际调用一条,含来源、场景、原因、结果) Iteration/8-11 已有
package_usage.reset_traffic 套餐使用记录的 last_reset_at / next_reset_at 加日流量记录 已有;重置前后用量写一行 app.log(logger=audit)备查
iot_card.auto_start / auto_stop 的停机原因、触发场景 tb_card_stop_resume_record 的 source、scene、reason 已有;原审计里的 before/after 卡状态不再保留,卡当前状态以卡表为准

后台"卡操作记录"之类的页面如果要看到停复机时间线,查询侧改为合并审计和停复机记录两个来源,不要回头再写审计。

5.7 审计覆盖治理

internal/governance/auditcoverage/scanner.go 扫描每个入口的 AuditEvent、DomainLedger、IntegrationLog 分类。本次需要做三件事:

  • 对移到 L2、L3、L4 的入口,把 AuditEvent 分类改为不写,并在 DomainLedger 里写明对应的业务表;
  • 覆盖扫描增加一条校验:机器操作者的动作必须在注册表显式声明 Persist,否则扫描失败;
  • 同步更新 openspec/specs/operations-audit 和 external-integration 中"每个入口都写审计"的要求。

5.8 应用日志增量与轮换(测试环境)

测试环境由 docker-compose.prod.yml 部署,api、worker 两个容器的现状:

  • 日志级别是 LEVEL=info、DEVELOPMENT=false,即 JSON 格式,可以按 "logger":"audit" 过滤;
  • 两个容器都把宿主机 ./logs 挂载到 /app/logs,且都没有设置 JUNHONG_LOGGING_APP_LOG_FILENAME,所以都使用默认的 /app/logs/app.log;
  • 轮换参数也是默认值:100 MB 一个文件、3 个备份、7 天、压缩。

问题:api 和 worker 写的是宿主机上同一个 /opt/junhong_cmp/logs/app.log。两个进程各自用 lumberjack 按大小轮换,会互相把对方正在写的文件改名、压缩,导致丢日志和备份错乱。这个问题与审计改造无关,但 L3 日志要落在 app.log 里,所以要一并修。

调整原则:每个服务写在自己运行目录下的 logs/。审计日志不新增路径、不改文件名,跟着所在进程的应用日志走。测试环境的问题只在于两个容器共用了同一个宿主机目录,所以只改挂载:

服务 挂载(宿主机 → 容器) 宿主机日志位置
api ./api/logs:/app/logs /opt/junhong_cmp/api/logs/app.log、access.log
worker ./worker/logs:/app/logs /opt/junhong_cmp/worker/logs/app.log
  • 容器内仍然是默认的 /app/logs/app.log,不设置 APP_LOG_FILENAME;目录结构与生产 /opt/junhong_cmp/api/logs、/opt/junhong_cmp/worker/logs 一致;

  • 轮换只加两项:JUNHONG_LOGGING_APP_LOG_MAX_BACKUPS=40、JUNHONG_LOGGING_APP_LOG_MAX_AGE=14,其余用默认值(100 MB、压缩);

  • 容量:两个进程合计约 1 GB,每个进程是 100 MB 当前文件加 40 个压缩备份。每个备份约 10 MB 是估算值,部署后按实际备份大小微调;

  • .gitea/workflows/deploy.yaml 里 mkdir -p ${DEPLOY_DIR}/logs 改为创建 api/logs、worker/logs;

  • 原来的 /opt/junhong_cmp/logs 不再写入,旧文件保留不动。

  • 新增量:方案 B 在测试环境移到 L3 的动作,每天约 8 万–10 万行:流量同步改由采集记录承担,不写日志;需要写日志的有网络状态同步约 2.5 万、优先轮询约 1.4 万、停机原因更新与通知若干。按每行约 400 B 计算,每天约 30–40 MB(压缩前),相对单文件 100 MB 没有压力。

文本日志是排查补充。丢几行不影响业务,也不影响审计表。写日志失败时不重试、不报错。

5.9 记录查询接口

审计里移出去的数据,要能在后台查得到,否则等于丢了。凡是独立成表的记录,都要提供分页 + 条件筛选的查询接口。L3 文本日志不提供接口,由日志同步服务器检索。

公共约定(与现有 ListStopResumeRecords 一致):

项 约定
分页 page 默认 1;page_size 默认 20,最大 100(采集记录沿用现有的最大 200);返回 total、page、page_size、items
时间范围 start_time、end_time 必填,跨度不超过 31 天,按上海时间解析;单卡接口为空时默认取最近 31 天
卡标识 identifier 支持虚拟号、ICCID、MSISDN,先解析成卡 ID 再查,保证走"卡 ID + 时间"索引;找不到卡时直接返回空页
排序 按记录时间倒序,同一时间按 ID 倒序
单个与全部 每类记录提供一个列表接口,identifier 选填:传了就查单卡或单资产,不传就查全部。现有的单卡接口保留给前端兼容,与列表接口共用同一个查询
筛选 按业务排查需要来定,下面逐表列出,不受现有索引限制;为这些筛选新建或重建索引
时间范围的作用 表按月分区,时间范围用于分区裁剪,所以查全部时也只带时间范围、不要求其他条件
权限 平台账号;代理和企业账号是否开放、按归属范围过滤,另行确定

接口清单:

记录 表 列表接口 筛选条件 现状
运营商流量采集记录(成功,失败见 5.10) tb_card_traffic_collection GET /traffic-collections identifier、carrier_id(运营商账户)、decision(扣减判定)、source、scene、has_delta(是否产生增量)、stale_guarded 只有单卡接口 GET /assets/:identifier/traffic-collections,只能按时间分页
停复机记录 tb_card_stop_resume_record GET /card-stop-resume-records identifier、carrier_id、action、source、scene、reason、result、error_category、command_id 已有跨卡接口,但只能用 ICCID 查卡,也不能按场景、原因、指令号筛选;单卡接口没有筛选
套餐日流量详单 tb_package_usage_daily_record GET /package-usage-daily-records identifier、package_usage_id、package_id、carrier_id、日期范围 只有单套餐接口 GET /package-usages/:id/daily-records,不分页
卡日流量 tb_card_daily_usage GET /card-daily-usages identifier、carrier_id、日期范围、min_usage_mb(用量下限,排查异常大流量) 无接口
套餐流量冲正流水 tb_package_usage_adjustment GET /package-traffic-adjustments identifier、package_usage_id、操作人、调整方向(补扣或退回)、时间范围 只有单套餐接口,没有时间筛选
对接日志 tb_integration_log 现有 GET /audit/integrations 现有条件已覆盖 不改
退款后处理尝试记录 tb_refund_post_process_attempt(见 5.5) GET /refund-post-process-attempts refund_id、退款单号、identifier、step、result、error_code、trigger、时间范围 新增。退款列表同时增加 asset_post_status 筛选(可查"需人工处理"),列表和详情返回后处理次数、最后错误、下次重试时间

索引:按上面的筛选设计,需要时新建或重建。分区表的索引建在父表上,会自动应用到各个分区。

表 索引
tb_card_traffic_collection 保留 (iot_card_id, observed_at DESC);新增冗余列 carrier_id,采集时写入;新增 (observed_at DESC)、(carrier_id, observed_at DESC)、(decision, observed_at DESC);失败表索引见 5.10
tb_card_stop_resume_record 现有 (card_id, created_at)、(carrier_id, created_at)、(result, created_at) 重建为倒序;新增 (created_at DESC)、(scene, created_at DESC)、(command_id)
tb_card_daily_usage 现有唯一键 (iot_card_id, date);新增 (date, usage_mb DESC),支撑查全部和按用量下限筛选
tb_package_usage_daily_record 新增 (package_usage_id, date DESC)、(date)
tb_package_usage_adjustment 新增 (iot_card_id, created_at DESC)、(created_at DESC)
tb_refund_post_process_attempt (refund_id, created_at DESC)、(created_at DESC)、(result, created_at DESC)、(error_code, created_at DESC)

其余低选择性的条件,如 source、stale_guarded、调整方向,和上面的索引组合使用即可,不单独建索引。上线后在测试环境看慢查询日志,按实际情况调整。

说明:

  • 流量扣减结果直接从采集记录查:每条采集记录都带 decision、delta_mb、month_used_mb、event_id,再结合日流量详单,能还原每次扣了多少。
  • 扣减效果表 tb_card_observation_effect 不对外提供接口。它只保存 outbox 事件的处理进度,没有卡 ID。排查扣减卡住时,在采集记录里按 event_id 关联查。
  • 新增接口都要在路由 RouteSpec 中声明输入、输出 DTO,并同步生成接口文档。

5.10 流量采集记录成功与失败分表

现状(测试库近 3 天,只读统计):

读数结果 扣减判定 条数 平均行大小
ok written(写入增量) 104.2 万 432 B
ok queue_not_full(队列未满,暂不判断) 17.3 万 285 B
ok slope_negative、baseline、settled_existing 800 约 420 B
failed — 14.5 万 136 B
no_reading — 400 144 B
  • 成功和失败写在同一张 tb_card_traffic_collection 里,失败约占 11%,测试环境每天约 4.8 万条。
  • 失败记录只存了失败类型。polling_carddata_handler 在调用 recordUnreadable 时丢掉了具体错误,查不到失败原因,只能再去对接日志里按 observation_id 找。
  • 失败记录也只给"采集时刻有套餐"的卡写,为此每条失败都要额外查一次有效套餐。

调整:

表 写什么 保留
tb_card_traffic_collection(现有) 只写成功读数(result=ok),包括所有扣减判定;新增原始请求与响应字段 在线保留 2 个月,到期月分区导出为压缩包后删除(见下文"到期归档")
tb_card_traffic_collection_failure(新增) 只写失败:failed、rate_limited、invalid_payload、no_reading、invalid_reading;带原始请求与响应 与成功表相同:在线 2 个月,到期归档后删除

失败表字段:iot_card_id、iccid、carrier_id、observed_at、observation_id(等于对接日志的 integration_id,可直接关联)、source、scene、result(失败类型)、error_category(按网关错误分类:超时、限流、上游报错、响应格式错等)、provider_code、provider_message(截断到 500 字)、duration_ms、created_at,加上下面的原始数据字段。按 observed_at 按月分区,只新增不修改。

原始数据:成功表和失败表都保存运营商网关的原始请求与原始响应,有据可查。

字段 内容
raw_request 加密前的业务请求体(明文 JSON,只有卡号等查询参数),jsonb
http_status HTTP 状态码;没拿到响应(超时、连接失败)时为空
gateway_code、gateway_msg、gateway_trace_id 网关响应外层的 code、msg、trace_id
raw_response 网关原始响应体,原样保存。能解析成 JSON 的存 jsonb,不能解析的按文本存在 raw_response_text。超过 4 KB 时截断,并标记 raw_truncated=true
gateway_attempts 网关客户端内部重试次数;保存的是最后一次的请求和响应
  • 获取方式:网关客户端(internal/gateway/client.go 的 executeWithRetry)已经读到了完整响应体和外层的 code、msg、trace_id,但只返回 data。新增按请求上下文挂载的原始数据收集器 gateway.WithRawCapture(ctx),调用方挂上后,客户端把最后一次的请求体、状态码、响应体和重试次数写进收集器。没挂收集器的调用不受影响。
  • 写入:polling_carddata_handler 调 QueryFlow 前挂上收集器,成功读数和各类失败都把收集器内容带进 TrafficObservation,写入对应的表。
  • 安全:只存明文业务请求体,不存加密后的报文、签名、app_id、密钥和请求头。
  • 量的估算:流量查询响应很小(iccid、used、unit 加外层字段,约 150–250 B),每行增加约 300–400 B。测试环境成功读数每天约 40 万条,每天增加约 120–160 MB;在线保留 2 个月,原始数据部分约 7–10 GB。失败每天约 4.8 万条,2 个月约 1 GB。部署后按实际行大小复核。

到期归档:

  • 在线保留:当月加上最近 2 个整月。月分区的月末早于"当前时间减 2 个月"时,判定为到期。例如 2027-01-01 起,2026-10 的分区到期。常量 TrafficCollectionRetentionDays=90 改为 TrafficCollectionRetentionMonths=2,成功表和失败表共用。
  • 执行位置:沿用 leader worker 现有的分区维护循环 startTrafficCollectionPartitionMaintainer,每 12 小时运行一次。原来"到期直接 DROP TABLE"的逻辑,改为下面的四步:
    1. 摘出分区:ALTER TABLE ... DETACH PARTITION,到期分区不再参与在线查询。
    2. 导出压缩包:用 COPY (SELECT * FROM 分区 ORDER BY observed_at, id) TO STDOUT WITH (FORMAT csv, HEADER) 流式读出,边读边 gzip 写到 worker 运行目录下的 archive/traffic-collection/ 目录,不在内存里攒整个月的数据。文件名为 tb_card_traffic_collection_202610.csv.gz 或 tb_card_traffic_collection_failure_202610.csv.gz。原始请求与响应以 JSON 文本形式保存在 CSV 列里。
    3. 校验:写完后重新读一遍压缩包,统计行数并与分区 count(*) 比对;同时生成同名的 .manifest.json,记录表名、月份、行数、最早和最晚采集时间、文件大小、SHA-256 和导出时间。
    4. 删除分区:行数一致后才 DROP TABLE 已摘出的分区。导出或校验失败时保留已摘出的表,记 Error 日志,下一轮重试;不会出现"数据删了但没有压缩包"的情况。
  • 文件同步:压缩包和 manifest 由你们的同步服务器拉走。本地只保留最近 3 个月的压缩包,更早的自动删除,个数可配置。先写成 .tmp,校验通过后再改名为正式文件名,避免同步到写了一半的文件。
  • 测试环境挂载:worker 容器增加 ./worker/archive:/app/archive,宿主机目录为 /opt/junhong_cmp/worker/archive/traffic-collection/。
  • 压缩包大小估算:测试环境成功表每月约 1,200 万行,CSV 约 8–10 GB,gzip 后约 1–1.5 GB;失败表每月约 150 万行,压缩后约 50 MB。
  • 回查:要查归档月份的数据,解压后用 CSV 工具查看,或者临时 COPY FROM 导回一张临时表。线上接口只查在线的 2 个月。

写入规则:

  • 失败记录不再判断是否有套餐,所有轮询到的卡都写,省掉每条失败的有效套餐查询。运营商接口出问题和有没有套餐无关,排查时需要看全量。
  • TrafficObservation 增加失败详情(错误类别、上游返回码与信息、耗时),由 polling_carddata_handler 在网关调用失败时填入,不再丢弃错误。
  • 成功表仍在观测事务之外写入,规则不变;写入失败只告警,不影响扣减。
  • 成功表已有的失败历史数据保留,到期随分区删除;新数据按新规则分表写入。

查询接口(与 5.9 公共约定一致:可查单个也可查全部,分页,时间范围必填):

接口 筛选条件 索引
GET /traffic-collections(成功) identifier、carrier_id、decision、source、scene、has_delta、stale_guarded 见 5.9
GET /traffic-collection-failures(失败) identifier、carrier_id、result、error_category、provider_code、source、scene (iot_card_id, observed_at DESC)、(observed_at DESC)、(carrier_id, observed_at DESC)、(error_category, observed_at DESC)、(observation_id)

成功表不再有失败数据,所以 5.9 里成功表的 result 筛选和 (result, observed_at DESC) 索引都去掉。单卡接口 GET /assets/:identifier/traffic-collections 增加 include_failures 参数,默认不含失败;传了就把两张表合并后按时间倒序返回,方便在一张卡上连起来看。

6. 存量数据

  • 不删除、不迁移已有审计数据,由现有留存和归档任务按策略自然过期。
  • 如果要尽快释放空间,可以另行评估"按动作编码清理机器过程类历史数据"的一次性任务。本方案不包含它。

7. 分支与范围

  • 基于 Iteration/8-11 实施。该分支已有 tb_card_stop_resume_record、采集记录和扣减效果表,方案 B 的补位表都存在。
  • 只部署测试环境:8-11 推送后自动部署到测试环境;不在生产执行任何代码替换、配置修改或服务重启。生产什么时候、以什么方式合入,不在本方案范围内。
  • 全局写入开关 add-audit-integration-write-switches 已在 8-11 上,本方案与它互不替代:全局开关用于应急全停,本方案是常态下的按动作分级。

8. 实施步骤

步骤 内容 涉及
1 注册表增加 Persist,补齐全部机器动作的策略,并加上 5.2 的默认规则 internal/infrastructure/audit/registry.go、pkg/constants/audit.go
2 Writer 按策略分流:outcome 只写最终结论;log_only 写现有应用日志(logger=audit) internal/infrastructure/audit/writer.go
3 对接日志去掉 attempt_started 补写 internal/infrastructure/integrationlog/repository.go
4 退款后处理加重试上限和退避,新增尝试记录表;停机业务性失败不重投,调用前被拦截的写 skipped 停复机记录 internal/service/refund、internal/service/iot_card、migrations
5 增加 audit.persist_overrides 运行时覆盖配置 pkg/config
6 审计覆盖扫描和 OpenSpec 规格同步 internal/governance/auditcoverage、openspec/specs
7 查询侧:卡、设备时间线合并停复机记录(方案 B) internal/query/audit
8 测试环境 api、worker 各自挂载自己的 logs/ 目录,轮换改为 40 个备份(见 5.8) docker-compose.prod.yml、.gitea/workflows/deploy.yaml
9 记录查询接口:每类记录一个列表接口,可查单个也可查全部;按 5.9 的筛选条件建立或重建索引;采集记录增加 carrier_id 冗余列 internal/routes、internal/handler/admin、internal/model/dto、internal/store/postgres、migrations
10 采集记录成功与失败分表:新增失败表,补全失败详情,失败不再判断有无套餐;两张表保存网关原始请求与响应(网关客户端新增原始数据收集器);提供失败查询接口(见 5.10) internal/gateway/client.go、internal/application/cardobservation、internal/task/polling_carddata_handler.go、internal/model、internal/store/postgres、migrations
11 采集记录到期归档:分区维护改为摘出、导出 csv.gz、校验、删除四步;测试环境 worker 挂载 archive 目录 internal/store/postgres/card_traffic_collection_store.go、cmd/worker/main.go、pkg/constants、docker-compose.prod.yml

建议按"1–3 → 4 → 5–11"分三次提交,每次推送 8-11 后在测试环境验证。

9. 测试与验证(测试环境)

测试环境逐项验证(项目规定自动化测试为 N/A,按 ENG-TEST-001 在测试环境验证,以下各项是验证要点):

  • 每种策略在 account、openapi、system_task 下的写入结果;

  • outcome:中间失败不写审计,尝试记录表每次都有一条;最终成功或转人工写一条审计,带总次数;同一件事重复写结论只保留一条;

  • log_only 不写表、文本日志有记录且不含快照;

  • 覆盖配置能把 always 降为 log_only,也能反过来恢复。

  • 对接调用没有上游审计时,tb_integration_log.audit_event_id 为空,审计表无新增;

  • 退款后处理失败超过上限后状态为"需人工处理",outbox 不再重投。

  • 流量查询成功写成功表、各类失败写失败表,两张表都带原始请求与响应;失败记录有错误类别和上游返回码;无套餐的卡失败也写;

  • 网关响应超过 4 KB 时截断并标记;原始请求里没有密钥、签名或加密报文;

  • 到期归档:构造一个过期月分区,执行维护后生成 csv.gz 和 manifest,行数与 SHA-256 一致后分区被删除;模拟导出失败时,已摘出的表保留,下一轮重试成功;

  • 记录查询接口:每个接口都能查单卡、也能查全部,分页总数正确,各筛选条件生效。

测试环境观察(部署后 24 小时):

  • 审计日增从约 12.6 万降到约 300 条(只读查询走 created_at 索引、按小时统计);
  • app.log 中出现 logger=audit 的行,轮换正常,日志同步服务器能收到并按 logger 名过滤;
  • 停复机记录、扣减效果写入量没有变化,业务结果没有变化;成功表加失败表的写入量合计,与改造前采集记录的量相当(失败表多出无套餐卡的失败);
  • 新接口在测试库数据量下没有慢查询;
  • /opt/junhong_cmp/worker/archive/traffic-collection/ 目录可写,同步服务器能拉到文件。第一次真实归档要等到在线数据满 2 个月之后,在此之前用单元测试和集成测试覆盖。

10. 已定事项(2026-11-05)

事项 结论
方案 方案 B
范围 基于 Iteration/8-11,只部署测试环境
L3 文本日志 写入所在服务自己运行目录下的 logs/app.log,沿用现有轮换,由日志同步服务器归集
测试环境日志保留 api、worker 各自的 logs/ 目录,各保留 40 个压缩备份,合计约 1 GB;部署后按实际备份大小微调
退款后处理重试上限 10 次,指数退避,最长间隔 1 小时;超过后标记"需人工处理"
失败记录 每次尝试都记录在业务尝试记录表(退款后处理尝试、停复机记录),可分页查询;审计只记最终结论,不按首次失败去重
停机业务性失败 按网关错误分类判定为不可重试,不再重投
运行时覆盖 提供 audit.persist_overrides,可按动作临时调整策略
存量审计数据 不删除、不迁移,按现有留存策略自然过期
采集记录分表 成功写现有表,失败写新表 tb_card_traffic_collection_failure,带完整错误详情,所有卡都写;两张表都保存网关原始请求与响应
采集记录保留 两张表在线保留 2 个月(当月加最近 2 个整月);到期月分区先导出为 csv.gz 压缩包并校验,再删除;压缩包由同步服务器拉走,本地保留 3 个月
记录查询 所有独立成表的记录都提供分页加条件筛选接口,可查单个也可查全部;筛选条件按排查需要来定,索引随之新建或重建,清单见 5.9;文本日志不提供接口
页面依赖 实施第 7 步(时间线合并停复机记录)前,与前端或运营确认是否有页面依赖机器动作审计