feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s

- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
This commit is contained in:
邹进
2026-10-24 15:06:41 +09:00
parent 9e45097aa2
commit 42e881576d
106 changed files with 7173 additions and 48 deletions

View File

@@ -0,0 +1,2 @@
schema: spec-driven
created: 2026-10-24

View File

@@ -0,0 +1,42 @@
## Context
完整设计见 `docs/engineering/轮询按运营商账户限流技术方案.md` 第三部分第 1~5.1、7.2~7.6、8、9、14 节。本文记录实现决策。
现状:`internal/polling/scheduler.go` 每秒对 16 个分片 × 5 类型 Lua 出队后逐条 `Enqueue` 到 Asynq(`MaxRetry(0)`、无 TaskID);按 ZCARD 背压(50 万);`polling_base.go` 全局 + 类型并发令牌;优先提示 List `polling:priority:{taskType}` 与手动触发 List;`OnCardStatusChanged` 重新入队全部类型;业务事件经 Outbox `AppendSeriesRequested` 创建"立即、3 分钟、5 分钟"观测序列,读入口经 `BestEffortSeriesDispatcher`(C 端资产详情、后台资产实时状态、C 端与后台实名链接;OpenAPI 不触发)。Redis 单节点;仓库无 NSQ 依赖;自动化测试为 N/A。生产 98,430 张卡、89,962 张开启轮询、37 个运营商账户。
## Goals / Non-Goals
**Goals:** 按账户隔离、不丢卡、同卡串行、去重;业务事件检查合并且受限流;整体切换可回退。
**Non-Goals:** 停复机指令队列与设备维度判断(第 6 个 Change,本 Change 中套餐步骤与 Outbox 消费者仍按现有方式同步停复机);批量查询;手动刷新行为。
## Decisions
1. **Redis 结构**(前缀新,不与旧 key 冲突):
- 账户:`polling:carrier:{cid}:priority|queue`(ZSET,member=card_id)、`:running`(ZSET,member=token,score=到期,仅计数)、`:dispatch_lock`。`stop_resume`、`sr_running` 在第 6 个 Change 使用,本 Change 预留领取顺序。
- 卡:`polling:card:{id}:due`(Hash:各类型到期、优先标记、连续失败、首次失败、最近错误、最近成功时间)、`:claim`(值=token)、`:exec`(值=token+实例)。
2. **Lua 脚本**:领取(清理过期 running → 计算上限 → 优先/普通按占比 → 预计调用数对比剩余 QPS → `SET claim NX PX` → 推后 score → 写 running)、续期(校验 token → PEXPIRE claim/exec → 推后 score 与 running)、收尾(校验 token → 删 claim/exec → 移出 running → 写 due → 按优先标记选队列设 score)、请求检查(设 due[type]=now、冷却判断、放入 priority 或打标记)。全部单节点 Lua,不跨 slot 问题。
3. **NSQ 而非 Asynq**(已定保留 NSQ):每账户独立 topic `polling.card.{cid}`,channel `worker`;消费者 `max_in_flight` 按账户参数;`msg_timeout` 大于续期间隔,执行中 `Touch`;租约 > `msg_timeout` × 允许重投次数。动态订阅随运营商账户与配置刷新。
4. **执行权 key**:NSQ 在消费者假死时会重投同一 token,仅核对 claim 无法区分;`SET exec token+实例 NX PX 续期间隔×2` 抢不到即 FIN。
5. **步骤函数**:原 4 个 handler 拆为 `step(ctx, StepInput{Card, Result}) (nextDue, err)`;`Result` 预留批量查询与推送结果。套餐步骤本轮流量已触发评估时可跳过(配置)。沿用 `polling_priority_claim.go` 的优先项认领与收尾。卡流量同步锁保留与手动刷新互斥。
6. **限流等待模式**:NSQ 消费者使用第 1 个 Change 限流器的"等待至超时"模式(不占 Asynq 协程),等待超过单步超时返回限流超时,按短延迟重排不计失败。
7. **请求检查取代观测序列**:5 处 `AppendSeriesRequested` 与 3 处读入口分发改为调用"请求检查(卡、类型、场景)";场景表 `tb_polling_check_scene` 预置 scene 行(订单支付、套餐激活、停复机成功、设备操作、自动续费购包、C 端资产详情、后台资产实时状态、实名链接),读入口默认配置冷却。观测序列中与卡检查无关的部分(设备信息同步 `query_device_info`)保持不变。
8. **失败告警**:`tb_polling_failure_alert` 部分唯一索引(卡、检查类型、未关闭),告警写入走异步、失败只记日志;通知走现有 `alert_service.go`。停复机方向的告警在第 6 个 Change 接入同一张表。
9. **整体切换**:`polling.scheduler_mode` 放受控系统配置;切换由 Worker 监听配置变更执行:停旧调度 → 初始化新结构(按批读库,进度复用 `/polling-stats/init-progress`)→ 开启分发。回退对称。旧 handler 执行前检查模式。
10. **监控**:队列与执行数读 Redis;QPS、耗时读第 1 个 Change 的分钟计数;告警读告警表。
## Risks / Trade-offs
- [不灰度,新调度出问题影响全部 9 万张卡] → 测试环境按生产规模压测(造卡或回放生产卡 ID),覆盖 tasks 第 11 节全部场景;上线首日重点监控,异常用 `scheduler_mode` 回退。
- [初始化 10 万张卡耗时] → 测试环境实测并写入上线步骤;初始化期间不领取,切换窗口内轮询暂停。
- [新增 NSQ 组件] → nsqd 与 nsqlookupd 部署、监控与告警纳入运维;NSQ 消息丢失由租约到期兜底。
- [Redis 内存增加] → 每卡一个 `due` Hash(约 10 字段),上线前按生产卡量估算并确认 `maxmemory` 与淘汰策略不淘汰轮询 key。
- [读入口冷却期内页面数据不新] → 已接受;页面照常展示数据库数据。
## Migration Plan
1. 测试环境部署 nsqd + nsqlookupd;执行迁移(三张新表、系统配置项、并发配置表注释)。
2. 部署 API 与 Worker,`scheduler_mode = legacy`;运营配置账户调度参数与场景。
3. 切 `carrier`,按 tasks 第 11 节核对;演练回退与再次切换。
4. 生产:维护者部署 NSQ、执行迁移与发布,选择低峰期切 `carrier`,首日监控。
5. 稳定运行后另行删除旧分片 key 与旧调度代码。

