Files
junhong_cmp_fiber/openspec/changes/add-carrier-polling-scheduler/design.md
邹进 42e881576d
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
feat: 卡网关按运营商账户限流并记录停复机调用
- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
2026-10-24 15:06:41 +09:00

43 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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 与旧调度代码。