feat: 审计动作按落库策略分级写入,系统过程动作改写应用日志
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 12m8s
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:
440
docs/2026-11-05-审计日志写入改造技术方案.md
Normal file
440
docs/2026-11-05-审计日志写入改造技术方案.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# 审计日志写入改造技术方案
|
||||
|
||||
> 日期: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` 新增字段:
|
||||
|
||||
```go
|
||||
// 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`,在注册校验通过后、组装事件前分流:
|
||||
|
||||
```go
|
||||
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 步(时间线合并停复机记录)前,与前端或运营确认是否有页面依赖机器动作审计 |
|
||||
Reference in New Issue
Block a user