View File

@@ -0,0 +1,37 @@
## Why
现有轮询按固定 16 个分片 × 5 种类型调度,与运营商账户无关:慢账户占满共用的 Asynq 协程,影响其他账户与其他业务;出队后到投递前崩溃会丢卡;按集合大小背压,单分片超过 50 万后永久停止出队;投递无去重,同卡同类型可能重复执行,同卡不同类型并行执行。业务事件触发的卡观测序列固定"立即、3 分钟、5 分钟"三连查且不受限流,生产 2026-10-22 批量下单 70 张卡形成单秒 177 次的波峰,并与优先轮询重复查询。本 Change 是《轮询按运营商账户限流技术方案》第五部分第 3 节第 5 步。
## What Changes
- 新调度:每个运营商账户 3 个延时队列(停复机预留、优先、普通);卡始终留在队列中,领取时写带租约的处理中标记并推后 score,收尾按下次到期设置 score;崩溃后标记到期自动重新领取,不丢卡。
- 同卡串行:一张卡一个卡任务,按配置的步骤顺序(默认卡状态 → 流量 → 实名 → 套餐)串行执行已到期的检查类型;每步单独超时,某步失败不影响后续步骤。
- 分发器每秒按账户领取:账户分发锁保证每轮只有一个实例领取;按执行上限、优先占比、预计网关调用数与本秒剩余 QPS 领取。
- **BREAKING** 卡轮询从 Asynq 改为 NSQ 分发:每个账户独立 topic,`max_in_flight` 控制每进程并发;Redis 是唯一权威状态,NSQ 只做传输。消费前核对派发 token 并抢执行权;执行中续期租约;收尾 Lua 校验 token 写回。
- 失败处理:按"卡 × 检查类型"记连续失败次数与最近错误,按配置的退避序列重试;限流等待超时不计失败;达到阈值写失败告警(新表 `tb_polling_failure_alert`),首次成功自动恢复;同账户告警超阈值产生账户级告警。
- **BREAKING** 业务事件与读入口改为"请求检查":订单支付、套餐激活、停复机成功、设备操作、自动续费购包,以及 C 端资产详情、后台资产实时状态、实名链接,不再起观测序列;改为把对应检查设为立即到期放入优先队列,同卡多次请求合并,按场景配置延迟确认与冷却时长(新表 `tb_polling_check_scene`)。OpenAPI 查询保持不触发观测。
- 优先轮询提示、手动触发队列改为写入账户队列;初始化、生命周期改为操作账户队列与卡到期信息。
- 运营商账户调度参数(新表 `tb_carrier_polling_param`):执行上限、每进程 `max_in_flight`、优先占比等;步骤顺序、单步超时、退避、告警阈值放受控系统配置。
- 整体切换:受控系统配置 `polling.scheduler_mode`(`legacy` / `carrier`),不按账户灰度;切换时旧任务直接结束、从数据库初始化全部账户新结构后开始领取;可整体回退。
- 监控改为按运营商账户;下线按 ZCARD 背压、旧并发计数与并发配置接口、旧提示通道。
## Capabilities
### New Capabilities
- `carrier-polling-scheduler`:按账户队列与领取、租约与续期、执行权、同卡串行步骤、NSQ 分发与消费、执行上限与优先占比、失败退避与告警、请求检查与场景配置、整体切换与回退、按账户监控。
### Modified Capabilities
- `polling-load-control`:删除"轮询全局并发与背压"(由按账户执行上限与限流取代)。
- `polling-operations`:删除"轮询并发计数可观测""轮询并发配置覆盖实际任务""轮询任务类型名称可读"(并发配置页下线)。
- `priority-polling-queue`:"优先调度与执行提示通道"改为写入运营商账户优先队列。
## Impact
- 依赖:第 1 个 Change(限流器,消费者使用等待模式)、第 3 个 Change(去掉保护期)已上线。
- 部署:测试环境与生产新增 nsqd + nsqlookupd;`go.mod` 新增 NSQ 客户端依赖;yaml 增加 NSQ 地址、`msg_timeout`、租约、续期间隔、分发间隔、卡任务总超时、优雅退出宽限期。
- 数据库:新增 `tb_carrier_polling_param`、`tb_polling_check_scene`(预置场景)、`tb_polling_failure_alert`;`tb_system_config` 插入步骤与告警参数、`polling.scheduler_mode`;`tb_polling_concurrency_config` 保留不删、表注释标记废弃。
- 代码:重写 `internal/polling/queue_manager.go`、`scheduler.go`、`initializer.go`、`internal/task/polling_*_handler.go`(拆为步骤函数)、`polling_base.go`、`internal/service/polling/monitoring_service.go`;修改 `lifecycle_service.go`、`priority_manual_service.go`、`manual_trigger_service.go`、`polling_priority_claim.go`;业务事件 5 处与读入口 3 处改为请求检查;`cmd/worker/main.go`、`internal/bootstrap/*` 装配分发器与 NSQ 消费者;删除 `concurrency_service.go` 及其接口。
- 接口:新增 `/polling-carrier-params`、`/polling-check-scenes`、`/polling-failure-alerts`(列表、汇总、详情、处理)、`/iot-cards/:id/polling-state`;`/polling-stats` 按账户;下线 `/polling-concurrency`。前端新增调度参数、场景、失败告警页,监控页按账户,下线并发配置页。
- 行为:业务事件后的检查不再固定三连查,按场景配置;读入口受冷却与限流约束。

