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