feat: 轮询观测入库异步化,调网关与入库分离,采集记录经消息攒批写入
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s

- 轮询步骤异步模式下只调网关并发布 card.ingest 入库消息,入库消费者固定并发 30、按采集 ID 去重、可重试错误不限次数退避重投
- 采集记录经 card.collection 攒批写入,失败整批重投,新增 (observation_id, observed_at) 唯一索引
- 网络、实名观测增加乱序保护;轮询读查询走缓存,套餐状态查询各自计时且失败不缓存
- 入库积压告警与反压;系统配置 polling.ingest.mode 默认 sync 可回退;测试环境 nsqd 消息全部落盘

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
邹进
2026-11-06 16:33:29 +09:00
parent 7e0e37933e
commit 1214181e78
41 changed files with 2007 additions and 46 deletions

View File

@@ -0,0 +1,67 @@
## 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 随流量事件与扣费审计传递,使扣费可追溯到对应采集记录。
- 采集记录 SHALL 经 `card.collection` 消息由批量消费者写入;写入失败 MUST 重投重试、不丢弃,且不影响扣减与卡状态。
- 同一采集 ID 与采集时间的记录 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** 记录中不含加密报文、签名、应用标识与密钥
#### Scenario: 采集记录写库失败
- **WHEN** 批量写采集记录时数据库超时
- **THEN** 这一批消息重投后重新写入,记录不丢失,卡的扣减与状态不受影响
#### Scenario: 采集记录重复投递
- **WHEN** 同一条采集记录消息被投递两次
- **THEN** 表中只保留一条该采集 ID 的记录

View File

@@ -0,0 +1,27 @@
## MODIFIED Requirements
### Requirement: 卡任务串行执行检查步骤
系统 SHALL 对一张卡的一个卡任务按配置的步骤顺序(默认卡状态 → 流量 → 实名 → 套餐)串行执行本次已到期的检查类型。每步 MUST 有单独超时;某步失败只影响该步,后续步骤照常执行;限流等待超时时该步按短延迟重排且不计失败。卡任务总时长 MUST 不超过各步超时之和加余量,到达后取消剩余步骤并按失败收尾。同一张卡的不同检查类型 MUST NOT 并行执行。
入库模式为异步时,卡状态、流量、实名步骤 SHALL 只读取缓存、调用网关并发布入库消息,MUST NOT 在卡任务内写观测结果;步骤结果只反映网关调用是否成功,入库成败不计入该步的失败与退避。网关未返回有效结果的采集,步骤 SHALL 直接发布采集失败记录消息。套餐步骤 SHALL 依据入库段写入的流量评估标记决定是否跳过:标记存在时本轮套餐步骤按成功跳过。
#### Scenario: 流量步骤失败
- **WHEN** 卡任务中流量查询超时
- **THEN** 实名、套餐步骤照常执行,流量按退避间隔重试
#### Scenario: 同卡不同类型
- **WHEN** 卡的状态检查与流量检查同时到期
- **THEN** 系统在同一个卡任务中先查状态再查流量,不并行发起
#### Scenario: 网关成功后只发消息
- **WHEN** 入库模式为异步,流量步骤拿到有效网关响应
- **THEN** 步骤发布一条流量入库消息后按成功结束,不在卡任务内写日快照与采集记录
#### Scenario: 入库失败不影响步骤退避
- **WHEN** 网关调用成功,但该消息入库时数据库超时
- **THEN** 该卡的流量检查按成功计算下次到期时间,入库由入库消费者重试
#### Scenario: 流量已触发评估时跳过套餐步骤
- **WHEN** 入库段处理流量消息后产生了流量增量并写入流量评估标记,标记有效期内该卡套餐检查到期
- **THEN** 本轮套餐步骤按成功跳过

View File