View File

@@ -0,0 +1,124 @@
## ADDED Requirements
### Requirement: 按运营商账户队列调度且不丢卡
系统 SHALL 在 `polling.scheduler_mode = carrier` 时,为每个运营商账户维护优先队列与普通队列,每张参与轮询的卡在其所属账户中 MUST 只占一个成员(优先标记决定在哪个队列),score 为该卡各检查类型中最早的到期时间。领取时系统 MUST 写带租约的处理中标记(写成功才算领取到)并把 score 推后到租约到期时间,卡不移出队列;处理结束(成功或失败)由收尾按派发 token 校验后删除处理中标记、写回各检查类型到期时间与失败计数,并把 score 设为下次最早到期时间。处理中崩溃时,租约到期后该卡 MUST 能被重新领取。优先提示、手动触发、生命周期事件 MUST 只修改到期时间与 score,不得新增重复成员。
#### Scenario: 执行中进程崩溃
- **WHEN** 卡任务执行到一半 Worker 崩溃
- **THEN** 租约到期后该卡被重新领取执行,不需要全量初始化
#### Scenario: 重复优先提示
- **WHEN** 同一张卡 1 秒内收到 3 次优先提示
- **THEN** 该卡在优先队列中仍只有一个成员,只执行一次
### Requirement: 分发器按账户领取
系统 SHALL 每秒对每个运营商账户执行一次领取,同一账户每轮 MUST 只由一个分发器实例领取。卡任务领取上限 = 账户执行上限 − 执行中数,且不超过订阅该账户的各进程 `max_in_flight` 之和;先领优先队列,优先领取数不超过本轮上限 × `priority_max_ratio`(为空不限),剩余名额给普通队列,普通队列不足时优先可补满;按卡累计本次预计网关调用数(未开实名管控的账户不计实名),任一限流组累计达到本秒剩余 QPS 即停止领取。只领取已到期的卡。
#### Scenario: 多实例同时运行
- **WHEN** 3 个 Worker 实例同时运行分发器
- **THEN** 同一账户每秒只被一个实例领取,执行中数不超过该账户执行上限
#### Scenario: 读入口刷屏
- **GIVEN** 账户 A `priority_max_ratio = 0.5`,优先队列积压 1 万张,普通队列有已到期卡
- **WHEN** 分发器领取账户 A
- **THEN** 本轮至少一半名额给普通队列
### Requirement: 卡任务串行执行检查步骤
系统 SHALL 对一张卡的一个卡任务按配置的步骤顺序(默认卡状态 → 流量 → 实名 → 套餐)串行执行本次已到期的检查类型。每步 MUST 有单独超时;某步失败只影响该步,后续步骤照常执行;限流等待超时时该步按短延迟重排且不计失败。卡任务总时长 MUST 不超过各步超时之和加余量,到达后取消剩余步骤并按失败收尾。同一张卡的不同检查类型 MUST NOT 并行执行。
#### Scenario: 流量步骤失败
- **WHEN** 卡任务中流量查询超时
- **THEN** 实名、套餐步骤照常执行,流量按退避间隔重试
#### Scenario: 同卡不同类型
- **WHEN** 卡的状态检查与流量检查同时到期
- **THEN** 系统在同一个卡任务中先查状态再查流量,不并行发起
### Requirement: 租约续期与执行权
系统 SHALL 在卡任务执行期间定期续期处理中标记(按 token 校验后延长租约,并同步推后 score 与执行中计数的到期时间)。续期发现 token 已不一致时,系统 MUST 立即停止后续步骤,不再发起新的网关调用,只写入已产生的业务结果。消费者执行前 MUST 核对处理中标记的值等于消息中的派发 token,并抢该 token 的执行权;任一不满足即丢弃消息,保证同一 token 不会被两个消费者同时执行。
#### Scenario: 长任务超过单个租约
- **WHEN** 卡任务因限流等待累计超过一个租约时长
- **THEN** 续期成功,期间该卡不被重新领取
#### Scenario: 消息重投时原消费者仍在执行
- **WHEN** NSQ 重投同一消息给另一个消费者,原消费者尚未结束
- **THEN** 后者抢不到执行权,直接丢弃消息
### Requirement: 卡轮询经 NSQ 分发
系统 SHALL 将领取结果发布到对应运营商账户的 NSQ topic,由订阅该 topic 的消费者执行;每个账户独立 topic,消费者按账户配置的 `max_in_flight` 控制每进程并发。重试与退避 MUST 由 Redis 中的 score 表达,MUST NOT 用 NSQ 重新入队做业务重试。发布失败时,系统 MUST 按 token 删除处理中标记并把 score 恢复为当前时间。卡轮询 MUST NOT 再经过 Asynq;其他业务的 Asynq 队列不受影响。
#### Scenario: 慢账户积压
- **WHEN** 账户 A 上游变慢导致其 topic 积压
- **THEN** 账户 B 的卡任务照常执行,Outbox 等 Asynq 业务不受影响
#### Scenario: 发布失败
- **WHEN** 领取后发布 NSQ 失败
- **THEN** 该卡处理中标记被删除、score 恢复为当前时间,下一轮重新领取
### Requirement: 检查失败退避与失败告警
系统 SHALL 按"卡 × 检查类型"记录连续失败次数、首次失败时间与最近错误;失败后下次到期 = 当前 + 退避间隔,退避随连续失败次数按配置序列拉长,最长不超过该类型正常检查间隔;成功一次即清零。限流等待超时与上游频率限制 MUST NOT 计入连续失败。连续失败次数或持续失败时长达到阈值、或命中"首次即告警"的错误类别时,系统 MUST 写失败告警;同一卡同一检查类型只保留一条未关闭告警,后续失败更新计数;告警后继续按最长退避轮询,首次成功自动转为已恢复。同一运营商账户在时间窗口内的告警数超过阈值时,系统 MUST 产生账户级告警。
#### Scenario: 持续超时
- **WHEN** 某卡流量查询连续失败达到阈值
- **THEN** 系统写一条失败告警,之后按最长退避继续查询
#### Scenario: 上游恢复
- **WHEN** 已告警的卡下一次查询成功
- **THEN** 连续失败清零,告警状态变为已恢复
#### Scenario: 账户级问题
- **WHEN** 账户 A 10 分钟内新增失败告警超过阈值
- **THEN** 系统额外产生一条账户级告警,提示联系上游
### Requirement: 业务事件与读入口请求检查
系统 SHALL 在订单支付、套餐激活、停复机成功、设备操作(按设备下各卡)、自动续费购包事务提交后,以及 C 端资产详情、后台资产实时状态、获取实名链接时,按场景配置把卡的对应检查类型设为立即到期并放入所属账户优先队列;卡正在执行时打优先标记,执行结束后立即再执行一次。同一张卡多次请求 MUST 合并为一次。场景配置了冷却时长时,该检查类型最近一次成功检查未超过冷却时长 MUST NOT 请求。场景配置了延迟确认序列时,本次检查完成后追加延迟检查(下次到期 = min(正常间隔, 当前 + 确认延迟)),观测结果已满足预期时取消后续确认。系统 MUST NOT 再为卡检查创建"立即、3 分钟、5 分钟"观测序列。OpenAPI 查询 MUST 保持不触发任何检查。场景由代码预置,后台只可修改检查类型、确认延迟与冷却时长。
#### Scenario: 批量下单
- **WHEN** 代理 10 秒内线下支付 27 笔订单,涉及 70 张卡
- **THEN** 系统只产生约 70 次立即检查(加按场景配置的确认检查),按各账户 QPS 平滑执行
#### Scenario: C 端反复刷新
- **GIVEN** C 端资产详情场景冷却 5 分钟
- **WHEN** 用户 2 分钟内打开同一资产详情 10 次
- **THEN** 只在第一次请求检查,其余不请求,页面照常展示数据库数据
#### Scenario: 停机后确认
- **GIVEN** 停复机成功场景配置确认延迟 3 分钟
- **WHEN** 停机成功后立即检查显示仍在线
- **THEN** 3 分钟后再检查一次;若立即检查已显示停机,则取消确认
### Requirement: 调度参数可后台维护
系统 SHALL 提供运营商账户调度参数(执行上限、卡任务与停复机每进程 `max_in_flight`、停复机执行上限、优先占比、单卡停复机最小重试间隔、结果未知确认延迟)的列表与修改,未配置的账户返回全局默认值并标记"默认";保存时 MUST 校验执行上限不大于当前订阅进程 `max_in_flight` 之和并提示。步骤顺序、单步超时、限流短延迟、退避序列、告警阈值通过受控系统配置维护,JSON 值 MUST 做结构校验(步骤只能是 4 种类型且不重复,退避序列递增)。修改仅超级管理员可用并写统一审计,下一轮调度生效。
#### Scenario: 步骤重复
- **WHEN** 超级管理员提交步骤顺序 `[card_status, carddata, carddata]`
- **THEN** 系统拒绝保存
### Requirement: 整体切换与回退
系统 SHALL 由受控系统配置 `polling.scheduler_mode`(`legacy` / `carrier`)全局决定卡轮询使用旧分片调度还是新调度,MUST NOT 按运营商账户灰度,任一时刻只有一套调度在领取与执行。切到 `carrier` 时:旧调度停止出队,旧 Asynq 轮询任务执行前检查模式并直接结束;系统从数据库按批初始化全部账户新结构,初始化完成前新分发器不领取。回到 `legacy` 时:新分发器停止领取,执行中任务按收尾规则完成,系统重新初始化旧分片队列后旧调度恢复。所有写入轮询结构的入口按当前模式写新或旧结构。
#### Scenario: 切换期间旧任务
- **WHEN** 切到 `carrier` 时 Asynq 中仍有排队的旧轮询任务
- **THEN** 这些任务执行时直接结束,不调网关、不重入旧队列
#### Scenario: 回退
- **WHEN** 新调度异常,超级管理员把模式改回 `legacy`
- **THEN** 新分发器停止领取,旧分片队列按数据库重建后恢复轮询,无卡丢失
### Requirement: 按账户监控与卡轮询状态查询
系统 SHALL 按运营商账户展示各队列长度、已到期数、执行中数、实际 QPS、限流等待与超时次数、处理中标记到期次数、失败告警数(按错误类型);提供单卡轮询状态查询(各检查类型下次到期、连续失败与最近错误、是否执行中),只读。系统 SHALL 提供失败告警列表(按运营商账户、检查类型、错误类型、状态、时间筛选)、按账户 × 错误类型汇总、详情与标记已处理。
#### Scenario: 排查单卡
- **WHEN** 运营查询某卡轮询状态
- **THEN** 系统返回各检查类型下次到期时间、最近错误与是否执行中,不改变任何状态

