Files
邹进 1214181e78
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 16m2s
feat: 轮询观测入库异步化,调网关与入库分离,采集记录经消息攒批写入
- 轮询步骤异步模式下只调网关并发布 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>
2026-11-06 16:33:29 +09:00

8.3 KiB
Raw Permalink Blame History

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 条消息继续被入库消费者处理