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,2 @@
schema: spec-driven
created: 2026-11-06

View File

@@ -0,0 +1,114 @@
## Context
依据 `docs/2026-11-06-轮询入库异步化技术方案.md`。按运营商账户调度上线后,测试环境 worker 实测同时处理约 380 个任务(理论上限约 1,290:卡轮询 41 × 20、停复机 41 × 10、设备评估 10、异步任务队列 50),共用 `MAX_OPEN_CONNS=60` 的连接池。每个轮询步骤在同一个任务里先调网关、再同步写库,写库计入步骤超时;结果是每小时约 8,000 次 SQL 超时、13.8 万条慢查询告警、采集记录因 3 秒写超时丢失。
现状(流量步骤):读优先项 → 清缓存后查卡 → 范围校验查库 → 调网关 → `ApplyTrafficObservation`(Redis 队列 Push + 事务:锁卡、查套餐、写快照、更新卡、outbox、通道阈值、审计)→ 写采集记录(3s)→ 对接日志、优先项完成 → 返回 `TriggeredEvaluation`。卡状态、实名步骤结构相同。
约束:基于 `Iteration/8-11`,只部署测试环境;测试环境网关只读开关保持开启;不改计量与扣减业务规则。
## Goals / Non-Goals
**Goals:**
- 调网关的并发继续按账户控制;入库并发固定、可配置,与账户数无关。
- 入库不丢、不重复算,乱序安全。
- 轮询步骤调网关前的读查询基本不碰数据库。
- 一键回退到同步入库;nsqd 故障时自动降级。
**Non-Goals:**
- 死信表与重放接口(本期不做)。
- 调整按账户调度参数、网关限流规则。
- 生产环境发布。
- 人工刷新、运营商回调、激活前结算、观测序列的异步化。
## Decisions
### D1 入库拆到单独的 NSQ topic,而不是给卡任务加全局并发上限
备选:在卡任务消费者上加一个全局信号量。拒绝原因:卡任务里既有网关等待又有写库,全局上限会同时压低网关吞吐;而网关并发本来就由账户限流控制。拆开后网关侧按账户并发,数据库侧固定 30 并发,两种瓶颈各自控制。
### D2 入库复用现有 `Apply*Observation`
入库消费者把消息还原为 `domain.TrafficObservation` / `NetworkObservation` / `RealnameObservation` 后调用现有应用服务,计量、扣减、通道阈值、审计逻辑不复制、不改写。同步路径与异步路径共用一套业务代码,`polling.ingest.mode=sync` 时轮询步骤直接调用同一函数。
### D3 消息格式
`card.ingest` 一条消息一次观测,JSON,字段见规格。`observed_at` 取网关返回时刻,入库全程使用它,保证延迟入库不改变日期归属。网关原始数据按现有截断规则(4KB)在发布前截断,单条约 2KB。
### D4 重试用 NSQ 延迟重投、不限次数
入库失败按错误分类:可重试错误(数据库超时、连接错误、锁等待超时、`context deadline exceeded`)调用 `msg.RequeueWithoutBackoff(delay)`,延迟按 `attempts` 取 5s/15s/30s/1m/2m/5m…;消费者 `MaxAttempts=0`(不限)。nsqd `--max-msg-timeout=15m` 已满足最大 5 分钟延迟。业务性错误(`CodeNotFound`、校验失败)FIN 并记 WARN。第 10 次起每次重投记 ERROR。
卡任务的业务重试仍由 Redis score 表达(现有要求),入库 topic 与卡任务 topic 互不影响。
### D5 幂等
- 处理前查 Redis `ingest:done:<observation_id>`,存在即 FIN;事务提交后 `SET … EX 48h`。
- 事务已提交但标记未写入时的重放:日快照取当日最大、增量按"本月最大 − 已结算"得 0;outbox 按 `event_id` `ON CONFLICT DO NOTHING`(已核对 `internal/infrastructure/messaging/outbox/repository.go:103`);采集记录唯一索引兜底。
- 采集队列 Lua 增加同 `observed_at` 去重,防止重放时同一点进队两次影响判断。
### D6 网络、实名观测的乱序保护
现有 `ApplyNetworkObservation`、`ApplyCardObservation` 没有比较采集时间。新增:事务内锁卡后,若 `observed_at` 早于卡上 `last_card_status_check_at` / `last_real_name_check_at`,不改状态、不写事件,只确认消息并记 INFO。同步入口也走同一判断,行为一致。
### D7 采集记录走 `card.collection` 批量写
成功记录在入库事务提交后发布;网关失败、无读数的失败记录由轮询步骤直接发布。批量消费者 `max_in_flight=500`,内存缓冲按 `batch_size=200` 或 1 秒刷写,多行 `INSERT … ON CONFLICT DO NOTHING`,成功统一 FIN、失败统一 `Requeue`。写库并发 1。唯一索引 `(observation_id, observed_at)`,`observed_at` 为分区键,满足分区表唯一索引要求。删除 `collectionRecordTimeout` 与"写失败只记告警"。
### D8 收尾动作的归属
| 原位置(步骤内) | 异步后 |
|---|---|
| 优先项完成、对接日志"业务事实发生变化" | 本轮认领了优先项的观测保持同步入库,沿用原逻辑;普通轮询本来就不写对接日志 |
| `StopPolling` → `removeCard` | 步骤按网关结果(`ShouldStopPollingForRisk`)直接返回停止轮询;入库段写库时关闭卡轮询开关 |
| 延迟确认的观测值 | 步骤按网关状态映射(`MapGatewayNetworkStatus`)得出 |
| `TriggeredEvaluation` 跳过套餐步骤 | 入库段写 Redis `flow_evaluated:<card_id>`,TTL = 套餐检查间隔;套餐步骤读取 |
理由:优先项需要"本轮写库后完成"的语义,且量很小(测试环境十几分钟几条),保持同步比在入库段重建优先项轮次简单可靠。停止轮询与延迟确认只依赖网关结果,不需要等入库。
步骤结果在网关成功、消息发布成功时即为成功,写回下次到期时间;入库失败不影响该卡调度退避。
### D9 读查询缓存
- 卡信息:步骤不再"先清缓存再查库",改读 Redis 卡缓存;入库段事务提交后失效缓存(现有 `cache.Invalidate`)。
- 优先项:Redis 集合 `polling:priority:active`(成员 `card_id:task_type`),优先项提示下发时加入;leader 每 30 秒按库内活动项重建(并入 2 分钟内新入队的项),就绪标记存在且不在集合中时不查库,否则回退查库。
- 运营商实名开关(已有)、重置日:进程内缓存 1 分钟,重置日读取失败不缓存。
- 设备轮询开关与绑定关系:卡任务的范围校验结果按卡进程内缓存 30 秒;卡自身轮询开关仍实时判断,生命周期事件仍实时校验。
- `lazyTierFacts`:3 秒总超时改为每次查询单独 2 秒;`Prefill` 查询失败的卡不写缓存。
### D10 积压监控与反压
worker leader 每分钟请求 nsqd `/stats?format=json&topic=…`,取 topic 未分发量与 channel 待消费量、延迟重投量之和作为积压,等待时间取 leader 进程内最近处理消息的 `now − published_at`,写 INFO 指标;超过 `alert_depth`(默认 200,000)或等待 > 10 分钟写 ERROR。超过 `pause_depth`(默认 500,000)时在 Redis 置 `polling:ingest:paused`,分发器每轮检查,置位时不领取新卡;低于一半时清除。
### D11 同步回退与降级
`polling.ingest.mode` 放系统配置(5 秒进程缓存),默认 `sync`,部署后确认无误再切 `async`。采集记录不论模式都经 `card.collection` 写入(nsqd 不可用时同步写)。`sync` 时步骤直接调用 `Apply*Observation` 并同步写采集记录(采集记录仍可发 `card.collection`;nsqd 不可用时同步写)。异步模式发布失败时,该次观测降级为同步入库并记 WARN。
### D12 连接预算检查
启动时:`ingest.concurrency + 1(采集记录) ≤ MAX_OPEN_CONNS − 20`,否则 ERROR(不阻止启动)。测试环境 30 + 1 ≤ 40。
### D13 nsqd 落盘
测试环境 `docker-compose.prod.yml` nsqd 参数改 `--mem-queue-size=0`,所有 topic 写 `./nsq-data`。每秒几十条消息,磁盘写入可忽略;积压 50 万条约 1GB。
## Risks / Trade-offs
- [入库延迟使后台数据晚几秒] → 常态目标等待 < 30 秒;积压告警覆盖异常。
- [停复机、通道阈值判断晚几秒] → 判断逻辑不变,只是触发时间后移;与网关调用间隔相比可接受。
- [不做死信,坏消息无限重试] → 业务性错误直接丢弃;可重试错误第 10 次起 ERROR 告警,积压告警兜底;需要时后续加死信。
- [乱序保护改变同步入口行为] → 只拦"比已应用观测更旧"的状态变化,同步入口原本也不应接受更旧的观测。
- [卡缓存陈旧导致轮询范围判断滞后] → 入库段与停复机、轮询开关修改均失效缓存;缓存 TTL 保持现有值。
- [nsqd 全落盘性能] → 当前量级每秒几十条,远低于 nsqd 磁盘队列能力。
- [一张卡的写入跨两个消费者,排查变复杂] → 日志统一带 `observation_id`、`card_id`。
## Migration Plan
1. 部署含新代码的镜像,`polling.ingest.mode` 默认 `sync`,确认行为不变(采集记录已改经 `card.collection` 写入)。
2. 执行采集记录唯一索引迁移(测试库,用户授权后执行)。
3. nsqd 改 `--mem-queue-size=0` 并重启 nsqd。
4. 系统配置切 `async`,观察 1 小时:SQL 超时数、慢查询数、积压、采集记录对账。
5. 回退:系统配置切 `sync`,已在队列中的消息继续被消费完。
## Open Questions
- 无。2026-11-06 已定:入库并发 30;nsqd `--mem-queue-size=0`;不做死信;告警 200,000 / 反压 500,000。