View File

@@ -0,0 +1,5 @@
## REMOVED Requirements
### Requirement: 轮询全局并发与背压
**Reason**: 并发计数不以上游运营商账户为单位、数值没有依据,按集合大小背压会在单分片积压超过阈值后永久停止出队。由 `carrier-polling-scheduler` 的按账户执行上限、领取上限与 `carrier-gateway-rate-limit` 的按账户限流取代。
**Migration**: 运营按账户配置调度参数与限流组;`tb_polling_concurrency_config` 保留不删、表注释标记废弃,代码不再读写。

View File

@@ -0,0 +1,13 @@
## REMOVED Requirements
### Requirement: 轮询并发计数可观测
**Reason**: 按任务类型的并发计数随新调度下线,执行情况改为按运营商账户的执行中数与监控展示。
**Migration**: 使用 `/polling-stats` 按账户监控与 `/polling-carrier-params` 调度参数;`/polling-concurrency` 下线,前端去掉并发配置页。
### Requirement: 轮询并发配置覆盖实际任务
**Reason**: 并发配置由运营商账户调度参数(执行上限、每进程 `max_in_flight`)取代。
**Migration**: 同上;`tb_polling_concurrency_config` 保留不删、表注释标记废弃。
### Requirement: 轮询任务类型名称可读
**Reason**: 该名称仅用于并发状态接口,接口随并发配置一起下线。
**Migration**: 检查类型的中文名称由 `/polling-options` 枚举接口提供。

