## 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 与旧调度代码。