View File

@@ -0,0 +1,39 @@
## Why
测试环境 worker 每小时约 8,000 次 SQL `context deadline exceeded`、13.8 万条慢查询告警,采集记录因 3 秒写超时持续丢失。根因是按运营商账户调度的 NSQ 消费者只有"每账户上限"(41 个账户 × 20 = 820),没有总量上限,而每个轮询步骤在同一个任务里先调网关再同步写库,三百多个任务争抢 60 个数据库连接。依据 `docs/2026-11-06-轮询入库异步化技术方案.md`,把"调上游"与"入库"拆开:调网关继续按账户并发,入库单独发消息、由固定并发的消费者处理。
## What Changes
- 轮询的卡状态、流量、实名步骤只做"读缓存 → 调网关 → 发入库消息",不在卡任务内写库;步骤结果只反映网关调用是否成功。
- 新增 NSQ topic `card.ingest` 与入库消费者,并发固定(默认 30),与账户数量无关;入库复用现有 `ApplyTrafficObservation`、`ApplyNetworkObservation`、`ApplyCardObservation`。
- 入库可重试错误按退避不限次数重试、不丢弃;业务性错误记 WARN 后丢弃;本期不做死信。
- 入库幂等与顺序:按 `observation_id` 去重;采集队列按采集时间去重;网络、实名观测"更新的才生效";采集记录唯一索引。
- 新增 NSQ topic `card.collection` 与批量消费者,攒批写采集成功表、失败表;删除采集记录 3 秒写超时与"写失败只记告警"。
- 优先轮询项完成、对接日志"业务事实发生变化"、网络观测导致的停止轮询、套餐步骤跳过标记移到入库段。
- 轮询步骤调网关前的读查询走缓存(卡信息、优先项、运营商开关、绑定关系);配置匹配查套餐状态每次查询单独计时,失败不缓存"未知"。
- 入库积压监控:积压超过 20 万条告警,超过 50 万条调度器暂停派发新卡任务,降到一半以下恢复。
- 系统配置 `polling.ingest.mode`(`async` / `sync`)一键回退;发消息失败时降级为同步入库。
- 测试环境 nsqd 改为 `--mem-queue-size=0`,消息全部落盘。
- 后台人工刷新、运营商回调、激活前结算、观测序列保持同步入库。
- 不在本 Change:死信表与重放、生产环境发布、按账户调度参数调整。
## Capabilities
### New Capabilities
- `polling-async-ingest`:轮询观测入库消息、入库消费者并发与重试、幂等与顺序、采集记录批量写、积压告警与反压、同步回退与降级。
### Modified Capabilities
- `carrier-polling-scheduler`:卡任务的检查步骤改为只调网关并发入库消息;套餐步骤跳过依据改为入库段写的流量评估标记。
- `card-traffic-metering`:采集记录写入改为经消息批量写、失败重试不丢,替代"写入失败只记告警"。
## Impact
- 前置:`add-carrier-polling-scheduler`、`add-card-traffic-queue-and-observed-deduction`、`refactor-audit-log-persistence` 须先归档(本 Change 修改它们新增或修改的要求)。
- 代码:`internal/task/polling_carddata_handler.go`、`polling_cardstatus_handler.go`、`polling_realname_handler.go`、`carrier_card_executor.go`、`polling_priority_claim.go`;`internal/application/cardobservation/`(`traffic.go`、`traffic_collection.go`、`network.go`、`apply.go`);`internal/polling/config_manager.go`、`tier.go`;采集队列 Lua;新增入库消费者、采集记录批量消费者与积压监控;`cmd/worker/carrier_scheduler.go`、`internal/polling/carrierqueue/dispatcher.go`(反压)。
- 数据库:采集成功表、失败表新增 `(observation_id, observed_at)` 唯一索引(成对迁移)。
- 配置:系统配置 `polling.ingest.mode`、`polling.ingest.alert_depth`、`polling.ingest.pause_depth`;启动配置 `polling.ingest.concurrency`、`polling.ingest.timeout`、`polling.collection.batch_size`。
- Redis:`ingest:done:<observation_id>`(TTL 48h)、`flow_evaluated:<card_id>`、有活动优先项的卡集合。
- 部署:`docker-compose.prod.yml` 中 nsqd 改 `--mem-queue-size=0`。
- 范围:基于 `Iteration/8-11`,只部署测试环境。

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