@@ -0,0 +1,131 @@
## ADDED Requirements
### Requirement: 轮询观测经消息入库
入库模式为异步时,系统 SHALL 把轮询的卡状态、流量、实名观测发布到 NSQ topic `card.ingest`,由入库消费者调用现有观测应用逻辑写库。消息 MUST 包含观测类型、卡 ID、运营商账户、ICCID、采集 ID、采集时间(网关返回时刻)、来源、场景、关联 ID、观测内容、网关原始数据、本轮认领的优先轮询项与发布时间。后台人工刷新、运营商回调、激活前结算与观测序列 MUST 保持同步入库。
#### Scenario: 流量观测入库
- **WHEN** 入库消费者收到一条流量入库消息
- **THEN** 系统按消息中的采集时间执行采集队列判断、日快照、扣减事件与通道阈值判断,结果与同步入库一致
#### Scenario: 人工刷新保持同步
- **WHEN** 后台人工刷新一张卡的流量
- **THEN** 系统同步写库并在接口中返回本次读数与写入结果,不经过入库消息
### Requirement: 入库消费者并发上限
系统 SHALL 以单独的消费者处理 `card.ingest`,每进程并发由启动配置 `polling.ingest.concurrency` 决定,默认 30,与运营商账户数量无关。单条消息的入库超时 SHALL 从消费者开始处理该消息时计时,默认 30 秒。启动时,入库并发与采集记录写并发之和 MUST 不超过数据库最大连接数减 20,超过时记录 ERROR。
#### Scenario: 账户增加不增加入库并发
- **WHEN** 运营商账户从 41 个增加到 60 个
- **THEN** 入库消费者同时处理的消息数仍不超过 30
#### Scenario: 并发配置超出连接预算
- **WHEN** 数据库最大连接数为 60,入库并发配置为 50
- **THEN** worker 启动时记录 ERROR,指出入库并发超出连接预算
### Requirement: 入库失败重试
入库遇到可重试错误(数据库超时、连接错误、锁等待超时)时,系统 SHALL 让 NSQ 延迟重投,退避依次为 5 秒、15 秒、30 秒、1 分钟、2 分钟,之后每 5 分钟一次,MUST NOT 设次数上限或丢弃消息。第 10 次及以后的每次重投 SHALL 记录 ERROR,包含采集 ID、卡 ID 与错误。业务性错误(卡不存在、观测数据校验失败)MUST NOT 重投,记录 WARN 后确认消息。本期不提供死信表。
#### Scenario: 数据库超时后重试成功
- **WHEN** 一条流量入库消息因数据库超时失败
- **THEN** 该消息 5 秒后重投,再次处理成功后写入日快照
#### Scenario: 长时间失败
- **WHEN** 一条消息连续失败到第 10 次
- **THEN** 系统记录 ERROR 并继续每 5 分钟重投,不丢弃
#### Scenario: 卡已删除
- **WHEN** 入库时卡不存在
- **THEN** 系统记录 WARN 并确认消息,不再重投
### Requirement: 入库幂等与顺序
系统 SHALL 保证入库消息乱序、重复投递时结果正确:
- 入库成功后 SHALL 写入以采集 ID 为键的已处理标记(保留 48 小时);处理前发现已处理标记 MUST 直接确认消息。
- 采集队列 MUST 按采集时间去重,同一采集时间的点只保留一个。
- 晚到的旧流量观测按采集队列规则不在队尾时 MUST NOT 写日快照。
- 网络状态与实名观测 MUST 只在采集时间晚于卡上最近一次已应用的同类观测时才改变卡状态。
- 流量事件按采集 ID 生成稳定事件 ID,重复写入 MUST 被忽略。
#### Scenario: 同一消息投递两次
- **WHEN** 一条已入库成功的流量消息被再次投递
- **THEN** 系统发现已处理标记,直接确认,不重复扣减
#### Scenario: 提交后未写标记即崩溃
- **WHEN** 入库事务已提交、写已处理标记前进程退出,消息被重投
- **THEN** 重放不产生新的流量增量,流量事件不重复,采集记录只保留一条
#### Scenario: 网络状态乱序
- **WHEN** 采集时间 10:00 的"停机"观测晚于 10:05 的"正常"观测到达
- **THEN** 卡状态保持 10:05 的"正常"
### Requirement: 入库段收尾动作
入库成功后,流量入库产生增量或跨月时,系统 SHALL 写入该卡的流量评估标记,有效期等于该卡的套餐检查间隔。本轮同时是优先执行(认领了优先轮询项)的观测 MUST 保持在卡任务内同步入库,优先项的完成与对接日志沿用原逻辑。网络观测命中风险停机或已销户时,卡任务 SHALL 按网关结果直接停止该卡轮询,入库段写库时关闭卡的轮询开关。
#### Scenario: 加急轮询保持同步
- **WHEN** 异步模式下一张卡的流量步骤认领了优先轮询项
- **THEN** 该次观测在卡任务内同步入库,入库成功后优先项被标记为完成
#### Scenario: 卡销户停止轮询
- **WHEN** 异步模式下网络步骤查到卡已销户
- **THEN** 卡任务把该卡移出运营商账户调度队列,入库段写库时把卡的轮询开关置为关闭
### Requirement: 采集记录批量写入
Worker 配置了 nsqd 时,系统 SHALL 不论入库模式,把采集成功记录与采集失败记录发布到 NSQ topic `card.collection`,由批量消费者写入采集成功表与失败表。批量消费者 SHALL 攒满 `polling.collection.batch_size`(默认 200)条或等待满 1 秒时写一次,写成功后统一确认,写失败时整批重投。成功表与失败表 MUST 以采集 ID 与采集时间建唯一索引,重复记录忽略。
#### Scenario: 攒批写入
- **WHEN** 1 秒内收到 150 条采集记录消息
- **THEN** 系统在 1 秒到达时一次写入这 150 条
#### Scenario: 网关失败直接写失败记录
- **WHEN** 轮询步骤查流量时网关超时
- **THEN** 步骤直接发布采集失败记录消息,不经过入库消费者
### Requirement: 轮询读查询走缓存
入库模式为异步时,轮询步骤调网关前 SHALL 从缓存读取卡信息、运营商实名开关与重置日、设备轮询开关与绑定关系;优先轮询项 SHALL 先查"有活动优先项的卡"集合,不在集合中时 MUST NOT 查库。配置匹配查询套餐状态时,每次查询 SHALL 单独计时;查询失败 MUST NOT 把"未知"写入缓存。
#### Scenario: 无优先项的卡
- **WHEN** 一张没有活动优先项的卡执行流量步骤
- **THEN** 系统不查询优先轮询项表
#### Scenario: 套餐状态查询失败
- **WHEN** 配置匹配查询某卡套餐状态超时
- **THEN** 本次按未知处理,缓存中不写入该卡结果,下次重新查询
### Requirement: 入库积压告警与反压
系统 SHALL 每分钟读取 `card.ingest` 与 `card.collection` 的积压量与最老消息等待时间并记录。积压量超过系统配置 `polling.ingest.alert_depth`(默认 200,000)或最老消息等待超过 10 分钟时 SHALL 记录 ERROR 告警。`card.ingest` 积压量超过 `polling.ingest.pause_depth`(默认 500,000)时,调度器 SHALL 暂停派发新的卡任务,积压降到该阈值一半以下时恢复。反压阈值 MUST 大于告警阈值。
#### Scenario: 积压告警
- **WHEN** `card.ingest` 积压达到 200,001 条
- **THEN** 系统记录 ERROR 告警,包含积压量与最老消息等待时间
#### Scenario: 反压暂停与恢复
- **WHEN** `card.ingest` 积压超过 500,000 条
- **THEN** 调度器暂停派发新卡任务,积压降到 250,000 条以下后恢复派发
### Requirement: 同步回退与发布失败降级
系统 SHALL 提供系统配置 `polling.ingest.mode`,取值 `async` 或 `sync`,默认 `sync`,修改后数秒内生效;为 `sync` 时轮询步骤 MUST 恢复在卡任务内同步入库。异步模式下发布入库消息或采集记录消息失败时,轮询步骤 SHALL 改为同步入库并记录 WARN,MUST NOT 丢弃本次观测。
#### Scenario: 切回同步
- **WHEN** 运维把 `polling.ingest.mode` 改为 `sync`
- **THEN** 之后的轮询步骤在卡任务内同步写库,已在队列中的入库消息继续由入库消费者处理
#### Scenario: nsqd 不可用
- **WHEN** 发布流量入库消息时 nsqd 连接失败
- **THEN** 该步骤同步执行入库并记录 WARN
### Requirement: 入库消息持久化
测试环境 nsqd SHALL 以 `--mem-queue-size=0` 运行,所有 topic 的消息直接写入磁盘数据目录,nsqd 重启后未确认的消息 MUST 仍可被消费。
#### Scenario: nsqd 重启
- **WHEN** `card.ingest` 有 1,000 条未处理消息时 nsqd 容器重启
- **THEN** 重启后这 1,000 条消息继续被入库消费者处理