View File

@@ -0,0 +1,20 @@
## MODIFIED Requirements
### Requirement: 优先调度与执行提示通道
优先轮询项 MUST 以持久化事实为权威;执行提示 MUST 通过把该卡对应检查类型设为立即到期、并把卡放入其所属运营商账户的优先队列下发;卡正在执行时只打优先标记,本次执行结束后立即再执行一次。同一张卡在一个账户中只占一个队列成员,多次提示 MUST 合并。手动触发队列取出的卡 MUST 设为立即到期并放入所属账户的普通队列。分发器 MUST 在每轮领取中先领优先队列、再领普通队列,优先领取数受账户 `priority_max_ratio` 约束。提示 MUST NOT 作为活动、权限或尝试次数的判定依据。优先 MUST NOT 绕过运营商账户限流与执行上限。
#### Scenario: 提示丢失
- **WHEN** 优先提示因缓存服务重启丢失
- **THEN** 后续普通轮询执行仍按活动优先轮询项认领并执行,仅退化为延迟到该卡下一次到期,不丢事实也不产生第二套补偿
#### Scenario: 同一轮的领取顺序
- **WHEN** 同一账户的优先队列与普通队列都有已到期的卡
- **THEN** 分发器先领优先队列,在优先占比内领取后再领普通队列
#### Scenario: 执行中收到优先提示
- **WHEN** 卡正在执行卡任务时收到优先提示
- **THEN** 系统打优先标记,本次执行结束后该卡立即再执行一次,不并行执行