View File

@@ -0,0 +1,70 @@
## 1. 幂等与乱序基础
- [x] 1.1 采集队列 Lua 按 `observed_at` 去重(现有 Lua 已按同一采集时间去重,无需改动)
- [x] 1.2 `ApplyNetworkObservation` 增加采集时间早于 `last_card_status_check_at` 时不改状态的保护
- [x] 1.3 `ApplyCardObservation` 增加采集时间早于 `last_real_name_check_at` 时不改状态的保护
- [x] 1.4 迁移:采集成功表、失败表新增 `(observation_id, observed_at)` 唯一索引(成对 up/down)
## 2. 配置
- [x] 2.1 启动配置 `polling.ingest.concurrency`(30)、`polling.ingest.timeout`(30s)、`polling.collection.batch_size`(200),含默认值、环境变量与校验
- [x] 2.2 系统配置 `polling.ingest.mode`(async/sync)、`polling.ingest.alert_depth`(200000)、`polling.ingest.pause_depth`(500000,须大于告警阈值)
- [x] 2.3 启动连接预算检查:入库并发 + 1 > `MAX_OPEN_CONNS` − 20 时记 ERROR
## 3. 采集记录批量写
- [x] 3.1 定义 `card.collection` 消息与发布器(成功、失败两种记录)
- [x] 3.2 批量消费者:缓冲按 200 条或 1 秒刷写,多行 INSERT `ON CONFLICT DO NOTHING`,成功统一 FIN、失败统一重投
- [x] 3.3 `ApplyTrafficObservation` 采集记录改为发布消息,发布失败同步写;删除 `collectionRecordTimeout` 与"写失败只记告警"
- [ ] 3.4 测试环境验证:攒批、整批失败重投、重复记录忽略(项目自动化测试为 N/A,按 ENG-TEST-001 在测试环境验证)
## 4. 入库消息与消费者
- [x] 4.1 定义 `card.ingest` 消息(三种观测、原始数据、优先项、发布时间)与编解码,补测试
- [x] 4.2 入库消费者:已处理标记检查、按类型调用 `Apply*Observation`、成功写标记(48h)
- [x] 4.3 错误分类与重投:可重试错误按 5s/15s/30s/1m/2m/5m 延迟重投、不限次数,第 10 次起记 ERROR;业务性错误记 WARN 后 FIN
- [x] 4.4 收尾归属:优先执行保持同步入库(优先项完成、对接日志沿用原逻辑);`StopPolling` 由步骤按网关结果移出调度;入库段写 `flow_evaluated:<card_id>`
- [x] 4.5 在 `cmd/worker/carrier_scheduler.go` 注册入库与采集记录消费者(`MaxAttempts=0`),随 worker 优雅退出
- [ ] 4.6 测试环境验证:重复投递、提交后未写标记重放、卡不存在、可重试错误重投
## 5. 轮询步骤改造
- [x] 5.1 流量步骤:异步模式下网关成功后发布入库消息即成功返回;网关失败直接发布采集失败记录
- [x] 5.2 卡状态步骤、实名步骤:异步模式下发布入库消息
- [x] 5.3 发布失败降级为同步入库并记 WARN;`sync` 模式走原逻辑
- [x] 5.4 套餐步骤跳过依据改为读 `flow_evaluated:<card_id>`
- [ ] 5.5 测试环境验证:异步成功、发布失败降级、同步模式行为不变、套餐步骤跳过
## 6. 读查询缓存
- [x] 6.1 步骤读卡改为读卡缓存(去掉每步先清缓存再查库);入库段提交后失效缓存
- [x] 6.2 有活动优先项的卡集合:入队加、终态删、启动全量重建;步骤先查集合
- [x] 6.3 运营商实名开关、重置日进程内缓存 1 分钟;设备轮询开关与绑定关系并入卡缓存
- [x] 6.4 `lazyTierFacts` 每次查询单独计时;`Prefill` 失败的卡不写缓存
## 7. 积压监控与反压
- [x] 7.1 leader 每分钟读 nsqd stats,记录 `card.ingest`、`card.collection` 积压与最老等待时间
- [x] 7.2 超过告警阈值或等待 > 10 分钟记 ERROR
- [x] 7.3 超过反压阈值置暂停标记,分发器暂停领取新卡;低于一半恢复
## 8. 部署(测试环境)
- [x] 8.1 `docker-compose.prod.yml` nsqd 参数改 `--mem-queue-size=0`
- [ ] 8.2 `go build ./...`、相关包测试、OpenSpec `--strict` 校验通过
- [ ] 8.3 提交并推送 `Iteration/8-11`(自动部署测试环境),`polling.ingest.mode` 先保持 `sync`
- [ ] 8.4 测试库执行唯一索引迁移(用户授权后)
## 9. 测试环境验证
- [ ] 9.1 切 `async` 后 1 小时:`context deadline exceeded` 从每小时约 8,000 次降到个位数
- [ ] 9.2 慢查询告警与 worker 日志量明显下降
- [ ] 9.3 采集记录对账:入库消息数 = 成功表 + 失败表新增行数
- [ ] 9.4 抽样卡日快照、扣减与同步模式一致;重投与乱序不重复扣减
- [ ] 9.5 `card.ingest` 常态等待 < 30 秒
- [ ] 9.6 切回 `sync` 行为恢复;停 nsqd 时步骤降级同步入库
- [ ] 9.7 nsqd 重启后未处理消息继续消费
## 10. 归档
- [ ] 10.1 `add-carrier-polling-scheduler`、`add-card-traffic-queue-and-observed-deduction`、`refactor-audit-log-persistence` 归档后再归档本 Change