View File

@@ -0,0 +1,86 @@
## 0. 前置确认
- [ ] 0.1 确认第 1 个 Change(限流器)与第 3 个 Change(去掉保护期)已上线;维护者提供测试环境 nsqd + nsqlookupd 地址。
## 1. 迁移与配置
- [ ] 1.1 新增成对迁移:`tb_carrier_polling_param`(`carrier_id` 唯一、`inflight_limit`、`card_max_in_flight`、`stop_resume_max_in_flight`、`sr_inflight_limit`、`priority_max_ratio`、`stop_resume_min_interval`、`stop_resume_confirm_delay`、审计字段)。
- [ ] 1.2 新增成对迁移:`tb_polling_check_scene`(`scene` 唯一、`check_types`、`confirm_delays`、`cooldown`),预置 8 个场景,读入口场景带默认冷却。
- [ ] 1.3 新增成对迁移:`tb_polling_failure_alert`(卡、运营商账户、检查类型、连续失败、首次与最近失败、最近错误、状态、处理人与时间;部分唯一索引 `(card_id, check_type) WHERE status = 未处理`)。
- [ ] 1.4 新增成对迁移:`tb_system_config` 插入 `polling.scheduler_mode`(默认 `legacy`)、步骤顺序、单步超时、卡任务总超时余量、退避序列、告警阈值、账户级告警窗口与阈值;`tb_polling_concurrency_config` 表注释标记废弃。
- [ ] 1.5 `pkg/config` 与 `defaults/config.yaml`:NSQ 地址、`msg_timeout`、租约、续期间隔、分发间隔、优雅退出宽限期、默认执行上限与 `max_in_flight`;`go.mod` 引入 NSQ 客户端。
- [ ] 1.6 注册受控系统配置项并实现 JSON 结构校验(步骤类型合法且不重复、退避序列递增)。
## 2. Redis 结构与 Lua
- [ ] 2.1 常量:账户队列、running、dispatch_lock,卡 due、claim、exec 的 key。
- [ ] 2.2 领取 Lua:清理过期 running、执行上限、优先占比、预计调用数对比本秒剩余 QPS、`SET claim NX PX`、推后 score、写 running;已有 claim 时推后到剩余 TTL 后。
- [ ] 2.3 续期 Lua:校验 token,延长 claim、exec,推后 score 与 running。
- [ ] 2.4 收尾 Lua:校验 token,删 claim、exec,移出 running,写 due 与失败计数,按优先标记设置 score;token 不一致时只写业务结果。
- [ ] 2.5 请求检查 Lua:设 due[type]=now、冷却判断、放入 priority 或打优先标记,合并重复请求。
## 3. 初始化与生命周期
- [ ] 3.1 `initializer.go`:按批读库计算各类型 due(复用第 2 个 Change 的分层与重置日前到期计算),写 due 与账户 queue;进度写入 init-progress。
- [ ] 3.2 `lifecycle_service.go`、`asset_polling_service.go`:增删卡、状态变化、启停轮询改为操作账户队列与 due;恢复轮询时 due 设为当前加抖动。
- [ ] 3.3 优先提示(`priority_manual_service.go`)与手动触发(`manual_trigger_service.go`)改为写 due 与账户队列。
## 4. 分发器
- [ ] 4.1 Worker 内每秒对各账户抢分发锁并执行领取 Lua,发布到 `polling.card.{cid}`;发布失败按 token 删 claim、score 恢复为当前时间。
- [ ] 4.2 读取账户调度参数(缺省用默认),执行上限不超过订阅进程 `max_in_flight` 之和,不满足时收紧并上报。
- [ ] 4.3 定时动作:统计各账户处理中标记到期次数、写分发器心跳。
## 5. NSQ 消费者与卡任务
- [ ] 5.1 NSQ 生产者与消费者封装:按账户动态订阅与取消订阅、`max_in_flight`、`Touch`、优雅退出(停止分发与订阅、宽限期内完成后 FIN)。
- [ ] 5.2 消费入口:核对 claim token、抢 exec 执行权,任一失败即 FIN。
- [ ] 5.3 将实名、流量、卡状态、套餐 4 个 handler 拆为步骤函数(`StepInput` 含可选外部结果);按配置顺序串行执行到期类型;单步超时、总超时、panic 恢复。
- [ ] 5.4 执行期间按续期间隔续期;续期失败立即停止后续步骤。
- [ ] 5.5 网关调用使用限流器等待模式;限流等待超时按短延迟重排不计失败。
- [ ] 5.6 沿用 `polling_priority_claim.go` 的认领与收尾;保留卡流量同步锁。
## 6. 失败退避与告警
- [ ] 6.1 收尾按"卡 × 类型"更新连续失败、首次失败、最近错误;按退避序列计算下次到期,频率限制与限流超时不计失败;成功清零。
- [ ] 6.2 达到阈值或首次即告警类别时写或更新 `tb_polling_failure_alert`;成功后自动转已恢复;通知走现有告警通道。
- [ ] 6.3 账户级告警:窗口内同账户告警数超过阈值时产生账户级告警。
## 7. 业务事件与读入口请求检查
- [ ] 7.1 订单支付、套餐激活、停复机成功、设备操作(按设备下各卡)、自动续费购包 5 处 `AppendSeriesRequested` 改为事务提交后请求检查。
- [ ] 7.2 C 端资产详情、后台资产实时状态、C 端与后台实名链接改为请求检查;OpenAPI 查询保持不触发。
- [ ] 7.3 延迟确认:按场景在检查完成后追加确认到期;结果已满足预期时取消。
- [ ] 7.4 卡检查不再创建观测序列;`query_device_info` 等非运营商上游部分保持不变。
## 8. 整体切换
- [ ] 8.1 Worker 监听 `polling.scheduler_mode`:切 `carrier` 时停旧调度出队、初始化新结构后开启分发;切 `legacy` 时停止领取、等待执行中任务收尾、重建旧分片队列后恢复旧调度。
- [ ] 8.2 旧轮询 handler 执行前检查模式,为 `carrier` 时直接结束。
- [ ] 8.3 所有写入轮询结构的入口按当前模式写新或旧结构。
## 9. 接口与下线
- [ ] 9.1 `/polling-carrier-params` 列表(含默认标记)、详情、修改、删除;`/polling-check-scenes` 列表与修改;`/polling-failure-alerts` 列表、`/summary`、详情、`PUT /:id/status`;`GET /iot-cards/:id/polling-state`。
- [ ] 9.2 `/polling-stats` 改为按账户(队列长度、到期数、执行中、实际 QPS、限流等待与超时、处理中标记到期、告警数)。
- [ ] 9.3 下线 `/polling-concurrency`、`concurrency_service.go`、`acquireConcurrency`/`releaseConcurrency`、按 ZCARD 背压;旧提示通道 List 不再写入。
- [ ] 9.4 同步路由、`cmd/api/docs.go`、`cmd/gendocs/main.go`,重新生成接口文档。
## 10. 编译与规范校验
- [ ] 10.1 `gofmt -w`;`go build ./cmd/api ./cmd/worker` 通过。
- [ ] 10.2 `openspec validate add-carrier-polling-scheduler` 与 `openspec doctor --json` 通过。
## 11. 测试环境验证(自动化测试为 N/A,按 ENG-TEST-001;按生产规模造卡或回放生产卡 ID)
- [ ] 11.1 多实例同时领取:同卡只被领取一次;同一账户每轮只领一次;执行中数不超过执行上限。
- [ ] 11.2 处理中崩溃:杀掉执行中的 Worker,租约到期后卡被重新领取,不丢卡。
- [ ] 11.3 长任务续期:执行超过单个租约时续期成功;构造 token 不一致时续期失败并停止后续步骤。
- [ ] 11.4 NSQ 重投:同一 token 两个消费者只有一个拿到执行权。
- [ ] 11.5 同卡串行:状态与流量同时到期时在一个卡任务中先后执行;某步失败后续步骤照常。
- [ ] 11.6 慢账户隔离:人为让账户 A 变慢,账户 B 与 Outbox 等 Asynq 业务不受影响。
- [ ] 11.7 请求检查:多次请求合并;冷却时长内不请求;执行中请求打优先标记;批量下单不形成单秒波峰;OpenAPI 查询不触发。
- [ ] 11.8 失败退避与告警:连续失败按序列退避并在阈值写告警,成功后自动恢复;账户级告警触发。
- [ ] 11.9 整体切换:切 `carrier` 时旧 Asynq 排队任务直接结束、初始化完成前不领取;实测约 10 万张卡初始化耗时并写入上线步骤;回退后旧分片队列完整、无丢卡;再次切换正常。
- [ ] 11.10 跨账户设备:设备下各卡分属不同账户时各自按账户执行,无重复执行。
- [ ] 11.11 按生产卡量评估 Redis 内存占用,确认轮询 key 不会被淘汰。