Files
junhong_cmp_fiber/docs/engineering/轮询按运营商账户限流技术方案.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

1223 lines
144 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.
# 轮询按运营商账户限流技术方案
最后更新:2026-10-24
状态:技术方案(未实现)。已定事项与后续事项见第七部分。
文档结构:
- 第一部分:现状逻辑(As-Is)
- 第二部分:方案总览
- 第三部分:详细设计(To-Be)
- 第四部分:清理项
- 第五部分:改动范围与实施拆分
- 第六部分:与老系统对比
- 第七部分:待确认与后续事项
---
## 第一部分:现状逻辑(As-Is)
### 1. 队列结构
- 固定 16 个分片:`PollingShardCount = 16`(`pkg/constants/polling.go:7`),分片号 `card_id % 16`,与运营商账户无关。
- 每个分片下每种任务类型一个 ZSET:`polling:shard:{shardID}:queue:{taskType}`,score 为下次检查时间戳(`pkg/constants/redis.go:491`)。
- 5 种任务类型(`pkg/constants/constants.go:64-68`):
| 类型 | 含义 | 是否调网关 |
|---|---|---|
| `polling:realname` | 实名状态检查 | 是,查实名 |
| `polling:carddata` | 卡流量检查 | 是,查流量 |
| `polling:card_status` | 卡开停机状态检查 | 是,查状态 |
| `polling:protect` | 保护期一致性检查 | 仅在需要时调停机或复机 |
| `polling:package` | 套餐检查(定期重新判断停复机) | 不查网关,判断出要停复机时调停机或复机 |
- 另有两个按任务类型划分的 List:优先轮询提示通道 `polling:priority:{taskType}`;手动触发队列 `polling:manual:{taskType}`(接口 `/polling-manual-trigger`,`internal/routes/admin.go:149`)。
### 2. 入队
- 启动全量初始化:`internal/polling/initializer.go:268`,分批读库,按 last_check_at 和间隔算下次时间,Pipeline 写 ZADD 和卡缓存。
- 执行后重入队:`Requeue`(ZADD,覆盖时间);`EnsureQueued`(ZADD NX,只补缺失)。
- 卡状态变化:`OnCardStatusChanged`(`internal/polling/lifecycle_service.go:66`)先从所有队列移除,再按"当前时间 + 0~interval/10 秒抖动"重新入队全部类型。
### 3. 调度(`internal/polling/scheduler.go:158`,每 1 秒)
1. 先清空优先提示通道和手动触发队列(每类型最多 1000 条),不受初始化状态和背压影响。
2. 初始化未完成则返回。
3. 16 个分片各起一个 goroutine,整轮超时 0.9 秒。
4. 每个分片内按 5 种类型依次:ZCARD 查深度,超过 50 万跳过(背压);Lua 原子出队到期卡(最多 7000 条);逐条 `Enqueue` 到 Asynq(`MaxRetry(0)`、超时 60 秒、按类型分队列);投递失败则按当前时间 Requeue。
### 4. 执行与并发控制
- Asynq Worker 协程数来自 `queue.concurrency`(默认 10),5 个轮询队列权重都为 1,与其他业务队列共用协程池(`pkg/constants/constants.go:365-376`)。
- handler 执行时抢 Redis 令牌(`internal/task/polling_base.go:108`):一次 Lua 同时 INCR 全局计数(`polling_total_max_concurrency`,默认 100)和该任务类型计数(后台可配,默认 300),任一超限即回滚并 Requeue;执行完 DECR;key TTL 10 分钟。
- 配置表 `tb_polling_concurrency_config` 按 task_type 存上限,`ConcurrencyService` 同步到 Redis。
- 没有任何按运营商账户的并发或 QPS 控制。
### 5. 停复机
- 统一入口 `StopResumeService.EvaluateAndAct`(`internal/service/iot_card/stop_resume_service.go:113`):
- 在线卡:停机原因优先级为 流量用完 > 无有效套餐 > 实名不满足;设备维度原因会抢设备锁(SetNX 30 秒),逐张停掉设备下所有在线卡。
- 停机卡:须同时满足 有效套餐、流量未用完、实名满足 才复机;设备卡同样按设备批量复机。
- 停复机新规则(`Iteration/8-11` 已实现,`internal/service/iot_card/stop_resume_unified.go`,总开关 `stop_resume.unified_rule_enabled` 默认关闭):
- 开启后:复机 = 有生效套餐 + 流量充足 +(运营商账户未开实名管控,或开了实名管控且已实名),不看停机原因;实名管控为运营商账户字段 `tb_carrier.realname_control_enabled`,不区分行业卡、不看卡或设备的 `realname_policy`;卡或所在设备暂停轮询时不自动停复机;持通道阈值锁仍拒绝复机。
- 关闭时(旧口径):只对轮询停机原因自动复机;实名满足 = 行业卡或已实名,否则所属资产 `realname_policy = none`。
- 实名轮询仍按卡类别跳过行业卡(`internal/task/polling_realname_handler.go:70`),未随新规则调整。
- 每次网关调用失败重试 3 次,每次 sleep 2 秒(`stop_resume_service.go:99-100`)。
- 触发路径:
- 轮询任务内同步执行:`package` 调 `EvaluateAndAct`;`protect` 保护期内调 `ForceStopCard` / `ForceStartCard`,保护期外调 `EvaluateAndAct`。
- 经 Outbox 异步执行:查流量、查状态、查实名写入观测结果后产生 Outbox 事件,由卡观测消费者(`cmd/worker/main.go:658-678`)调用 `EvaluateAndAct`。"流量用完停机"走这条路径。
- 套餐激活(`internal/service/package/activation_service.go:718` `resumeAfterActivation`,实名激活、排队激活、指定激活、队首激活 4 处调用)、流量重置(`internal/service/package/reset_service.go:400`,每个套餐一个 goroutine)、订单支付后(`internal/service/order/service.go:2196`):事务提交后起裸 goroutine 调 `ResumeCardIfStopped` 当场复机,失败只打日志,不重试。
- 退款后资产处理(`internal/service/refund/service.go:1243` `stopAsset`):退款后资产无可用主套餐时调 `ManualStopCard` 当场停机,停机原因记为 `manual`;`ManualStopCard` 内部 sleep 重试,失败后由 Outbox 重投与补偿扫描(`internal/infrastructure/commissiondelivery/event.go` `RecoverRefundPostProcessing`)反复补发,卡已停机也照样调网关。
- 停复机没有独立队列,在哪个任务里触发就在哪个任务里同步调网关。
### 5.1 业务事件触发的卡观测序列
- 机制:`SeriesTrigger`(`internal/application/cardobservation/series.go`)为每张卡、每种检查(状态、流量、实名)创建固定的"立即、3 分钟、5 分钟"三次尝试(`pkg/constants/card_observation.go:38`),作为 Asynq 任务执行,不经过轮询调度,不受任何限流约束。
- 业务事件入口(经 Outbox 写入 `AppendSeriesRequested`):订单支付后(`internal/service/order/service.go:2276`)、套餐激活(`internal/service/package/activation_service.go:744`)、停复机成功后(`internal/service/iot_card/stop_resume_service.go:1104`)、设备操作(`internal/service/device/service.go:1751`)、自动续费购包(`internal/task/auto_purchase.go:288`)。
- 读入口直接分发(`BestEffortSeriesDispatcher`):C 端资产详情(`internal/handler/app/client_asset.go:366`)、后台资产实时状态(`internal/handler/admin/asset.go:313`)、实名链接(`internal/handler/app/client_realname.go:158`、`internal/service/iot_card/gateway_service.go:76`)。OpenAPI 查询不触发观测序列(`agent-open-api` 规范明确要求,2026-10-24 按代码核实)。
- 与优先轮询重复:套餐生效时已产生优先轮询项,卡会被立即轮询一次;观测序列又额外查 3 轮。
- 生产实例(2026-10-22):代理 11:40:58~11:41:08 线下支付 27 笔设备套餐订单,约 70 张卡 × 3 种检查 × 3 次,约 600 次网关调用集中在 11:41、11:44、11:46 三个瞬间,11:46:04 单秒 177 次。
### 6. 保护期
- 来源:后台对设备停机或复机时设置 1 小时保护期(`internal/service/device/service.go:1506,1663`),key `protect:device:{id}:stop|start`,二者互斥。
- 作用:保护期内阻止相反的人工操作;`protect` 轮询发现方向不一致时强制停复机。
- 问题:自动停复机 `EvaluateAndAct` 不检查保护期,保护期内会出现"自动停机 → 保护期强制复机 → 再自动停机"的反复翻转;且与"规则优先"原则冲突。
### 7. 运营商账户
- `tb_carrier` 一行实际是一个上游账户(通道),名称中带上游账号,例如 `联通31-710WLW17915117`、`移动15-BE20030985258`。
- 上游的频率限制以账户为单位,现有并发控制既不按账户,数值(300、100)也没有依据。
### 8. 现状问题汇总
1. 并发控制不以上游账户为单位,数值没有依据,无法防止上游超频或繁忙。
2. 背压按 ZCARD 统计整个集合(含未到期),单分片超过 50 万卡后永久停止出队。
3. 出队后到投递 Asynq 前进程崩溃,卡会丢失直到下次全量初始化。
4. `Enqueue` 不受 0.9 秒超时控制,单轮可能逐条投递数十万任务,阻塞主循环;回退 Requeue 用的是可能已过期的 ctx。
5. 任务进入 Asynq 后不区分账户;慢账户会占满 Worker 协程,影响其他账户。
6. 同一张卡的不同类型可以并行执行。
7. 停复机在执行过程中 sleep 重试,长时间占用协程;设备停复机可能跨账户。
8. 保护期机制与"规则优先"冲突,且实现上会反复翻转。
9. 手动刷新后 `OnCardStatusChanged` 会让所有类型几秒内重新轮询一遍,网关调用翻倍(本方案不处理,见第七部分)。
10. 开启轮询开关的卡全部按配置轮询,配置只能区分网络与实名状态,库存卡、无套餐卡与在用卡同频调网关;无套餐仍在跑流量的卡没有专门兜底。
11. 停复机新规则靠总开关与旧口径并存,代码里同时保留两套实名判断与复机条件;实名轮询仍按行业卡跳过,与新规则的运营商账户实名管控口径不一致。
12. 套餐激活、流量重置、订单触发的复机在裸 goroutine 中当场执行:失败只打日志,客户付费后卡可能一直停机且无人知晓;流量重置日集中复机,瞬间打满上游;与流量入账后的停机可能并发反向操作同一张卡。
13. 无套餐期间若不查流量,按月对账(本月最大快照 − 本月已结算)会把无套餐期间、以及二次销售前上一用户本月的用量,算进新激活的套餐。
14. 流量查询稀疏(平均每卡约 1.5 天一次),每张卡在运营商流量重置日清零前最后一次查询到清零之间的用量查不到、扣不到套餐上(旧周期尾部丢失)。
15. 退款触发的停机重试风暴:退款走人工停机接口(`ManualStopCard` 内部 sleep 重试),失败后 Outbox 重投与每分钟补偿扫描反复补发;所有上游返回一律按普通失败处理。生产 2026-10-22:5 笔退款涉及 5 张广电卡,其中 4 张处于上游终态(号码封存禁止办理、已销户、风险停机仅支持风险复机),根本无法停机;另 1 张被上游单卡频率限制("3 分钟内同一张卡相同操作仅允许一次""卡状态变更每十分钟只允许调用 1 次")拦截,重试间隔远小于窗口,每次重试都重置窗口。结果停机请求 24 小时失败约 26.8 万次,单卡每 1~2 秒调用一次,持续冲击上游;且错误原因只在统一审计中可见。
16. 业务事件触发的卡观测序列固定"立即、3 分钟、5 分钟"三连查且不受限流约束,批量下单等批量操作在同一瞬间形成波峰;与优先轮询重复查询。
17. 失败原因与调用量不可见:轮询调用网关失败时,集成日志 `provider_code`、`provider_message` 为空、`duration_ms` 为 0;网关业务错误码只拼在错误字符串里(`internal/gateway/client.go:274`);轮询成功且数据未变化时不记录。无法区分限频、卡错误与超时,也算不出各账户成功率与真实调用量(生产 2026-10-22:24 小时轮询失败约 37 万次,原因均为空)。
18. 投递无去重:调度器投递 Asynq 时未设置 TaskID(`internal/polling/scheduler.go:282`),优先提示与手动触发 List 可重复 push、查状态时"补齐缺失的套餐任务"(`ensureMissingTask`)会把正在 Asynq 中排队的任务当作缺失重新补入、生命周期事件会把排队中的卡重新放回 ZSET,同一张卡同一检查类型可能被重复投递执行;退款重试风暴即重复投递的一例。
---
## 第二部分:方案总览
### 1. 目标
- 轮询按运营商账户(`tb_carrier` 一行即一个上游账户)隔离调度。
- 每个运营商账户的网关 QPS 不超过配置上限,后台修改即时生效。
- 同一张卡的各类检查串行执行。
- 停复机优先级最高。
- 规则优先:只要符合规则就自动停复机,人工操作不享有豁免期。
- 所有数值与分组由后台配置,代码中不出现运营商账户名称、分组方式或业务数值。
### 2. 范围
在范围内:
- 所有自动触发的卡检查与停复机:轮询、业务事件与读入口触发的检查、激活前流量结算,以及轮询、Outbox 消费者、套餐激活、流量重置、订单、退款、套餐到期、实名管控修改触发的自动停复机。
- 卡的 5 个网关操作的限流:查流量、查状态、查实名、停机、复机。
- 保护期机制的整体清理。
- 分层轮询与到期即停(第三部分第 11 节)。
- 自动停复机统一出口:轮询、Outbox 消费者、套餐激活、流量重置、订单、退款触发的自动停复机都只请求评估,统一由停复机指令队列执行(第三部分第 6 节)。
- 业务事件触发的卡检查并入卡任务:不再起观测序列,改为请求检查(第三部分第 5.1 节)。
- 套餐激活前流量结算,保证无套餐期间的用量不计入新套餐(第三部分第 11.9 节)。
不在范围内:
- 批量查询:gateway 目前不支持(`internal/gateway/flow_card.go:62` 为预留未实现),后期 gateway 支持后再增加;本方案在步骤接口上预留查询结果外部传入的能力(见第三部分第 5 节)。
- 手动刷新(`/assets/:identifier/refresh`)。
- 后台人工点击的停复机、通道阈值、自动续费直接发起的停复机、手动刷新:照旧直接调网关,不限流;其余所有自动触发的检查与停复机均受运营商账户限流约束。
- 手动触发队列接口保留,只调整消费方式。
- 停复机业务规则不新增:沿用 `Iteration/8-11` 已实现的停复机新规则,本方案只将其转正(第三部分第 12 节);提前停机、续费联动等不在范围。
### 3. 核心模型
```
┌──────────── 每个运营商账户(Redis 延时队列)────────────┐
规则判断 ──生成指令──▶ stop_resume ─┐
优先提示 ───────────▶ priority ─┼─▶ 分发器(每秒,按 停复机 > 优先 > 普通、剩余 QPS 与执行上限领取)
到期检查 ───────────▶ queue ─┘ 领取即写处理中标记(token + TTL),卡留在队列中
└──────────────────────────┬─────────────────────────────┘
▼ 发布
NSQ topic:polling.stop_resume.{cid}(专用消费者)
polling.card.{cid}
▼ 消费(max_in_flight 控制每进程并发)
网关限流器(运营商账户 → 限流组 → 操作,QPS)
│
▼
gateway
设备维度判断请求 ──▶ device_eval 队列 ──▶ 分发器 ──▶ NSQ polling.device_eval ──▶ 生成设备下各卡的停复机指令
```
分工:Redis 负责到期调度(含长延迟)、同卡去重与串行、执行上限、QPS 限流、设备锁,是唯一权威状态;NSQ 替代 Asynq 负责执行分发、消费者并发与执行超时重投。
---
## 第三部分:详细设计(To-Be)
### 1. 轮询类型
| 名称 | 是否调网关 | 说明 |
|---|---|---|
| 卡状态 `card_status` | 是 | 查状态 |
| 流量 `carddata` | 是 | 查流量 |
| 实名 `realname` | 是 | 查实名 |
| 套餐 `package` | 否 | 定期按规则重新判断停复机 |
| 停复机指令 | 是 | 独立队列,优先级最高 |
`protect` 类型下线(见第四部分)。
### 2. Redis 数据结构
每个运营商账户 `{cid}`:
| Key | 类型 | 内容 |
|---|---|---|
| `polling:carrier:{cid}:stop_resume` | ZSET | 停复机指令,member=card_id,score=可执行时间;被领取后 score 推后为处理中标记到期时间 |
| `polling:carrier:{cid}:priority` | ZSET | 优先卡,member=card_id,score=可执行时间;被领取后同样推后 |
| `polling:carrier:{cid}:queue` | ZSET | 普通卡,member=card_id,score=该卡所有检查类型中最早的到期时间;被领取后同样推后 |
| `polling:carrier:{cid}:running` | ZSET | 仅用于计数:执行中的卡任务,member=派发 token,score=到期时间;用于执行上限与监控 |
| `polling:carrier:{cid}:sr_running` | ZSET | 仅用于计数:执行中的停复机指令,结构同上 |
每张卡:
| Key | 类型 | 内容 |
|---|---|---|
| `polling:card:{id}:due` | Hash | 各检查类型的下次到期时间、优先标记、各检查类型的连续失败次数 / 首次失败时间 / 最近错误 |
| `polling:card:{id}:stop_resume_cmd` | Hash | 停复机指令:动作、原因、来源、场景、生成时间、版本号 `ver`(每次生成或覆盖指令时 `HINCRBY`)、连续失败次数、首次失败时间、最近错误、待确认标记(上游返回已受理类频率限制时置位,下次执行前先查卡状态) |
| `polling:card:{id}:sr_last_call` | String | 本卡最近一次调用上游停机或复机的时间(不分操作,停机与复机合计),用于单卡最小重试间隔;TTL 不小于单卡最小重试间隔 |
| `polling:card:{id}:claim` | String | 卡任务处理中标记,值=派发 token,TTL=租约时长 |
| `polling:card:{id}:sr_claim` | String | 停复机指令处理中标记,值=派发 token,TTL=租约时长 |
| `polling:card:{id}:exec` / `sr_exec` | String | 执行权:值=派发 token + 消费者实例 ID,TTL=续期间隔×2,随续期延长;防止 NSQ 重投时同一 token 被两个消费者同时执行(见 3.3 节) |
设备维度判断:
| Key | 类型 | 内容 |
|---|---|---|
| `polling:device_eval:queue` | ZSET | 待判断设备,member=device_id,score=可执行时间;同一设备只有一个成员;被领取后 score 推后 |
| `polling:device:{id}:eval_ver` | String | 判断请求版本号,每次请求 `INCR` |
| `polling:device:{id}:eval_scenes` | Set | 待处理的请求场景(轮询、到期、退款、激活等),多次请求取并集(见 6.1 节) |
| `polling:device:{id}:eval_claim` | String | 设备判断处理中标记,值=派发 token,TTL=租约时长 |
| `polling:device:{id}:eval_lock` | String | 设备维度判断锁,值为持有者 token,带 TTL |
分发锁:
| Key | 类型 | 内容 |
|---|---|---|
| `polling:carrier:{cid}:dispatch_lock` | String | 账户分发锁,值=分发器实例 token,TTL 略小于分发间隔;同一账户每轮只由一个实例领取(见 3.2 节) |
| `polling:device_eval:dispatch_lock` | String | 设备判断分发锁,同上 |
网关限流:
| Key | 类型 | 内容 |
|---|---|---|
| `gateway:qps:{cid}:{group}` | ZSET | 滑动窗口内每次请求的毫秒时间戳 |
| `gateway:qps:{cid}:{group}:high_waiting` | String | 正在等待名额的高优先级请求数 |
| `gateway:qps:global:{group}` | ZSET | 可选的全局组窗口 |
去重与串行原则(处理中标记):
- 卡**始终留在**延时队列中(priority 与 queue 二者之一,由优先标记决定),不因领取而移出。
- 领取时写处理中标记 `SET claim token NX PX 租约`,写成功才算领取到,同时把该卡在队列中的 score 推后到标记到期时间,避免重复扫描。
- 处理结束(无论成功或失败)由收尾 Lua 校验 token、删除处理中标记,并把 score 改为下次执行时间:成功按检查间隔,失败按退避间隔(见 6.2 节)。失败不会丢卡,而是带着重试时间留在队列里。
- 处理中崩溃:处理中标记 TTL 到期自动消失,score 已是到期时间,下一轮自然被重新领取,不需要额外的租约收回动作。
- `running` 集合只用于计数(执行上限与监控),其过期成员在每次领取前清理,不承担恢复职责。
- 停复机指令、设备判断使用各自的处理中标记,与卡任务互不阻塞。
- 停复机指令领取时记下指令版本号 `ver`,随消息发布;收尾时版本号未变才移除指令,变了说明执行期间有新指令覆盖,保留指令并把 score 设为 now(见第 6 节)。
内存估算:每张参与轮询的卡新增 `due` Hash(约 10 个字段),停复机指令、处理中标记、`sr_last_call` 只在有指令或执行中时存在。上线前按生产参与轮询的卡量估算 `due` 总内存(含现有卡缓存),并确认 Redis `maxmemory` 与淘汰策略不会淘汰轮询 key(轮询 key 不得被 LRU 淘汰)。
### 3. 分发与执行(Redis + NSQ,不经过 Asynq)
卡轮询(卡任务、停复机指令、设备维度判断)不再经过 Asynq,执行分发改用 NSQ。NSQ 只替换卡轮询这一块;其他业务(Outbox `outbox:deliver`、导出、佣金、自动续费、通道阈值、套餐排队激活等)继续使用 Asynq,不受影响。原调度器每 10 秒执行的套餐激活检查与流量重置调度(`scheduler.go` 的 `processActivationTasks`)不属于卡轮询,保持现有逻辑,随调度器改造迁入分发器所在进程的定时动作,行为不变。
分工原则:**Redis 是唯一权威状态,NSQ 只是传输**。NSQ 的延迟消息上限受 `max-req-timeout` 限制(默认 1 小时),不支持去重、不保证顺序、没有全局限流,因此长延迟调度、同卡去重与串行、执行上限、QPS 限流、设备锁都留在 Redis;NSQ 承担执行分发、消费者并发控制与执行超时重投。
#### 3.1 NSQ topic 与消费者
| topic | 内容 | 消费者 |
|---|---|---|
| `polling.stop_resume.{cid}` | 停复机指令 | 专用消费者,与卡任务分开,保证停复机不排在卡任务后面 |
| `polling.card.{cid}` | 卡任务 | 普通消费者 |
| `polling.device_eval` | 设备维度判断 | 设备判断消费者 |
- 每个运营商账户独立 topic,channel 统一为 `worker`;慢账户只积压在自己的 topic,不影响其他账户。
- 消息体:卡 ID(或设备 ID)、运营商账户、派发 token、派发时间。
- 每个 Worker 进程按配置订阅 topic,`max_in_flight` 控制该进程对该账户的并发:`polling.card.{cid}` 在 `scheduler_mode = carrier` 时订阅全部账户;`polling.stop_resume.{cid}` 与 `polling.device_eval` 在 `stop_resume_queue_enabled` 开启后订阅全部账户(见第 9 节)。运营商账户新增、停用或配置变更时随配置刷新动态订阅、取消订阅。
- NSQ 消息超时(`msg_timeout`)大于对应任务的执行超时;长任务执行中用 `Touch` 延长。
- 部署:nsqd + nsqlookupd,消费者经 nsqlookupd 发现 nsqd;topic 由分发器首次发布时自动创建。
#### 3.2 分发器(每秒,Worker 进程内,多实例安全)
领取范围:卡任务在 `scheduler_mode = carrier` 时领取全部账户;停复机指令与设备判断在 `stop_resume_queue_enabled` 开启后领取全部账户(见第 9 节)。每个账户每秒只由一个分发器实例领取:领取前抢账户分发锁 `polling:carrier:{cid}:dispatch_lock`(`SET NX PX`,TTL 略小于分发间隔,值为实例 token),抢到的实例执行本轮领取,其余实例跳过该账户。避免多个 Worker 实例按同一个"本秒剩余 QPS"各领一遍、领到实例数倍。各账户的锁相互独立,多个实例可以分担不同账户。
抢到锁后执行一次 Lua 原子领取(停复机指令与卡任务分属两个开关,未开启的部分跳过):
1. 停复机指令:先清理 `sr_running` 中过期成员;领取数 = min(停复机所在限流组本秒剩余 QPS, `sr_inflight_limit − ZCARD(sr_running)`);取 `stop_resume` 中 score ≤ now 的卡,先校验单卡最小重试间隔:`sr_last_call + 单卡最小重试间隔 > now` 的不领取,把 score 推后到可调用时间;其余逐个 `SET sr_claim token NX PX 租约`,成功者推后 score、写入 `sr_running`,并记下指令当前版本号 `ver` 随消息发布。执行器实际调用上游前写 `sr_last_call = now`。
2. 卡任务:先清理 `running` 中过期成员;领取上限 = `inflight_limit − ZCARD(running)`;先 priority 后 queue,priority 领取数不超过本轮领取上限 × `priority_max_ratio`(为空表示不限),剩余名额给 queue,queue 不足时 priority 可补满,避免读入口与批量业务事件长时间占满账户 QPS、饿死普通轮询;只取已到期的卡。按卡累计预计调用数:读该卡 `due`,统计本次已到期且需调网关的检查类型(卡状态、流量、实名;未开实名管控的账户不计实名),计入各类型所属限流组;任一限流组累计达到该组本秒剩余 QPS,或领取数达到领取上限,即停止领取。逐个 `SET claim token NX PX 租约`,成功者推后 score、写入 `running`。领取不占用限流名额,执行时仍由网关限流器把关;按预计调用数领取只是避免超领后任务在限流器中空等。
3. 设备判断:不分账户,由抢到 `polling:device_eval:dispatch_lock` 的实例领取;取 `device_eval:queue` 中 score ≤ now 的设备,逐个 `SET eval_claim token NX PX 租约`,成功者推后 score。
4. 写标记失败(已有处理中标记,说明正在处理):跳过,并把 score 推后到该标记剩余 TTL 之后。
5. 领取结果发布到对应 topic;发布失败用独立短超时 ctx 按 token 删除处理中标记并把 score 恢复为 now;恢复也失败则等处理中标记 TTL 到期后自然被重新领取。
执行上限是全局的:领取时校验 `ZCARD(running) < inflight_limit`(停复机为 `ZCARD(sr_running) < sr_inflight_limit`),无论部署几个 Worker 实例,同一账户同时执行的卡任务数都不超过配置值。
执行上限与消费能力的约束:执行上限不得大于该账户所有订阅进程的 `max_in_flight` 之和,否则领出的消息在 NSQ 中排队,排队时间超过租约后处理中标记到期、卡被重新领取,NSQ 中堆积过期重复消息。卡任务为 `inflight_limit ≤ Σ card_max_in_flight`,停复机为 `sr_inflight_limit ≤ Σ stop_resume_max_in_flight`。保存配置时按当前订阅进程数校验并提示;运行中由分发器每轮比较,不满足时按 Σ `max_in_flight` 收紧本轮领取上限并上报监控告警。
#### 3.3 消费与幂等
1. 消费者收到消息后,先核对 Redis:对应处理中标记存在且值等于消息中的派发 token,才执行;否则说明是过期或重复投递(标记已到期并被重新派发),直接 `FIN` 丢弃。
2. 执行(卡任务见第 5 节,停复机指令见第 6 节,设备判断见第 6.1 节)。
- 租约续期:执行期间每隔"租约时长 / 3"(系统参数,见 7.5 节)执行一次续期 Lua:校验处理中标记的值仍为本 token,是则 `PEXPIRE` 延长租约,并把该卡在队列中的 score、`running` / `sr_running` 中的到期时间同步推后;同时 `Touch` NSQ 消息。续期发现 token 已不一致(标记已到期并被重新派发)时,立即取消后续步骤(尚未发起的网关调用不再发起),按第 4 条只写已产生的业务结果。卡任务串行多个步骤、每步都可能在限流器中等待到单步超时,总时长可能超过单个租约,必须续期才能保证同卡串行。
- 执行总时长上限:卡任务总超时 = 各步骤超时之和 + 余量(系统参数),到达后取消剩余步骤,按失败路径收尾;续期最多延长到总超时,进程卡死时租约仍会到期。
3. 执行结果一律先写回 Redis,再 `FIN`。收尾 Lua:校验 token → 删除处理中标记 → 从 `running` / `sr_running` 移除 → 写回 `due` 与失败计数 → 按下次执行时间(成功为检查间隔,失败为退避间隔)设置 score。停复机指令收尾另比较指令版本号:与领取时记下的 `ver` 相同,成功或结束时才移除指令;不同说明执行期间有新指令覆盖(如停机执行中客户付费产生复机指令),保留新指令、失败计数按新指令重新计算,并把 score 设为 max(now, 本卡 `sr_last_call` + 单卡最小重试间隔)。重试与退避由 Redis 的 score 表达,不使用 NSQ 的 `REQ` 做业务重试。
4. 收尾时 token 不一致(标记已到期且已被重新派发):只写入本次执行产生的业务结果,不改 score、不动处理中标记。
5. 消费者崩溃或执行超时未 `FIN`:NSQ 在 `msg_timeout` 后重投,处理中标记仍有效则重新执行;处理中标记 TTL(租约)大于 `msg_timeout` × 允许的重投次数,NSQ 消息丢失(如 nsqd 异常)时由标记到期兜底。NSQ 重投时原消费者可能仍在执行(如进程假死后恢复),新消费者核对 token 一致也会执行;为此消费者执行前先 `SET polling:card:{id}:exec token NX PX 续期间隔×2` 抢执行权,抢不到说明同一 token 已有执行者,直接 `FIN`,执行权随续期一起延长。
#### 3.4 其他定时动作(每秒,Worker 进程内)
1. 消费手动触发队列与优先提示(见第 8 节)。
2. 统计各账户 `running` / `sr_running` 中过期成员数(处理中崩溃或超时的次数)并上报监控。
3. 写分发器心跳。
#### 3.5 进程生命周期
- 每个任务有执行超时与 panic 恢复;panic 视同失败,按失败路径写回。
- 优雅退出:先停止分发与订阅,等待执行中的消息在宽限期内完成并 `FIN`;未完成的由 NSQ 重投或处理中标记到期后重新领取。
### 4. 网关 QPS 限流
- 生效范围:所有自动触发的检查与停复机(轮询、业务事件与读入口请求检查、激活前流量结算、各自动入口生成的停复机指令)都受运营商账户限流约束;只有后台人工点击的停复机、通道阈值、自动续费、手动刷新不限流。实现上**默认限流、显式豁免**:gateway Client 外层限流器对卡的 5 个操作一律限流,只有上述 4 个入口在 ctx 中打"豁免限流"标记(带豁免来源,便于监控统计豁免调用量)。这样以后新增的自动入口忘记处理时仍受限流,不会出现漏网的不限流调用。限流组按**目标卡**的 carrier_id + 操作类型查找(设备停复机拆分后每张卡各自查找)。
- 计量单位:按**每次实际发出的 HTTP 请求**扣额度,而不是按方法调用。gateway Client 一次方法调用内部最多重试 `maxRetries` 次(默认 2,共 3 次请求,仅对超时、连接失败等网络错误重试,`internal/gateway/client.go:141`),若只在方法入口扣一次,重试的请求会漏计。限流器挂在现有逐次尝试钩子 `AttemptObserver.BeforeAttempt` 上(每次 HTTP 尝试前调用),每次尝试各自取名额;拿不到名额时按所在模式等待或立即返回,立即返回时本次方法调用结束,不再发起后续尝试。
- 算法:滑动窗口。Lua 删除 1 秒前的记录后判断 `ZCARD < max_qps`,满足则记录并放行,否则返回需等待的毫秒数。
- 等待:按返回毫秒数等待后重试,总等待不超过所在步骤的超时;超时返回"限流等待超时"错误。在 Asynq handler 内调用时使用立即返回模式,不等待(见第五部分第 3 节第 1 步说明)。
- 高优先级操作(由限流组配置,默认停机、复机),仅在与其他操作同组时生效:
- 普通操作最多用到 `max_qps − reserved_qps`,高优先级操作可用满。
- 高优先级请求等待期间登记 `high_waiting`,大于 0 时普通操作拿不到新名额。
- 全局组:若配置了全局组,每次调用同时检查运营商账户组与全局组,两者都满足才放行。
- 分发器领取时读取的"本秒剩余 QPS"即同一窗口,口径一致。
- 多 Worker 共用 Redis,限流全局生效。
- 未被任何启用的限流组覆盖的操作(含所在组已停用)使用默认 QPS,不存在不限流的自动调用。
### 5. 卡任务
1. 读卡缓存和 `due`,找出已到期的检查类型。
2. 按配置的步骤顺序串行执行(默认 卡状态 → 流量 → 实名 → 套餐,见 7.3)。原 4 个 handler 的核心逻辑拆成步骤函数:
```go
type StepInput struct {
Card *CardSnapshot
Result *GatewayResult // 可选:外部已取得的查询结果,非空时跳过网关查询
}
step(ctx, input) (nextDue time.Time, err error)
```
- `Result` 为后期批量查询、推送回调预留:查询与"观测入账 + 规则判断"分离,有外部结果时直接复用后半段。
- 每步单独超时;某一步失败只影响本步,按 6.2 节记录失败并计算退避后的 nextDue,后续步骤照常执行。
- 限流等待超时:本步 nextDue 设为短延迟(可配置),不计失败。
- 套餐步骤:本轮流量步骤已触发评估时可跳过(可配置)。
3. 对应步骤沿用现有优先轮询认领与收尾逻辑(`internal/task/polling_priority_claim.go`)。
4. 收尾 Lua(见 3.3):写回各类型 `due` 与失败计数,删除处理中标记,按最早 nextDue 设置该卡在 queue 中的 score;有优先标记则改放 priority。
5. 保留卡流量同步锁,用于与手动刷新互斥。
6. 检查间隔沿用轮询配置(`MergedTaskIntervals`,按卡匹配,含第 11 节分层条件)。
### 5.1 业务事件触发检查(替代卡观测序列)
业务事件不再起观测序列,改为把卡的对应检查设为立即到期并放进优先队列,统一走卡任务。业务事件、轮询、优先轮询为同一入口,不会重复查。
1. 请求检查:业务事件提交后调用"请求检查(卡、检查类型、场景)",一次 Lua:把 `due[type]` 设为 now,卡放入所属运营商账户的 `priority`;卡正在执行时打优先标记(同第 8 节优先轮询)。同一张卡多次请求只合并为一次,不新增队列成员。
- 冷却:场景配置了冷却时长(`cooldown`,见 7.6 节)时,该检查类型最近一次成功检查距今未超过冷却时长则不请求(Lua 内读 `due` 中的最近成功时间判断)。读入口场景应配置冷却,避免 C 端用户反复刷新页面持续占用优先队列;订单支付、套餐激活等业务事件场景通常不配冷却。
2. 执行:分发器按"停复机 > 优先 > 普通"领取,经运营商账户限流与执行上限,按卡任务步骤串行执行,失败按 6.2 节退避。
3. 延迟确认:需要"过几分钟再确认一次"的场景,按配置在本次检查完成后追加一次延迟检查:该类型下次到期 = min(正常间隔, 当前 + 确认延迟)。确认延迟按场景配置(可为空、一次或多次);观测结果已满足预期(如停机后已是停机状态)时取消后续确认。
4. 场景配置(后台,全局):
| 字段 | 说明 |
|---|---|
| scene | 业务场景:订单支付、套餐激活、停复机成功、设备操作、自动续费购包等 |
| check_types | 需要检查的类型(状态 / 流量 / 实名) |
| confirm_delays | 延迟确认序列,如"3 分钟";为空表示只立即检查一次 |
| cooldown | 冷却时长:最近一次成功检查未超过该时长则不请求;为空表示不冷却 |
5. 业务事件入口(第一部分 5.1 节列出的 5 处)改为请求检查;设备操作按设备下各卡分别请求检查。
6. 读入口(C 端资产详情、后台资产实时状态、实名链接)同样改为请求检查;OpenAPI 查询保持不触发任何检查,不再起观测序列;页面照常展示数据库中的数据。同一张卡反复打开页面只合并为一次检查,冷却时长内不再请求,受运营商账户限流约束。读入口场景默认不配置延迟确认,应配置冷却。
7. 设备信息同步(`query_device_info`,非运营商上游)不在本节范围,保持现状。
8. 效果:批量下单 27 笔、约 70 张卡,只产生约 70 次立即检查(加按配置的确认检查),并按各运营商账户 QPS 平滑执行,不再形成单秒波峰;与优先轮询不再重复。
### 6. 停复机指令
生成:
- 统一判断函数:输入卡与资产当前数据,输出目标状态与停机原因或"不动作",按第 12 节口径(暂停轮询 → 停机条件 → 复机条件 → 通道阈值锁)。`EvaluateAndAct`、`resumeSingleCard`、`resumeDeviceCards`、`ResumeCardIfStopped` 都改为调用它,不再各自判断。
- `EvaluateAndAct` 改为只判断、不执行:判断出需要停机或复机即生成指令。
- 调用方(只请求评估,不调网关):
- 套餐步骤、Outbox 三个卡观测消费者(流量增加、网络状态变化、实名变化)。Outbox 消费者只负责扣减与请求评估,不再同步调网关、不 sleep 重试;"流量用完停机"由此受运营商账户限流约束(2026-10-22 已定)。
- 套餐激活、流量重置、订单支付后:去掉裸 goroutine,在业务事务提交后请求评估(`ResumeCardIfStopped` 改为请求评估)。请求本身只写 Redis,失败时记录日志并由该卡下一次套餐步骤兜底。
- 套餐到期(第 11.5 节到期即停)。
- 退款后资产处理:不再调用 `ManualStopCard`,改为请求评估;资产无可用主套餐时按 `no_package` 生成停机指令(设备按设备维度判断)。请求评估写入成功即视为退款资产后处理完成(标记 `asset_reset`),停机本身的失败由停复机指令的退避重试与告警处理,不再触发 Outbox 重投与补偿扫描反复补发。
- 运营商账户实名管控修改(`internal/service/carrier/service.go`):保存后对该账户下受影响的卡批量请求评估,按账户 QPS 平滑执行。0 → 1 筛出在线且未实名的卡;1 → 0 筛出停机且未实名的卡。设备卡按设备请求设备维度判断。
- 卡或设备恢复轮询:不另加触发。生命周期服务恢复轮询时(现有 `OnCardEnabled`,`internal/polling/lifecycle_service.go:116`)把各检查类型 `due` 设为当前时间加少量抖动,套餐步骤随即执行评估。
- 单卡维度:在调用方当场判断,生成该卡的指令。
- 设备维度:由卡找到绑定设备,不在调用方当场判断,改为请求一次设备维度判断(见第 6.1 节),由设备判断任务统一生成设备下每张卡的指令,每条进入该卡自身所属运营商账户的队列。
- 同卡同一时刻只保留一条指令,新指令覆盖旧指令;方向相反时以最新判断为准,失败计数清零。每次生成或覆盖指令都递增指令版本号 `ver`;指令正在执行时也可以覆盖,执行完的收尾按版本号判断是否移除(见 3.3 节第 3 条),保证执行期间生成的新指令不会被收尾删掉。
执行(NSQ 消费者收到 `polling.stop_resume.{cid}` 消息后执行):
1. 执行前按规则重新判断,已是目标状态或条件不再满足则结束,指令从 `stop_resume` 移除。
2. 调网关只调用一次,不在执行中 sleep 重试,也不使用 gateway Client 的内部重试:停复机是外部状态写入,超时或连接失败时上游可能已经受理,内部重试会在几百毫秒内对同一张卡连发 2~3 次,正好撞上上游单卡频率限制("3 分钟内同一张卡相同操作仅允许一次""卡状态变更每十分钟只允许调用 1 次")。现状 `StopCard` / `StartCard`(`internal/gateway/flow_card.go:30-40`)沿用默认 `maxRetries = 2`,改为与限速接口 `SetCardSpeedTier` 相同的 `maxRetries = 0`;该改动对所有停复机入口生效(含后台人工点击、通道阈值、自动续费),人工入口失败由用户重新操作。超时、连接失败按"结果未知"处理:置待确认标记,下次执行前先查卡状态,已是目标状态则结束指令,否则按单卡最小重试间隔再调用。
3. 成功:沿用现有回写(卡状态、停机原因、网络状态序列、审计);指令版本号与领取时一致才从 `stop_resume` 移除,否则保留执行期间生成的新指令(见 3.3 节第 3 条)。
4. 失败:按 6.2 节分类处理。可重试的失败指令保留在 `stop_resume`,score = max(当前时间 + 退避间隔, 本卡上次调用停机或复机的时间 + 单卡最小重试间隔);达到告警阈值后写失败告警,指令**不丢弃**,按最长退避间隔继续重试(停机失败意味着卡可能仍在跑流量)。上游终态不可操作的不再重试(见 6.2 节)。
5. 结果未知(超时、连接失败、上游返回已受理类频率限制):不沿用现有恢复扫描。现有普通停复机的结果未知只有人工核对策略(`pkg/constants/card_observation.go:135` `GatewayCardCommandUnknownRecoveryStrategy`),通道阈值、自动续费各有专项恢复,都不能直接复用。指令队列内的完整路径:
1. 置待确认标记,记下本次调用时间;指令保留在 `stop_resume`,score = now + 确认延迟(按运营商账户配置 `stop_resume_confirm_delay`,见 7.2 节)。
2. 再次领取时,先查一次卡状态(查状态受限流,计入停复机所在限流组;不受单卡最小重试间隔约束,因为查询不改变上游状态):
- 已是目标状态:按成功回写,结束指令,记录结果为"确认成功"。
- 不是目标状态:清除待确认标记;距本卡 `sr_last_call` 已满单卡最小重试间隔则本次直接重新调用停复机,否则 score 推后到可调用时间。
- 查状态失败:保持待确认,按查询退避间隔重试,不发起停复机调用。
3. 连续结果未知(含确认查询失败)次数达到告警阈值,按 6.2 节写失败告警,错误类型为"结果未知",指令不丢弃。
4. 执行前的规则重新判断仍在查状态之前进行:条件已不满足(如期间客户付费不需要停机)则结束指令,不再确认。
单卡最小重试间隔:上游按单卡限制停复机频率(生产 2026-10-22 实测返回"3 分钟内同一张卡相同操作仅允许一次""5 分钟内最多重复调用 3 次""卡状态变更每十分钟只允许调用 1 次")。停复机指令对同一张卡的两次停复机网关调用(停机与复机合计,不分操作)间隔不得小于"单卡最小重试间隔"(按运营商账户配置,见 7.2 节);按卡合计是因为上游"卡状态变更每十分钟只允许调用 1 次"对停机、复机共同计数,例如停机后几分钟内购买套餐触发复机也会被拦截,领取时校验,未到间隔则把 score 推后到可调用时间,不发起调用。
不变的部分:后台人工点击的停复机(用户在等结果)、通道阈值(有独立可靠任务与锁)、自动续费调用的停机、复机接口照旧直接执行,不进队列、不限流。
好处:
- 不风暴:执行前按目标状态重新判断,已停机的卡不再调停机接口;业务流程(如退款)只负责请求评估,不再因上游停机失败被整体重试。
- 不翻转:同卡只有一条指令、新覆盖旧,执行前重新判断;激活复机与流量入账停机同时发生时以最新数据为准。
- 不丢:激活、重置、订单后的复机失败退避重试,持续失败进告警,不再只打日志。
- 不超频:流量重置日集中复机按运营商账户 QPS 平滑执行;停复机预留 QPS、优先出队。
- 规则只有一处:所有自动入口共用同一判断函数。
- 代价:停复机比现在晚约 1~2 秒(每秒领取、优先出队)。
#### 6.1 设备维度判断(Redis 延时队列 + 锁 + NSQ 分发)
问题:设备下多张卡(通常分属不同运营商账户)的卡任务、Outbox 消费者可能同时做设备维度判断。例如卡 A 流量入账后设备流量用完、判断整机停机,同时卡 B 读到扣减前的数据判断可以复机,后者覆盖前者,导致停复机翻转或设备下卡状态不一致。设备套餐的流量扣减已在数据库层加行锁(`internal/service/package/usage_service.go:345`),冲突只在设备维度的停复机判断。
设计:Redis 延时队列负责排队、去重与合并,处理中标记保证同一设备同一时刻只有一个判断,设备锁负责与停复机指令执行器的重新判断互斥。
1. 请求判断:卡任务(套餐步骤)、Outbox 三个卡观测消费者、套餐到期、退款等需要做设备维度判断时,不当场判断,而是一次 Lua:`INCR eval_ver`,把本次请求的场景 `SADD` 进 `polling:device:{id}:eval_scenes`,并 `ZADD LT polling:device_eval:queue now {device_id}`(不存在则加入,存在则只会把 score 提前)。同一设备只有一个队列成员,多次请求自然合并,场景按并集合并、不丢失。
- 场景合并的意义:暂停轮询的设备只对套餐失效场景(到期、退款)放行停机(第 12 节)。若只按设备 ID 合并、不保存场景,"到期"请求与普通"轮询"请求合并后场景丢失,判断时会按暂停轮询拒绝停机,造成漏停。
- 领取时随消息带上当时的场景集合;收尾 Lua 只从 `eval_scenes` 中移除本次已处理的场景(`SREM`),判断期间新加入的场景保留,与 `eval_ver` 一起触发再判断一次。
2. 领取与分发:分发器取 score ≤ now 的设备,`SET eval_claim token NX PX 租约` 成功者推后 score,并记下领取时的 `eval_ver`,随消息发布到 NSQ `polling.device_eval`。同一设备同一时刻只会被一个消费者判断。
3. 执行判断:
1. 抢 `polling:device:{id}:eval_lock`(SetNX + token + TTL)。
2. 读取设备最新数据(设备套餐、流量、设备下各卡的网络状态与实名状态、各卡所属运营商账户的实名管控),按第 12 节口径判断;实名按卡逐张判断。暂停轮询这一步按场景集合判断:集合中含套餐失效场景(到期、退款)时,停机方向放行。
3. 需要停复机时,为设备下每张卡写停复机指令(指令记录触发它的场景,供执行前重新判断沿用),进入各卡所属运营商账户的停复机队列。
4. 按 token 释放锁;收尾 Lua 删除处理中标记,并比较当前 `eval_ver` 与领取时记下的版本:相同则把设备从 `device_eval:queue` 移除;更大说明判断期间有新请求,保留并把 score 设为 now,用最新数据再判断一次。
4. 约束:
- 锁内不调网关,真正的停机、复机由停复机指令执行,锁持有时间为毫秒级。
- 多次判断请求合并为"基于最新数据的最后一次判断",不丢失、不交错。
- 消费者崩溃时,锁 TTL 到期释放;NSQ 超时重投,或处理中标记到期后设备被重新领取判断。
5. 停复机指令执行器执行设备下某张卡的指令前重新判断时,涉及设备维度条件的同样经由此锁读取,读到不再满足则结束。
6. 设备下不同卡的停复机指令可以并行执行,各自独立调用上游。
#### 6.2 失败处理与告警(卡任务各步骤、停复机指令通用)
0. 失败原因与调用量记录(失败分类与告警的前提)
- gateway Client 返回结构化错误:错误类别(网络 / 超时 / HTTP 异常 / 响应无效 / 上游业务错误)、网关业务码与信息、耗时;不再只拼在错误字符串里。
- 现状:上游返回的错误信息目前只在统一审计表 `tb_audit_event` 中停复机动作(`action_code` 为 `iot_card.auto_stop`、`iot_card.auto_start`、`iot_card.manual_stop` 等)的 `error_summary` 中可见(如 `Gateway 业务错误: code=400, msg=...`),查询类调用不写审计,集成日志中为空;网关对各类错误统一返回 code=400,分类需按返回信息匹配。统一审计表与集成日志(生产约 1,500 万行)数据量大、积压严重,不再承载轮询与自动停复机的调用记录。
- 停复机:每次实际调用上游停机或复机写入单独的停复机记录表 `tb_card_stop_resume_record`(见下方),系统自动停复机不再写统一审计与集成日志;后台人工点击的停复机仍写统一审计(操作人审计职责),同时写停复机记录。
- 查询(状态、流量、实名):失败不逐条落库,不单独建表。按"运营商账户 × 操作 × 结果类别"在 Redis 做分钟级计数与耗时分布,供监控计算成功率、实际 QPS、p95 耗时;每张卡在 `due` 中保留各检查类型最近一次错误(类别、码、信息、时间);持续失败达到阈值的写入失败告警表 `tb_polling_failure_alert`(第 3 条)。
- 分类规则(错误信息关键字 → 类别)作为配置维护,可后台增补,不写死在代码中。
- 用途:区分限频、卡错误与超时,作为 6.2 失败分类、告警与各运营商账户 QPS 配置调整的依据。
停复机记录表 `tb_card_stop_resume_record`:
| 字段 | 说明 |
|---|---|
| card_id、iccid、carrier_id | 卡与所属运营商账户 |
| action | 停机 / 复机 |
| source、scene | 来源与场景:轮询、业务事件、退款、激活、重置、订单、实名管控修改、后台人工点击、通道阈值等 |
| reason | 停机原因 |
| command_id | 对应停复机指令,同一指令的多次尝试归为一组 |
| attempt | 尝试序号 |
| result | 成功 / 失败 / 结果未知 / 已是目标状态 / 跳过(未到单卡最小重试间隔) |
| error_category | 频率限制 / 终态不可操作 / 临时故障 / 业务错误 / 网络超时 |
| provider_code、provider_message | 上游返回码与信息(脱敏截断) |
| duration_ms | 耗时 |
| created_at | 记录时间 |
- 索引:(card_id, created_at)、(carrier_id, created_at)、(result, created_at),支持单卡历史、按账户统计失败类别、告警页跳转查看。
- 按月分区,保留期可配置,到期整区删除。主键包含 `created_at`;建 DEFAULT 分区,并由定时任务提前建好未来若干个月的分区(提前月数为系统参数,见 7.5 节),避免某月分区缺失导致插入失败。
- 记录写入与停复机状态回写不在同一事务:写记录失败只打日志并计数,不影响卡状态、停机原因等回写。
1. 失败重回队列、退避重试
- 按"卡 × 检查类型"(停复机指令按卡)记录连续失败次数、首次失败时间、最近错误。
- 失败后带着重试时间留在队列:下次执行时间 = 当前时间 + 退避间隔,退避间隔随连续失败次数逐级拉长(序列可配置),最长不超过该检查类型的正常检查间隔。
- 成功一次即清零。
2. 失败分类
| 类型 | 例子 | 是否计入连续失败 |
|---|---|---|
| 限流等待超时 | 本账户 QPS 用满 | 不计入:属于自身限流,不是卡的问题 |
| 网络或超时 | 上游超时、连接失败 | 计入 |
| 上游业务错误 | 卡不存在、卡不属于该账户、账户无权限、"当前用户不允许办理""防范实名" | 计入;可配置为首次出现即告警;不视为已是目标状态 |
| 账户配置错误 | "密码错误""参数缺失" | 计入;首次出现即产生账户级告警(通常是账户凭证或接入参数问题,影响该账户全部卡),不视为已是目标状态 |
| 上游频率限制 | "操作进行中,3 分钟内同一张卡相同操作仅允许一次""调用成功-5 分钟内最多重复调用 3 次""调用成功-卡状态变更每十分钟只允许调用 1 次""请求被合并,以最新一次为准""超频访问" | 不计入:按单卡最小重试间隔与上游窗口退避;返回含"调用成功""操作进行中""请求被合并"的,上游可能已受理,下次执行前先查卡状态确认,已是目标状态则结束指令 |
| 上游终态不可操作 | "当前用户已销户,无法操作""当前卡为风险停机状态,仅支持风险复机""用户状态是物联网号码封存,禁止办理物联网停机" | 不重试:结束指令,写失败告警(错误类型为终态);已销户、风险停机类自动关闭该卡轮询(第 12 节),其余终态建议运营关闭该卡轮询转人工;停机方向且上游已不可用的,按目标状态视为已停 |
| 上游临时故障 | "湖北省网获取到的 token 为空""请求失败" | 计入,按普通退避重试 |
| 上游表示已是目标状态 | 停机时明确返回已停机、复机时明确返回已开机 | 不计入:视为成功,结束停复机指令并按目标状态回写;只收录明确表示卡已处于目标状态的返回,具体错误码按失败原因落库后的统计整理,作为配置维护。不能以老系统的"结束停机任务"作为依据:老系统 `TingjiViewComp.java:255-271` 把"已存在""当前用户不允许办理""防范实名""参数缺失""密码错误"都置为 `tingjiOk` 并结束任务,但停复机记录 `status` 仍记为失败(2);电信卡只要停机或断网(达量)任一成功即结束任务(第 308 行)。这些只代表老系统不再重试,不代表停机成功 |
3. 告警
- 触发条件(可配置):连续失败次数达到阈值,或持续失败时长达到阈值,或命中"首次即告警"的错误。
- 写入失败告警记录(新表 `tb_polling_failure_alert`):卡、运营商账户、检查类型(或停复机)、连续失败次数、首次与最近失败时间、最近错误、状态(未处理 / 已恢复 / 已关闭轮询)、处理人与处理时间。同一卡同一检查类型只保留一条未关闭的告警,后续失败更新计数。
- 通知走现有告警通道(`internal/service/polling/alert_service.go`)。
- 告警后卡继续按最长退避间隔轮询,不自动停止;上游恢复后首次成功即清零,告警自动转为"已恢复"。
4. 运营处理
- 联系上游:无需在系统操作,恢复后自动关闭告警。
- 加入不轮询:告警页一键或勾选批量关闭该卡(或其设备)的 `enable_polling`(13.1 节),写审计与不轮询清单,告警转为"已关闭轮询";生命周期服务据此将卡移出轮询(`ShouldEnqueue`)。停机被拒告警单独成列表并可导出(13.3 节)。
- 关闭轮询的影响按第 12 节(沿用老系统不轮询名单口径):不再查上游,流量用完、实名不满足不自动停机,激活、流量重置不自动复机;套餐到期、退款后无套餐仍自动停机;订单套餐生效、后台改有效期后有生效套餐会自动恢复轮询并按规则复机(风险停机、已销户的卡除外);人工停复机照常。关闭设备时设备下所有卡同样适用。告警页与关闭轮询的确认框须明确提示上述影响。
5. 账户级汇总
- 告警列表支持按运营商账户、错误类型汇总。
- 同一运营商账户在时间窗口内的失败告警数量超过阈值时,额外产生账户级告警:通常是账户本身问题(额度、凭证、上游故障),应联系上游处理账户,而不是逐卡处理。
### 7. 配置
原则:只提供灵活的配置位置,具体数值与分组由运营按实际情况配置;后台配置修改后同步 Redis,下一轮调度即生效,无需重启。
#### 7.1 限流组(后台,按运营商账户)
新表 `tb_carrier_rate_limit_group`:
| 字段 | 说明 |
|---|---|
| carrier_id | 运营商账户;为空表示全局组(可选,用于聚合网关总限流,不配则不生效) |
| group_code / group_name | 组标识与名称 |
| max_qps | 该组每秒请求上限 |
| operations | 组内操作:查流量 / 查状态 / 查实名 / 停机 / 复机 |
| high_priority_operations | 组内高优先级操作(默认停机、复机) |
| reserved_qps | 预留给高优先级操作的额度 |
| status | 启用 / 停用;停用后组内操作回落为默认 QPS,不是不限流 |
示例:联通配两组(查询:查流量/查状态/查实名;停复机:停机/复机);广电配一组(全部 5 个操作,高优先级为停机/复机)。
规则:同一运营商账户下每个操作只能属于一个组,保存时校验;`reserved_qps < max_qps`;高优先级操作必须属于本组操作。
#### 7.2 运营商账户调度参数(后台,按运营商账户,可选)
存储:新表 `tb_carrier_polling_param`(`carrier_id` 唯一,一个账户一行,未配置的账户没有记录、用全局默认),不改 `tb_carrier`。
| 参数 | 说明 |
|---|---|
| inflight_limit | 该账户同时执行卡任务的上限(全局,跨 Worker 实例,按 `running` 计数),不配用全局默认 |
| card_max_in_flight | 每个 Worker 进程消费该账户 `polling.card.{cid}` 的 `max_in_flight`,不配用全局默认 |
| stop_resume_max_in_flight | 每个 Worker 进程消费该账户 `polling.stop_resume.{cid}` 的 `max_in_flight`,默认 1 |
| sr_inflight_limit | 该账户同时执行停复机指令的上限(全局,按 `sr_running` 计数),不配用全局默认;须不大于各订阅进程 `stop_resume_max_in_flight` 之和(见 3.2 节) |
| priority_max_ratio | 卡任务每轮领取中 priority 的最大占比(0~1),为空表示不限;queue 不足时 priority 可补满(见 3.2 节) |
| stop_resume_min_interval | 单卡最小重试间隔:同一张卡两次停复机网关调用(停机与复机合计)的最小间隔,不小于上游单卡限制(如 10 分钟),不配用全局默认 |
| stop_resume_confirm_delay | 停复机结果未知后,过多久查卡状态确认(见第 6 节第 5 条),不配用全局默认 |
#### 7.3 卡任务步骤(后台,全局)
存储:现有受控系统配置表 `tb_system_config`(键值,`module = polling`),不新建表;7.4 的标量参数同样存放于此。
| 参数 | 说明 |
|---|---|
| step_order | 步骤执行顺序,默认 卡状态 → 流量 → 实名 → 套餐 |
| step_timeout | 每种检查类型单步超时 |
| rate_limited_retry_delay | 限流等待超时后的短延迟 |
| skip_package_after_flow | 同轮流量已触发评估时是否跳过套餐步骤 |
#### 7.4 失败处理与告警(后台,全局,见 6.2)
| 参数 | 说明 |
|---|---|
| backoff | 退避间隔序列,可按检查类型与停复机分别配置;最长不超过该类型正常检查间隔 |
| alert_fail_count | 连续失败次数告警阈值,可按检查类型与停复机分别配置 |
| alert_fail_duration | 持续失败时长告警阈值 |
| immediate_alert_errors | 首次出现即告警的上游错误类型 |
| error_classification | 上游错误信息关键字 → 类别(频率限制 / 终态不可操作 / 已是目标状态 / 临时故障 / 业务错误 / 账户配置错误)的映射,见 6.2 节;条目多、需逐条增补,单独建表 `tb_gateway_error_classification`(关键字、匹配方式、类别、适用操作、是否自动关闭轮询、启用状态;"是否自动关闭轮询"只允许终态类别勾选,用于已销户、风险停机) |
| account_alert_threshold | 账户级告警:时间窗口与窗口内失败告警数量阈值 |
#### 7.5 系统参数(yaml)
默认 QPS、默认执行上限(`inflight_limit`、`sr_inflight_limit`)、默认 `max_in_flight`、设备判断 `max_in_flight`、分发间隔、卡任务总超时(各步骤超时之和 + 余量,见 3.3 节)、NSQ 地址(nsqd / nsqlookupd)、NSQ `msg_timeout`(须大于续期间隔,执行中靠 `Touch` 延长)、处理中标记 TTL 即租约时长(须大于 `msg_timeout` × 允许重投次数)、租约续期间隔(默认租约时长 / 3)、QPS 最长等待、优雅退出宽限期、重置日前加密的收尾提前量(11.10 节)、激活前流量结算总超时(11.9 节)、停复机记录表分区提前创建月数(6.2 节)。停复机出口全局开关 `stop_resume_queue_enabled` 不放 yaml,放受控系统配置 `polling.stop_resume_queue_enabled`(默认关闭),开关与回退即时生效、无需重新部署(第 9 节、14.1 节)。
#### 7.6 业务事件检查场景(后台,全局,见 5.1 节)
存储:新表 `tb_polling_check_scene`(`scene` 唯一,一个场景一行)。
| 参数 | 说明 |
|---|---|
| scene | 业务场景:订单支付、套餐激活、停复机成功、设备操作、自动续费购包、各读入口等 |
| check_types | 该场景需要检查的类型(状态 / 流量 / 实名) |
| confirm_delays | 延迟确认序列,为空表示只立即检查一次;读入口默认为空 |
| cooldown | 冷却时长,为空表示不冷却;读入口应配置(见 5.1 节) |
### 8. 需要同步适配
| 模块 | 改动 |
|---|---|
| 优先轮询 | 数据库为准、Redis 为提示不变;下发提示改为设置 `due[type]=now` 并放入运营商账户 priority,卡在执行中则打优先标记 |
| 手动触发队列 | 接口不变;由第 3.4 节的定时动作取出后设置 `due[type]=now` 并放入运营商账户 queue(score=now),走普通通道 |
| Initializer | 按各类型 last_check_at 计算 `due`,以最早时间写入运营商账户 queue |
| 生命周期 | 增删卡、卡状态变化时操作该卡所属运营商账户的各队列与 `due`;恢复轮询时各检查类型 `due` 设为当前时间加抖动(沿用 `calcInitialDelay`) |
| 监控 | 按运营商账户展示各队列长度、到期数、执行中数、实际 QPS、限流等待次数与超时次数、处理中标记到期次数、停复机成功/失败/重试、失败告警数(按错误类型)。数据来源:队列与执行数读 Redis;查询成功率、QPS、耗时读 Redis 分钟计数;停复机结果读停复机记录表 `tb_card_stop_resume_record`;持续失败读失败告警表 `tb_polling_failure_alert` |
| 后台 | 并发配置页改为限流组配置页;新增运营商账户调度参数、步骤与失败告警参数配置;新增失败告警页(按账户与错误类型汇总、一键关闭轮询,停机被拒视图与导出);新增不轮询清单页、批量开关轮询与文件导入(第 13 节);卡、设备列表增加是否轮询筛选;资产页去掉保护期展示 |
| 开关轮询入口 | 单资产接口、风险停机或已销户自动关闭、设备级联、订单套餐生效与改有效期的自动恢复,同一事务写不轮询清单 `tb_card_polling_pause`(13.2 节) |
### 9. 切换(不灰度,整体切换)
原则(2026-10-24 已定):不按运营商账户、设备或卡灰度。每个 change 上线时对全部运营商账户整体生效,先在测试环境验证,再上生产。只保留全局开关,用于出问题时整体回退,不用于逐步放量。
| 全局开关(受控系统配置,后台即时生效,见 14.1 节) | 所属 change | 开启 | 关闭(回退) |
|---|---|---|---|
| `polling.rate_limit_mode`(`observe` / `enforce`) | 1 | 拦截:按限流组执行 | 只统计:计数但不拦截 |
| `polling.scheduler_mode`(`legacy` / `carrier`) | 5 | 全部卡任务走新调度(按账户队列 + NSQ) | 全部回到旧分片调度 |
| `polling.stop_resume_queue_enabled`(bool) | 6 | 全部自动停复机经指令队列与设备判断 | 各自动入口恢复当场执行 |
- 新 key 前缀,与旧 key 不冲突;新旧调度不双跑:任一时刻只有 `scheduler_mode` 指定的一套调度在领取与执行。
- 入口写入:所有写入轮询结构的入口(Initializer、生命周期、优先提示、手动触发、业务事件与读入口请求检查)按 `scheduler_mode` 写新结构或旧结构,不再按账户分流。
- 切到新调度(`legacy` → `carrier`):
1. 旧调度器停止出队;旧 handler 执行前检查模式,已切换则直接结束、不重入旧队列(处理 Asynq 中已排队的任务)。
2. 从数据库按批初始化全部账户的新结构(`due` 与各账户 queue);初始化期间新分发器不领取,初始化完成后开始领取。初始化按 98,430 张卡规模估算耗时,在测试环境实测后写入上线步骤。
3. 初始化后各卡到期时间按 last_check_at 计算,已逾期的卡按账户 QPS 与执行上限逐步领取,不形成波峰。
- 回退(`carrier` → `legacy`):新分发器停止领取,执行中的任务按收尾规则完成;按数据库重新初始化旧分片队列,旧调度恢复出队;新结构保留不删,再次切换时重新初始化覆盖。
- 停复机出口开关关闭(回退):停止领取 `stop_resume` 与 `device_eval`,各自动入口恢复旧的当场执行;队列中未执行的指令保留,重新开启后继续执行,执行前按规则重新判断,过期指令自然结束。开关切换时正在执行的指令按收尾规则完成;旧路径正在执行的设备停复机仍持现有设备锁 `RedisPollingDeviceOpLockKey`,设备判断消费者执行前同样检查该锁,持有时 score 推后、不并行执行。
- 跨账户设备:生产 2026-10-24 实查,有效绑卡设备 20,109 台,其中 11,607 台(约 58%)的卡分属不同运营商账户。整体切换下同一设备的卡始终走同一套调度与同一个停复机出口,不存在一半新一半旧;仍作为测试环境核心验收场景:设备下各卡分属不同账户时,停复机全部经指令队列、各卡最终状态一致,开关开、关、再开过程中无重复停复机与漏停。
- 稳定运行后删除 `polling:shard:*`、`polling:priority:*`,下线旧调度代码与 `scheduler_mode` 开关。
不灰度的代价与对应措施:
- 新调度一旦有问题,影响全部 9 万张轮询卡。措施:测试环境按生产规模压测(批量造卡或回放生产卡 ID),覆盖第五部分测试要求全部场景后再上生产;上线后首日重点监控各账户队列积压、执行中数、处理中标记到期次数、停复机成功率,异常时用全局开关回退。
- 限流参数没有逐账户试运行的机会。措施:change 1 先以 `observe` 上线采集至少一周数据,按数据配好全部账户的限流组后,再整体切到 `enforce`。
### 10. 新方案对现状问题的处理
| 现状问题 | 处理方式 |
|---|---|
| 并发不以上游账户为单位、数值无依据 | 运营商账户限流组,数值由运营配置 |
| 背压按 ZCARD 判断 | 删除;按剩余 QPS 与执行上限领取,积压只留在 ZSET |
| 出队后崩溃丢卡 | 卡始终留在队列,处理中标记带 TTL,崩溃后标记到期自动重新领取 |
| 持续失败无人处理 | 退避重试 + 失败告警 + 账户级汇总,运营联系上游或一键关闭轮询(6.2 节) |
| 调度超时管不住入队 | 单轮领取数受 QPS 与执行上限约束,发布量有上界 |
| 慢账户占满协程 | 每个运营商账户独立 NSQ topic 与 `max_in_flight`,轮询不再与其他业务共用 Asynq 协程池 |
| 同卡不同类型并行 | 一张卡一个卡任务,串行执行 |
| 停复机 sleep 重试、跨账户 | 停复机指令队列,按目标卡运营商账户入队,失败退避重试 |
| 保护期反复翻转 | 去掉保护期,规则优先 |
| 全量卡同频轮询、无套餐仍在跑流量 | 分层轮询 + 无套餐层必配卡状态检查 + 到期即停(第 11 节) |
| 激活、重置、订单复机裸 goroutine 当场执行 | 改为请求评估,统一由停复机指令队列执行,失败退避重试与告警(第 6 节) |
| 重置日前尾部用量丢失 | 重置日前加密查流量(第 11.10 节) |
| 失败原因与调用量不可见 | gateway 结构化错误;停复机写单独的停复机记录表(按月分区);查询失败不落库,Redis 按账户 × 操作 × 类别计数 + 卡上保留最近错误 + 持续失败进告警表(6.2 节第 0 条) |
| 业务事件观测序列三连查、不限流、与优先轮询重复 | 改为请求检查,统一走卡任务与限流,延迟确认按场景配置(第 5.1 节) |
| 投递无去重、可能重复执行 | 每个账户队列中一张卡只占一个成员,优先、手动、生命周期只改 `due` 与 score;领取写处理中标记(`SET NX`)才发布,消费时核对 token;停复机指令一卡一条、设备判断按设备合并(第 2、3、6 节) |
| 退款停机走人工接口形成重试风暴 | 退款后改为请求评估,停机走停复机指令队列(第 6 节) |
| 无套餐期间用量计入新套餐 | 套餐激活前流量结算(第 11.9 节) |
| 新旧停复机规则并存、实名轮询口径不一致 | 以新规则为唯一口径,删除旧口径与总开关;实名步骤按运营商账户实名管控决定是否查询(第 12 节) |
### 11. 分层轮询
#### 11.1 目标
- 按卡当前业务状态决定轮询频率:在用套餐的卡高频,无套餐、库存卡低频巡检。
- 兜住"无套餐或套餐过期仍在跑流量"的卡,以及"库存卡在上游开机"的卡:发现开机即停机。
- 分层规则全部由配置决定,代码不写死层级与频率。
参考老系统:老系统高频轮询只覆盖有未过期套餐的卡(从 `tbl_card_life` 出发),另有全量巡检任务对无有效套餐的卡只查上游状态、开机即停,以及套餐到期即停任务。
#### 11.2 分层维度
在现有匹配维度(网络与实名状态、卡类别、运营商账户)之上新增两个:
| 维度 | 取值 | 数据来源 |
|---|---|---|
| 套餐状态 `package_state` | 有生效套餐 / 套餐已用完 / 只有待生效套餐 / 无套餐 | `package_usage`:绑定设备的卡按设备、独立卡按卡计算,口径与 `hasValidPackage` 一致(状态 0 待生效、1 生效中、2 已用完、3 已过期、4 已失效) |
| 资产状态 `asset_status` | 在库 / 已销售 / 已换货 / 已停用 | 卡表现有字段 |
#### 11.3 配置
`tb_polling_config` 新增两列 `package_state`、`asset_status`(为空表示不限)。匹配规则:按优先级遍历,每种检查类型取第一个填了间隔的配置。
间隔取值的三种含义(修正现状歧义):
| 取值 | 含义 | 合并时 |
|---|---|---|
| 正数(秒) | 按此间隔检查 | 采用,停止向下查找 |
| `0` | **不检查** | 采用(该类型不检查),停止向下查找 |
| 空(NULL) | 继承 | 跳过,继续找优先级更低的配置 |
- 现状:`MergedTaskIntervals`(`internal/polling/config_manager.go:176`)实际把 NULL 当"继承",对每种类型取最高优先级的非 NULL 间隔;但字段注释与接口文档(`internal/model/polling.go:17-21`、`internal/model/dto/polling_config_dto.go:10-14`)写的是"NULL 表示不检查",两者不一致。
- 不修正的后果:示例中"无套餐层流量 —"本意是不查流量,若填 NULL,会继承优先级更低的配置(如"未实名"层或兜底配置)的流量间隔,无套餐卡照样查流量,分层节省调用量失效。
- 处理:保持 NULL = 继承(不改变生产现有配置的行为),新增 `0` = 不检查;接口校验由 `min=30/60` 改为"等于 0 或不小于最小间隔";字段注释与接口文档改为上表口径。生产 2026-10-24 实查 7 条配置均无 0 值,引入 0 不影响现有数据。
- 下表示例中"—"即填 `0`(不检查),不是留空。
优先级:
- 后台可调整:单条修改 `PUT /polling-configs/:id` 的 `priority`;整体调整顺序用 `PUT /polling-configs/priorities`(一次提交全部配置的顺序,事务内重排,前端拖拽排序用)。
- 优先级可以重复,相同时按 ID 升序,保证匹配结果确定(现状仅按 priority 排序,相同优先级的顺序不确定;生产 2026-10-24 有 3 条配置同为优先级 1)。保存时若与其他启用配置优先级相同且匹配条件可能重叠,提示但不拦截。
- 匹配预览:`GET /polling-configs/match-preview?iccid=`,返回该卡当前的匹配维度取值(网络、实名、卡类别、运营商账户、套餐状态、资产状态)、命中的配置列表(按优先级),以及每种检查类型最终采用的间隔与来源配置(含"不检查""继承自 xx""未匹配")。调整优先级或间隔前用于确认效果。可选传入 `config_overrides`(未保存的修改)做预演。
调整后生效:
- 配置修改后,现有 Redis 通知机制让各进程立即刷新内存配置(`config_manager.go` 订阅变更通知,另每 5 分钟定时刷新);卡的层级与间隔在该卡下次执行时按新配置重新计算(11.4 节)。
- 已排好的到期时间不会自动变化:间隔从 1 天改为 1 小时,已排程的卡最多仍要等 1 天才按新间隔执行。为此提供"立即重算到期时间":保存配置时可勾选,或单独调用 `POST /polling-configs/recalculate-due`(可按运营商账户限定范围),后台异步任务按批读取受影响的卡,新到期 = min(当前到期, 上次检查时间 + 新间隔),只提前不推后(推后的情况等卡下次执行时自然生效)。重算只写 Redis 的 `due` 与 score,不调网关;提前到期的卡仍按账户 QPS 与执行上限领取,不会形成波峰。返回任务 ID,可查询进度。
配置思路示例(数值由运营配置):
| 配置 | 匹配条件 | 卡状态 | 流量 | 实名 | 套餐 |
|---|---|---|---|---|---|
| 在用卡 | 有生效套餐 | 高 | 高 | 低 | 中 |
| 已用完 | 套餐已用完 | 中 | 低 | — | 中 |
| 待生效 | 只有待生效套餐 | 低 | — | 中 | 中 |
| 无套餐 | 无套餐、已销售 | 低(必配) | — | — | 低 |
| 库存 | 在库 | 极低(必配) | — | — | 低 |
| 未实名 | 未实名 | — | — | 中 | — |
保存校验:匹配"无套餐、已销售"或"在库"的配置,卡状态检查间隔必须为正数(不得为空,也不得为 `0`)。
"未实名"层只对开了实名管控的运营商账户有意义:未开实名管控的账户,实名结果不影响停复机,实名步骤直接跳过(第 12 节),即使匹配到该层也不查实名。
#### 11.4 分层计算时机
套餐状态的修改点分散在约 15 个文件、45 处,不逐处挂钩子,改为使用时计算:
1. 每次卡任务收尾时:查询该卡当前套餐状态,匹配配置,计算各类型下次到期时间。
2. 全量初始化时:按批查询套餐状态后匹配。
3. 生命周期事件(`OnCardStatusChanged` 等)重新匹配时一并计算。
因此卡的层级最迟在下一次执行时更新。
#### 11.5 层级切换
- 升层(买了套餐):购买生效、续费生效、排队生效、加油包生效已产生优先轮询项,卡进入 priority 立即执行一次,执行时按新套餐状态重新匹配进入高频层,无需新增代码。
- 降层(套餐到期)——到期即停:在套餐到期失效处理处(`package_activation_handler.go`),若该资产已无其他有效套餐,直接以场景"套餐到期"请求停复机评估,不经过卡任务的套餐步骤:
- 独立卡:当场调用统一判断函数(场景 = 套餐到期),判断需要停机即生成停复机指令(指令记录场景)。
- 设备:请求设备维度判断,场景"套餐到期"写入 `eval_scenes`(6.1 节)。
- 不走套餐步骤的原因:暂停轮询的卡不在轮询队列中(生命周期 `ShouldEnqueue` 排除),套餐步骤不会执行;即使执行,套餐步骤属于周期评估,在暂停规则下也被禁止。到期即停必须以独立场景直接生成指令,暂停轮询的卡或设备才能按第 12 节停机。
- 该卡下次执行卡任务时(未暂停轮询的卡)自然落入无套餐层。
- 上线顺序:依赖第 6 个 change 的停复机指令队列与设备判断场景合并;第 6 个 change 上线前不实施到期即停,沿用现有套餐轮询发现过期后停机的逻辑。
#### 11.6 兜底:无套餐仍在跑流量、库存卡开机
- `EvaluateAndAct` 依据数据库中的 `network_status`。停机失败、结果未知或上游被重新开机时,数据库可能记为停机而上游实际开机,只有卡状态检查查询上游后才能发现。
- 因此无套餐层与库存层必须配置卡状态检查;查到开机后进入停复机判断。
- 库存卡上游开机应停机:库存卡通常无套餐,按现有规则命中"无有效套餐"停机原因,无需新增停机规则;售出并有生效套餐后按现有复机规则恢复。
- 已销售且无套餐、或在库的卡若未匹配到任何配置,监控告警,避免漏掉兜底。
#### 11.7 边界
| 情况 | 处理 |
|---|---|
| 设备卡 | 套餐状态按设备计算,设备下所有卡同层 |
| 套餐已用完 | 单独一层,中频查状态,确认未继续跑流量 |
| 只有待生效套餐 | 主要等待实名或激活条件,实名检查频率单独配置 |
| 行业卡 | 不单独处理,按第 12 节口径判断;轮询频率如需区分仍可用卡类别维度配置 |
| 未匹配任何配置 | 不入队;已销售无套餐、在库的卡告警 |
#### 11.8 与新调度的关系
- 分层只影响每张卡计算出的下次到期时间,不新增队列,不影响 NSQ 分发与限流。
- 不依赖新调度,可在现有调度上单独上线,直接减少调用量。
#### 11.9 套餐激活前流量结算
问题:流量计量(`Iteration/8-11`,已切换日快照计量的卡)的增量 = 本月最大快照 − 本月已结算;卡没有生效套餐时增量只记为已结算、不扣(`internal/application/cardobservation/traffic_flow.go:91`)。这要求无套餐期间有观测。无套餐层不查流量时,无套餐期间跑的流量(以及二次销售前上一用户本月的用量)会在激活后第一次查流量时算进新套餐。
设计:资产从"无生效套餐"变为"有生效套餐"之前,先做一次流量结算观测,再激活。
1. 触发:`ActivationService` 的实名激活、排队激活、指定激活、队首激活,以及订单购买即生效(`internal/service/order/service.go:2567,2714`),在激活事务开始前判断该资产当前无生效主套餐时执行。已有生效套餐(续费、排队衔接)与流量重置(套餐本身不变)不执行。
2. 结算:对独立卡查一次流量;对设备逐张查设备下各卡(各卡按所属运营商账户)。查询结果走现有观测入账(`ApplyTrafficObservation`),此时资产无生效套餐,增量只记为已结算。
- 结算观测**不触发停复机评估**:观测带"激活前结算"标记,入账照常,但不产生触发停复机评估的 Outbox 事件(或消费者识别标记后跳过评估)。否则资产此刻无套餐,会按"无有效套餐"生成停机指令并在 1~2 秒内执行;激活提交后的复机又被单卡最小重试间隔(停机与复机合计)挡住,客户付费后卡要停机一个间隔(约 10 分钟)。
- 按观测时间归属,不按入账时刻的套餐状态:结算观测带上网关返回时记录的观测时间 `observed_at`;入账时若资产已有生效套餐,但 `observed_at` 早于该套餐的激活时间 `activated_at`,增量仍只记为已结算、不扣减。原因是各激活入口的并发保护不统一(排队、指定、队首激活用 Redis 锁 `RedisPackageActivationLockKey`;订单购买用卡或设备行锁 `FOR UPDATE`,`internal/service/order/service.go:2300`;实名激活 `ActivateByRealname` 两者都没有),结算查询返回慢时,另一入口可能已先激活套餐;若按入账时刻判断有套餐,就会把激活前的旧用量扣到新套餐上。该规则对所有流量观测通用(轮询查流量返回慢于激活同样适用),不只限于结算。
- 统一资产级激活锁:所有"无生效套餐 → 有生效套餐"的激活入口(实名、排队、指定、队首激活,订单购买即生效)统一使用同一把资产级锁(沿用 `RedisPackageActivationLockKey(carrierType, carrierID)`,实名激活与订单购买补上),结算与激活事务都在锁内执行:抢锁 → 结算 → 激活事务 → 释放锁。锁 TTL 须大于结算总超时 + 激活事务耗时。订单路径原有的行锁保留。观测时间归属是正确性的根本保证,锁用于减少并发激活与重复结算。
3. 然后执行激活事务;提交后请求停复机评估(第 6 节),这是激活链路唯一的一次评估。
4. 结算查询失败或超时:不阻塞激活,照常激活,记录告警(卡、资产、错误),该卡本月可能多计无套餐期间用量,由运营核对。
5. 结算查询属于自动触发的检查,受运营商账户限流约束(批量下单时不形成波峰);限流等待超过单步超时则跳过结算,照常激活并按第 4 条告警。
6. 总超时:结算可能处于支付回调、实名回调等同步链路中,整次结算设总超时(系统参数,见 7.5 节)。设备逐张查询,总超时到达时剩余未查的卡跳过结算,照常激活,并按第 4 条逐卡告警,避免设备卡多时拖长回调。
7. 未切换日快照计量的卡沿用老算法,不做结算。
效果:无套餐层可以只查状态、不查流量,分层轮询的调用量节省不以计费准确性为代价。
#### 11.10 重置日前加密查流量
问题:运营商返回本周期累计流量,到重置日清零。每张卡"清零前最后一次查询"到"清零"之间的用量永远查不到,扣不到套餐上;查询越稀,丢得越多(`docs/卡流量计算技术方案-参考老卡管.md` 第 9 章)。
设计:在重置时刻前的一段窗口内,把流量检查间隔临时调短,让最后一次查询尽量贴近清零时刻。
1. 重置时刻:卡所属运营商账户 `tb_carrier.data_reset_day`(1~28)当天 0 点(业务时区),与流量计量的重置日口径一致。
2. 配置:`tb_polling_config` 新增两列,为空表示该配置不加密:
- `pre_reset_window`:重置前窗口长度;
- `pre_reset_carddata_interval`:窗口内的流量检查间隔。
收尾提前量(最后一次查询相对重置时刻的提前量)为系统参数,见 7.5 节。
通常只在有生效套餐的层配置。
3. 计算流量步骤下次到期时间(卡任务收尾、全量初始化、生命周期重新匹配时):
- 当前已在窗口内:下次到期 = 当前 + 窗口内间隔;若这一时间越过重置时刻,则改为"重置时刻 − 收尾提前量"(已过则不再加查),保证最后一次查询贴近清零;
- 当前在窗口前、按正常间隔算出的下次到期会越过窗口起点:下次到期截断到窗口起点,保证按时进入窗口;
- 越过重置时刻后恢复正常间隔。
4. 高峰:同一运营商账户的卡重置日相同,窗口内查询集中。仍受运营商账户 QPS 限流约束,不突破上限;限流内查不完的卡按到期先后执行。运营可按账户卡量与 QPS 调整窗口长度与间隔。
5. 监控:按运营商账户统计每个重置周期"有生效套餐、但窗口内未查到流量"的卡数,以及最后一次查询距重置时刻的分布,用于调整配置。
6. 适用于全部计量方式(日快照与老算法都存在尾部丢失)。
### 12. 停复机规则口径
沿用 `Iteration/8-11` 已实现的停复机新规则(`stop_resume_unified.go`),作为唯一口径,不再保留总开关与旧口径:
> 实名满足 = 卡所属运营商账户未开实名管控(`tb_carrier.realname_control_enabled = 0`),**或** 开了实名管控且卡已实名。
> 不区分行业卡,不看卡或设备的 `realname_policy`。
- 停机原因:流量用完 > 无有效套餐 > 实名不满足(未实名且运营商账户开了实名管控)。
- 复机:有生效套餐 且 流量充足 且 实名满足;不看停机原因;持通道阈值锁仍拒绝。
- 不看停机原因包括运营商侧主动停机 `carrier_stopped`(2026-10-24 已定):是否复机只由本系统规则决定,不以外部停机为依据。
- 风险停机、已销户的卡**必须关闭轮询**(2026-10-24 已定),关闭后不查上游、不自动停复机、不被套餐生效类入口自动恢复、批量开启时跳过:
- 现有:查卡状态返回扩展状态 `gateway_extend` 为"风险停机""已销户"时自动关闭轮询(`ShouldStopPollingForRisk`,`internal/domain/cardobservation/network.go:88`)。生产 2026-10-24 实查共 8,420 张(已销户 5,832、风险停机 2,588),全部为独立卡且均已关闭轮询。
- 补齐一:现有判断要求 `is_standalone`,绑定设备的卡命中时不关闭。改为不论是否绑定设备都关闭**该卡自身**的 `enable_polling`(不级联关闭设备与设备下其他卡);该卡因此不再参与自动停复机(`autoControlSuspended` 按卡判断),设备维度判断对其余卡照常进行。
- 补齐二:停复机调用直接返回终态(如"当前用户已销户,无法操作""当前卡为风险停机状态,仅支持风险复机")而查状态尚未返回对应扩展状态时,同样自动关闭该卡轮询,并回写 `gateway_extend`;错误分类表中这类关键字的类别为"终态不可操作",并标记"自动关闭轮询"(6.2 节)。
- 自动关闭同事务写不轮询清单,来源"风险停机或已销户自动关闭"(13.2 节)。其他终态(如"物联网号码封存")不自动关闭,按 6.2 节写告警,由运营决定。
- 开启影响(生产 2026-10-24 实查,停机、开启轮询且有生效套餐的卡,未计流量是否充足,为上限):`not_realname` 15,059 张、`carrier_stopped` 998 张、停机原因为空 83 张、`manual` 22 张。所有运营商账户 `realname_control_enabled` 默认为 0(迁移 242),新规则下等于全部账户不要求实名,15,059 张未实名停机卡将满足复机条件。开启前必须按第五部分第 3 节"上线前演练"处理。
- 暂停轮询(卡或所在设备 `enable_polling` 关闭)沿用老系统"不轮询名单"`tbl_no_loop_card` 的口径(2026-10-23 已定,取代 2026-10-22 的"关闭轮询即人工接管"):
- 不查上游:卡状态、流量、实名都不轮询;由检查结果或周期评估触发的自动停复机(流量用完、实名不满足、卡状态检查后的停复机、套餐步骤评估)不做。老系统对不轮询卡跳过阈值停复机判断(`CardFazhiService.java:258`),全量巡检也排除(`FindTingjiViewComp.java:253`)。
- 套餐失效停机照常:套餐到期即停(11.5 节)、退款后资产无可用主套餐的停机,不看 `enable_polling`。老系统到期停机任务 `CardJob.stopCard` 不排除不轮询名单。
- 套餐生效类入口自动恢复轮询:先自动恢复(卡或设备 `enable_polling` 置为开启,写审计与不轮询清单,见 13.2 节),再按规则请求评估。入口:订单套餐生效(客户支付成功、后台下单、批量下单、OpenAPI 钱包下单,均经 `internal/service/order/service.go` `activatePackage`);后台修改套餐有效期(`PATCH /assets/:identifier/packages/:package_usage_id/expires-at`)后资产有生效套餐(2026-10-23 已定)。老系统支付成功、后台充值套餐、批量或单张改有效期后有有效套餐,均把卡移出不轮询名单(`WeixinPayComp.java:3021-3025`,`CardViewComp.java` 中 `zht_rec`、`aght_rec`、`batch expire`、`update expire`)。卡的 `gateway_extend` 为风险停机或已销户时不恢复该卡轮询:这类卡由现有逻辑自动关闭轮询(`internal/domain/cardobservation/network.go:88` `ShouldStopPollingForRisk`),恢复后只会再次撞上游终态错误。
- 套餐失效停机对暂停轮询的卡只触发一次(到期或退款时请求评估一次,之后由停复机指令按 6.2 节重试);请求写入失败或 Redis 数据丢失时不做补偿扫描(2026-10-23 已定,接受:有套餐的卡关闭轮询由运营自行负责)。
- 其他自动复机入口(排队激活、实名激活、流量重置、运营商账户实名管控修改)对暂停轮询的卡不自动复机。
- 实现:请求评估带上场景;判断函数在"暂停轮询"这一步只对套餐失效场景(到期、退款)的停机方向放行;停复机指令记录场景,执行器执行前重新判断时沿用同一场景。
- 后台人工点击的停复机不受影响。
- 人工停机不享有豁免(2026-10-23 已定,接受):轮询开启的卡被后台人工停机后,只要有生效套餐、流量充足、实名满足,下一次套餐步骤即按规则自动复机;需要保持停机的,运营须同时关闭轮询。
- 实名步骤:卡所属运营商账户未开实名管控时跳过查实名(结果不影响停复机),不再按卡类别跳过。
- 设备维度判断(6.1 节)、停复机指令执行前的重新判断使用同一口径;设备下各卡按各自所属运营商账户判断实名。
### 13. 批量开关轮询与不轮询清单
现状:开关轮询只有单资产接口 `PATCH /assets/:identifier/polling-status`(`internal/routes/asset.go:140`)和系统自动规则(风险停机或已销户自动关闭、设备开关级联到卡、支付成功自动恢复);没有人工批量操作,卡列表也不能按是否轮询筛选。`iot_card.Service.BatchUpdatePollingStatus` 只在设备级联时内部使用(`internal/service/polling/asset_polling_service.go:96`)。老系统"不轮询网卡"页面(`tbl_no_loop_card`,`NoLoopCardViewComponent`)提供列表筛选、Excel 导入加入或移出、单条删除、导出,以及导卡时直接加入。
#### 13.1 批量开关轮询(核心)
- 勾选批量:新增 `POST /iot-cards/batch-update-polling-status`、`POST /devices/batch-update-polling-status`,参照 `batch-update-realname-policy`:资产 ID 列表(单次最多 500)、目标状态、原因;数据权限校验;同一事务写 `enable_polling`、不轮询清单(13.2 节)与审计;提交后调用生命周期移入或移出轮询(卡复用 `BatchUpdatePollingStatus` 的 `OnCardEnabled` / `OnCardDisabled`;设备沿用现有设备级联到卡)。
- 文件导入:上传 ICCID(或设备 IMEI)文件并选择开启或关闭,走异步导入任务,逐行处理、逐行返回成功或失败原因,部分成功不回滚;参照手机号资产解绑导入任务(`internal/routes/phone_asset_association.go` `/unbind-imports`),提供任务创建、列表、详情。对应老系统 Excel 导入加入或删除不轮询。
- 批量开启时跳过 `gateway_extend` 为风险停机或已销户的卡,返回逐项跳过原因,不提供强制开启参数(2026-10-23 已定)。
- 关闭、开启的影响按第 12 节;确认框须提示。
#### 13.2 不轮询清单表 `tb_card_polling_pause`
调度只认卡与设备的 `enable_polling`,本表不参与调度判断,只承载"谁、何时、为什么关闭"以及列表、筛选与导出,避免为此扫描卡大表,也避免列表被系统自动关闭的卡淹没(生产约 8,456 张关闭轮询的卡中约 8,420 张是风险停机或已销户自动关闭)。
| 字段 | 说明 |
|---|---|
| asset_type、asset_id、identifier | 卡或设备,ICCID 或 IMEI |
| carrier_id | 卡所属运营商账户(设备为空) |
| status | 已关闭 / 已恢复 |
| pause_source | 关闭来源:人工单条、勾选批量、文件导入、风险停机或已销户自动关闭、设备级联、停机被拒告警处理、历史数据 |
| pause_reason、paused_by、paused_at | 关闭原因、操作人(系统为空)、时间 |
| import_task_id | 文件导入时的任务 |
| resume_source、resumed_by、resumed_at | 恢复来源:人工、批量、支付或下单生效、改有效期、设备级联 |
- 每个资产只保留一条状态为"已关闭"的记录(部分唯一索引);恢复时把该记录标为"已恢复"并保留,再次关闭新增一条,保留历史(2026-10-23 已定)。
- 所有改 `enable_polling` 的入口在同一事务内写本表:单资产接口、13.1 节批量与导入、`ShouldStopPollingForRisk` 自动关闭(`internal/application/cardobservation/network.go:69`)、设备级联、第 12 节各自动恢复入口、6.2 节告警页关闭轮询。
- 存量:上线时一次性补写当前 `enable_polling = false` 的卡与设备,`gateway_extend` 为风险停机或已销户的记为"风险停机或已销户自动关闭",其余记为"历史数据"。
- 后台页面:列表按运营商账户、来源、状态、ICCID、操作人、时间筛选;导出复用统一导出任务,新增场景 `polling_pause`;列表勾选可批量开启。
- 卡列表、设备列表同时增加"是否轮询"筛选,导出带上该字段。
#### 13.3 停机被拒告警列表
- 告警页(6.2 节)增加"停机被拒"视图:`tb_polling_failure_alert` 中停复机方向为停机、错误类型为终态或业务错误,或停机失败达到阈值的告警。
- 展示:ICCID、运营商账户、所属资产、网络状态、套餐状态、停机原因、上游返回码与信息、首次与最近失败时间、失败次数、是否已关闭轮询、处理状态与处理人。
- 导出复用统一导出任务,新增场景 `polling_stop_refused_alert`;列表勾选可批量关闭轮询(按 13.1 节,单次 500),清单来源记为"停机被拒告警处理"。
不在本方案范围:导卡时直接设为不轮询(老系统导卡页面"导入不轮询卡"选项),需要时导卡后用 13.1 节文件导入关闭。
不在本方案范围:激活状态计算(`internal/store/postgres/iot_card_store.go:274,314`、`internal/application/cardobservation/apply.go:139-140`)仍按"在线且(行业卡或已实名)"判断,是否改为同一口径另行讨论。
### 14. 后台接口清单(供前端)
原则:第 7 节所有后台配置、第 6.2 节告警、第 13 节不轮询清单都提供查询与修改接口,前端据此做页面;只有 yaml 系统参数(7.5 节)不开放接口。路由沿用现有轮询接口风格(`internal/routes/polling_*.go`,`Register` + `RouteSpec` 自动生成 OpenAPI 文档),均需登录;修改类接口仅超级管理员可用并写统一审计(配置变更属于人工操作审计,不受第 6.2 节"系统自动停复机不写统一审计"影响)。修改后同步 Redis,下一轮调度生效。
#### 14.1 配置类
| 配置 | 接口 | 说明 |
|---|---|---|
| 限流组(7.1) | `GET /polling-rate-limit-groups`(按运营商账户筛选,含全局组)、`POST`、`GET /:id`、`PUT /:id`、`PUT /:id/status`、`DELETE /:id` | 保存时校验:同账户同一操作只属于一个组、`reserved_qps < max_qps`、高优先级操作属于本组操作;停用提示"回落默认 QPS" |
| 运营商账户调度参数(7.2) | `GET /polling-carrier-params`(列表:全部运营商账户,未配置的返回全局默认值并标记"默认")、`GET /:carrier_id`、`PUT /:carrier_id`(不存在则创建)、`DELETE /:carrier_id`(恢复全局默认) | 保存时按当前订阅进程数校验执行上限与 `max_in_flight`(3.2 节);不提供按账户切换调度的接口(不灰度,见第 9 节) |
| 卡任务步骤、失败告警标量参数(7.3、7.4) | 复用现有 `GET /system-configs?module=polling`、`PUT /system-configs/:key` | 需改动:注册 `module = polling` 的配置项;`SystemConfigListRequest.Module` 枚举增加 `polling`;`step_order`、`backoff`、`alert_fail_count` 等 JSON 值现只校验 JSON 合法,需为注册项增加结构校验(如步骤只能是 4 种类型且不重复、退避序列递增且不超过检查间隔) |
| 限流模式 | 复用 `/system-configs`,键 `polling.rate_limit_mode`(`observe` / `enforce`) | 全局生效,不按账户覆盖 |
| 调度模式 | 复用 `/system-configs`,键 `polling.scheduler_mode`(`legacy` / `carrier`) | 切换触发第 9 节初始化流程;`GET /polling-stats/init-progress`(现有接口)查看新结构初始化进度 |
| 停复机出口全局开关 | 复用 `/system-configs`,键 `polling.stop_resume_queue_enabled`(bool) | 从 yaml 改为受控系统配置:开关与回退需要即时生效,不能依赖重新部署(第 9 节) |
| 上游错误分类(7.4) | `GET /gateway-error-classifications`(按类别、操作、启用状态、关键字筛选)、`POST`、`PUT /:id`、`PUT /:id/status`、`DELETE /:id`;`POST /gateway-error-classifications/test`(输入一段上游返回信息,返回命中的规则与类别) | 测试接口用于运营新增规则前验证 |
| 业务事件检查场景(7.6) | `GET /polling-check-scenes`、`PUT /polling-check-scenes/:scene` | 场景由代码预置(入口在代码里),不提供新增与删除,只改检查类型、确认延迟、冷却 |
| 轮询配置(分层与重置日前加密,11.3、11.10) | 现有 `/polling-configs` 增加 `package_state`、`asset_status`、`pre_reset_window`、`pre_reset_carddata_interval` 四个字段,去掉 `protect_check_interval`;间隔支持 `0` = 不检查;新增 `PUT /polling-configs/priorities`(整体排序)、`GET /polling-configs/match-preview`(匹配预览)、`POST /polling-configs/recalculate-due` 与 `GET /polling-configs/recalculate-due/:task_id`(重算到期时间及进度) | 保存校验与三种间隔含义见 11.3 节;前端以"按间隔 / 不检查 / 继承"三态展示每种检查类型,并支持拖拽排序 |
| 旧并发配置 | 现有 `/polling-concurrency` | 下线(第四部分),前端去掉页面 |
#### 14.2 枚举与选项
`GET /polling-options`:一次返回前端下拉所需的枚举——操作类型(查流量 / 查状态 / 查实名 / 停机 / 复机)、错误类别、业务事件场景、检查类型、套餐状态、资产状态、不轮询清单来源、告警状态与错误类型。运营商账户下拉沿用现有运营商账户列表接口。前端不写死枚举值。
#### 14.3 监控与查询类
| 功能 | 接口 | 说明 |
|---|---|---|
| 按账户监控(8 节) | 现有 `/polling-stats` 改造:`GET /polling-stats/carriers`(各账户队列长度、到期数、执行中数、实际 QPS、限流等待与超时次数、处理中标记到期次数、停复机成功 / 失败 / 重试)、`GET /polling-stats/carriers/:carrier_id/trend`(分钟级趋势) | 原按任务类型的统计在全部切换后下线 |
| 分层统计(11 节) | `GET /polling-stats/tiers` | 各层卡数、漏配告警卡数 |
| 重置日前加密统计(11.10) | `GET /polling-stats/pre-reset` | 按账户统计窗口内未查到流量的卡数与最后一次查询距重置时刻分布 |
| 停复机记录(6.2) | `GET /card-stop-resume-records`(按卡 ICCID、运营商账户、动作、来源、结果、错误类别、时间范围筛选)、`GET /iot-cards/:id/stop-resume-records`(单卡历史) | 时间范围必填且有上限,避免跨多个月分区扫描 |
| 停复机规则演练 | `GET /stop-resume-rule/dry-run`(按运营商账户、停机原因筛选;返回按账户 × 停机原因 × 判断结果的汇总与明细);明细导出复用统一导出任务,场景 `stop_resume_rule_dry_run` | 只判断、不执行、不写任何状态;可传入"假设的实名管控配置"预演;上线前演练用(第五部分第 3 节) |
| 卡当前停复机指令 | `GET /iot-cards/:id/polling-state` | 卡的各检查类型下次到期时间、最近错误、当前停复机指令(动作、原因、场景、失败次数、待确认)、是否在执行中;排查用,只读 |
#### 14.4 告警类(6.2、13.3)
| 功能 | 接口 |
|---|---|
| 失败告警列表 | `GET /polling-failure-alerts`(按运营商账户、检查类型、错误类型、状态、时间筛选) |
| 账户维度汇总 | `GET /polling-failure-alerts/summary`(按运营商账户 × 错误类型计数) |
| 停机被拒视图 | `GET /polling-failure-alerts?view=stop_refused` |
| 告警详情 | `GET /polling-failure-alerts/:id`(含最近停复机记录) |
| 处理 | `PUT /polling-failure-alerts/:id/status`(标记已处理);`POST /polling-failure-alerts/close-polling`(勾选告警批量关闭对应卡或设备的轮询,单次 500,清单来源记为"停机被拒告警处理") |
| 导出 | 复用统一导出任务,场景 `polling_stop_refused_alert` |
现有 `/polling-alert-rules`、`/polling-alert-history`(按队列指标的告警规则)保留,与本节失败告警互不替代。
#### 14.5 不轮询清单与批量开关(13 节)
| 功能 | 接口 |
|---|---|
| 勾选批量 | `POST /iot-cards/batch-update-polling-status`、`POST /devices/batch-update-polling-status` |
| 文件导入 | `POST /polling-status-imports`(上传 ICCID 或 IMEI 文件 + 目标状态 + 原因)、`GET /polling-status-imports`、`GET /polling-status-imports/:id`(逐行结果) |
| 不轮询清单 | `GET /card-polling-pauses`(按运营商账户、来源、状态、ICCID、操作人、时间筛选);导出复用统一导出任务,场景 `polling_pause` |
| 卡、设备列表筛选 | 现有卡列表、设备列表接口增加 `enable_polling` 筛选参数,导出带上该字段 |
#### 14.6 前端改动汇总
新增页面:限流组、运营商账户调度参数(含新调度切换)、错误分类(含测试)、业务事件场景、失败告警(含账户汇总与停机被拒视图)、停复机记录、不轮询清单与文件导入。
改造页面:轮询配置(加 4 个字段、去掉保护期间隔)、系统配置(增加 `polling` 模块)、轮询监控(按运营商账户)、卡与设备列表(是否轮询筛选、批量开关)、资产详情(去掉保护期状态,后台与 C 端)。
下线页面:轮询并发配置。
---
## 第四部分:清理项
数据库原则:清理只针对代码,数据库只加不删。废弃的表与列保留,代码中去掉读写,表或列注释标记已废弃;不执行删表、删列迁移。
保护期整套机制:
| 位置 | 清理内容 |
|---|---|
| `polling:protect` 类型 | `internal/task/polling_protect_handler.go`、`pkg/queue/handler.go:290-300` 注册、统计与监控;`StopResumeService.ProtectCheckSkipsForRealname`(`stop_resume_unified.go`,仅保护期轮询使用) |
| 轮询配置 `protect_check_interval` | 模型字段、DTO(`internal/model/dto/polling_config_dto.go:13,28`)、`config_manager.go` 匹配逻辑;数据库列保留不删,列注释标记已废弃 |
| 设备停复机(`internal/service/device/service.go`) | 不再设置保护期,不再因保护期拒绝相反操作 |
| 手动停复机单卡(`stop_resume_service.go:969,1036`) | 去掉保护期检查 |
| 资产接口 `device_protect_status` | `asset_dto.go:38,144`、`client_asset_dto.go:75`、`internal/service/asset/service.go`:**字段保留不删**,固定返回"无保护期",接口文档标记已废弃;后台前端与 C 端(含老版本小程序)都不再读取后,另行删除。避免直接删字段导致老版本客户端出错 |
| 常量 | `RedisDeviceProtectKey`、`DeviceProtectPeriodDuration` 删除;`StopReasonProtectPeriod` 保留(历史数据与 `pkg/constants/agent_open_api.go:65` 对外开放接口映射仍需要),不再产生新值 |
| 卡字段 `last_protect_check_at` | 从模型去掉,不再读写(`initializer.go:322`、`polling_protect_handler.go:159`);数据库列保留不删,列注释标记已废弃 |
旧分片与兼容代码:
- `PollingShardCount`、`polling:shard:*` 相关方法。
- 旧非分片队列 key `RedisPollingQueue{Realname,Carddata,Package,Protect}Key` 与监控兼容模式 `getLegacyAverageWaitTime`。
- `PollingBackpressureThreshold` 及按 ZCARD 的背压逻辑。
旧并发控制:
- `internal/service/polling/concurrency_service.go`、`PollingConcurrencyConfig` 模型、按类型的并发配置接口与页面;表 `tb_polling_concurrency_config` 保留不删,表注释标记已废弃。
- `acquireConcurrency` / `releaseConcurrency` 及写死的默认并发数。
旧提示通道:
- `polling:priority:{taskType}` List,改为运营商账户 priority ZSET。
停复机 sleep 重试:
- 轮询路径不再使用 `stopCardWithRetry` / `resumeCardWithRetry` 的"3 次重试、每次 sleep 2 秒";非轮询入口保持不变。
业务事件触发的卡观测序列:
- 订单、激活、停复机成功、设备操作、自动续费购包 5 处 `AppendSeriesRequested` 改为请求检查;对应的观测序列 Outbox 事件、`SeriesTrigger` 的卡检查序列与"立即、3 分钟、5 分钟"固定延迟不再用于卡检查。
- 读入口的 `BestEffortSeriesDispatcher` 卡检查分发(`client_asset.go`、`admin/asset.go`、`client_realname.go`、`gateway_service.go`)改为请求检查;OpenAPI 查询本来就不触发,保持不变。
退款后资产处理的停机:
- `refund/service.go` `stopAsset` 调 `ManualStopCard` 当场停机(停机原因记为 `manual`)的写法,改为请求评估。
激活、重置、订单后的裸 goroutine 复机:
- `activation_service.go` `resumeAfterActivation`、`reset_service.go:400`、`order/service.go:2196` 中起 goroutine 当场调 `ResumeCardIfStopped` 的写法,改为事务提交后请求评估。
停复机旧口径与总开关:
- 总开关 `stop_resume.unified_rule_enabled`(`JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED`)及各处分支。
- `isRealnameOK` 旧分支(行业卡判断、卡或设备 `realname_policy` 判断);`isPollingStopReason` 限定自动复机的逻辑;`ListByDeviceIDAndPollingStopReasons`。
- `internal/task/polling_realname_handler.go:70` 按行业卡跳过实名查询,改为按运营商账户实名管控跳过。
调用记录:
- 系统自动停复机不再写统一审计 `tb_audit_event` 与集成日志 `tb_integration_log`,改写停复机记录表;轮询查询不再写集成日志(含现有"数据有变化时写成功记录")。
设备锁:
- 轮询路径上现有设备锁 `RedisPollingDeviceOpLockKey`(SetNX 30 秒,抢不到即跳过、包住整段网关调用)由第三部分 6.1 节的设备判断锁 + 待判断标记 + `polling:device_eval` 任务取代;非轮询入口(人工设备停复机)保持不变。
---
## 第五部分:改动范围与实施拆分
### 1. 现有代码规模
- 轮询相关约 7,500 行:`internal/polling` 2,184 行、`internal/task/polling_*` 1,742 行、`internal/service/polling` 3,598 行。
- 牵扯停复机、Outbox、设备、资产、网关、Worker 装配约 6,900 行。
- 仓库仅 1 个测试文件(`internal/bootstrap/worker_services_test.go`),上述代码基本无测试兜底,验证依赖测试环境。
测试要求(每个 change 的 tasks 中必须包含):本方案的正确性主要落在十几段 Lua(领取、收尾、续期、限流、请求检查、设备判断),这些是最容易出并发问题的地方,必须用真实 Redis(测试容器或测试环境实例,不用 mock)做脚本级测试,至少覆盖:
| 场景 | 验证点 |
|---|---|
| 多实例同时领取 | 同卡只被领取一次;分发锁下同一账户每轮只领取一次;执行上限不被突破 |
| 处理中崩溃 | 不收尾时租约到期后卡被重新领取,不丢卡 |
| 长任务续期 | 执行超过单个租约时续期成功,期间不被重新领取;token 不一致时续期失败并停止后续步骤 |
| NSQ 重投 | 同一 token 两个消费者只有一个拿到执行权 |
| 停复机指令覆盖 | 执行中写入反向指令,收尾后新指令保留且 score 正确;无覆盖时指令被移除 |
| 单卡最小重试间隔 | 间隔内不领取,score 推后到可调用时间 |
| 设备判断合并 | 判断期间新请求使 `eval_ver` 变化,收尾后重新判断一次 |
| 限流窗口 | 窗口边界、高优先级预留与 `high_waiting`、全局组与账户组同时生效、停用组回落默认 QPS |
| 请求检查 | 多次请求合并为一个队列成员;冷却时长内不请求;执行中请求打优先标记 |
| 激活前结算 | 结算观测不产生停机指令,激活提交后只评估一次;结算返回晚于另一入口激活时,激活前用量只记已结算、不扣新套餐 |
| 内部重试计量 | 一次方法调用内的每次 HTTP 尝试各扣一次额度;停复机超时不发起第二次请求 |
| Asynq 任务限流 | 限流错误经 `IsFailure` 不计入 Asynq 重试次数、按固定短延迟重试,不按 n⁴ 递增、不归档;非限流错误行为不变;只统计模式下不拦截 |
| 停复机结果未知 | 超时后按确认延迟查状态;已是目标状态则结束;不是则按单卡最小重试间隔重发;查询失败不重发 |
| 暂停轮询到期停机 | 暂停轮询的独立卡、设备套餐到期后生成停机指令;到期与普通轮询请求合并后场景不丢失 |
| 风险停机与已销户 | 查状态返回扩展状态、或停复机返回终态时,独立卡与绑定设备的卡都关闭自身轮询,设备与其他卡不受影响;之后不被自动恢复、批量开启跳过 |
| 分层匹配 | 间隔 `0` 停止向下继承、空值继承;相同优先级按 ID 稳定排序;重算到期时间只提前不推后 |
| 跨账户设备 | 设备下各卡分属不同运营商账户时,停复机全部经指令队列、各卡最终状态一致;三个全局开关开、关、再开无重复停复机与漏停 |
| 整体切换与回退 | `scheduler_mode` 切换时旧 Asynq 排队任务直接结束、新结构初始化完成前不领取;按生产卡量(约 10 万)实测初始化耗时;回退后旧分片队列完整、无丢卡 |
### 2. 改动明细
新增:
| 模块 | 内容 | 估算 |
|---|---|---|
| 网关限流器 | 滑动窗口 Lua、高优先级预留与等待登记、全局组、ctx 豁免标记、立即返回与等待两种模式 | 约 300 行 |
| 失败原因与调用量记录 | gateway 结构化错误;`tb_card_stop_resume_record` 表、模型、Store、按月分区与过期清理、查询接口;查询结果 Redis 分钟计数与监控读取;卡最近错误写入 `due` | 约 450 行 |
| 配置 | 限流组、运营商账户调度参数、步骤与停复机参数:表、模型、Store、Service、后台接口、Redis 同步、校验 | 约 700 行 |
| 分发器 | 账户分发锁、领取 Lua、处理中标记与派发 token、执行计数与执行上限、停复机先出、优先先出与优先占比、发布 NSQ | 约 550 行 |
| 失败处理与告警 | 失败计数与退避、`tb_polling_failure_alert` 表与 Store、告警写入与自动恢复、账户级汇总、后台告警接口与一键关闭轮询 | 约 500 行 |
| NSQ 接入 | 生产者与消费者封装、按账户动态订阅、token 核对、Touch、优雅退出 | 约 400 行 |
| NSQ 部署 | 测试环境部署 nsqd + nsqlookupd,yaml 配置 | 运维 |
| 卡任务 | 步骤编排、收尾 Lua、租约续期与执行权、`due` 维护 | 约 450 行 |
| 停复机指令 | 生成、覆盖与版本号、执行器、退避重试、单卡最小重试间隔、待确认先查状态 | 约 500 行 |
| 上游错误分类 | 关键字 → 类别配置(表、后台接口、Redis 同步)、分类器、终态与频率限制处理 | 约 250 行 |
| 业务事件与读入口请求检查 | 请求检查 Lua、场景配置(表、后台接口)、延迟确认、各入口改造 | 约 400 行 |
| 批量开关轮询与不轮询清单 | 卡、设备批量接口;文件导入任务;`tb_card_polling_pause` 表、Store、各开关入口同事务写入、存量补写;清单页与导出场景 `polling_pause`;停机被拒视图与导出场景 `polling_stop_refused_alert`;卡、设备列表是否轮询筛选(第 13 节) | 约 600 行 |
| 数据库迁移 | 只加不删:新增 7 张表——不轮询清单 `tb_card_polling_pause`、限流组 `tb_carrier_rate_limit_group`、运营商账户调度参数 `tb_carrier_polling_param`、错误分类 `tb_gateway_error_classification`、业务事件检查场景 `tb_polling_check_scene`、停复机记录 `tb_card_stop_resume_record`(按月分区 + DEFAULT 分区)、失败告警 `tb_polling_failure_alert`;步骤与失败告警标量参数写入现有 `tb_system_config`(只插数据);`tb_polling_config` 新增分层与重置日前加密 4 个可空列;废弃的 `tb_polling_concurrency_config`、`protect_check_interval`、`last_protect_check_at` 保留不删,只在代码中去掉读写并在注释中标记已废弃 | 按 change 拆分 |
重写:
| 文件 | 改动 |
|---|---|
| `internal/polling/queue_manager.go`(273 行) | 改为运营商账户队列 + `due` |
| `internal/polling/scheduler.go`(298 行) | 改为分发器(领取 + 发布 NSQ) |
| `internal/polling/initializer.go`(348 行) | 改为写 `due` 与运营商账户队列 |
| `internal/task/polling_{realname,carddata,cardstatus,package}_handler.go`(约 550 行) | 拆为步骤函数 |
| `internal/task/polling_base.go`(242 行) | 删令牌,重入队改为写 `due` |
| `internal/service/polling/monitoring_service.go`(317 行) | 改为按运营商账户统计 |
修改:
| 文件 | 改动 |
|---|---|
| `internal/service/iot_card/stop_resume_service.go`(1,133 行) | `EvaluateAndAct` 只判断并生成指令;抽出执行部分供执行器复用;去掉保护期检查 |
| `internal/infrastructure/cardobservation/event.go` | 3 个消费者随 `EvaluateAndAct` 调整,接口不变 |
| `internal/service/carrier/service.go` | 实名管控修改后对受影响的卡批量请求评估 |
| `internal/service/order/service.go`、`internal/service/package/activation_service.go`、`internal/service/iot_card/stop_resume_service.go`、`internal/service/device/service.go`、`internal/task/auto_purchase.go`、`internal/application/cardobservation/series*.go` | 业务事件由观测序列改为请求检查;场景延迟确认配置 |
| `internal/handler/app/client_asset.go`、`internal/handler/admin/asset.go`、`internal/handler/app/client_realname.go`、`internal/service/iot_card/gateway_service.go`、`internal/infrastructure/cardobservation/best_effort.go` | 读入口由观测序列改为请求检查 |
| `internal/service/refund/service.go` | 退款后资产处理由 `ManualStopCard` 改为请求评估,请求成功即标记资产后处理完成 |
| `internal/service/package/activation_service.go`、`internal/service/package/reset_service.go`、`internal/service/order/service.go` | 激活、重置、订单后的复机改为请求评估;激活前流量结算(11.9 节) |
| `internal/polling/lifecycle_service.go`、`internal/service/polling/asset_polling_service.go` | 操作运营商账户队列 |
| `internal/task/polling_priority_claim.go`、`internal/service/polling/priority_manual_service.go` | 提示写入方式调整,认领逻辑不变 |
| `internal/service/polling/manual_trigger_service.go` | 仅消费方式调整 |
| `internal/service/polling/config_service.go`、`internal/polling/config_manager.go` | 删除保护期检查间隔 |
| `internal/service/iot_card/stop_resume_unified.go`(98 行)、`pkg/config/config.go:65`、`pkg/config/loader.go:162`、`pkg/config/defaults/config.yaml:166`(`stop_resume.unified_rule_enabled`)、`.gitea/workflows/deploy.yaml:67`(`JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED`)、`internal/task/polling_realname_handler.go` | 新规则转正:新规则并入主逻辑,删除总开关配置与部署环境变量、旧口径分支;实名轮询改按运营商账户实名管控跳过 |
| `internal/service/device/service.go`、`internal/service/asset/service.go` 及 DTO | 删除保护期 |
| `internal/gateway/client.go`、`internal/gateway/flow_card.go` | 限流器挂在 `AttemptObserver.BeforeAttempt`,按每次 HTTP 尝试扣额度;返回结构化错误(类别、业务码、信息、耗时);`StopCard` / `StartCard` 设 `maxRetries = 0` |
| `internal/application/cardobservation/traffic_flow.go` | 流量入账按观测时间与套餐激活时间归属,激活前的用量只记已结算 |
| `internal/service/package/activation_service.go`、`internal/service/order/service.go` | 实名激活与订单购买即生效补上资产级激活锁,结算与激活在锁内执行 |
| `pkg/queue/handler.go`、`cmd/worker/main.go`、`internal/bootstrap/*`、`pkg/constants/*` | 移除轮询的 Asynq 注册;装配分发器与 NSQ 消费者;常量 |
删除:`polling_protect_handler.go`(166 行)、`concurrency_service.go`(293 行)及对应 handler/路由/DTO、分片与兼容代码、卡检查用观测序列分发、新规则总开关与旧口径分支,约 1,100 行。
前端:限流组与各项参数配置页;轮询配置页去掉保护期间隔;资产详情(后台与 C 端)去掉保护期状态;监控页按运营商账户展示。
合计:新增约 5,000 行(含停复机记录表、错误分类、请求检查、批量开关轮询等),重写约 2,000 行,修改约 25 个文件,删除约 1,100 行;后端粗估 17~22 人日(含分层轮询 4~5 人日、批量开关轮询与不轮询清单 2 人日),不含前端与测试环境验证。
### 3. 实施拆分(按 OpenSpec change 依次上线)
前置条件(运行基线,2026-10-24 两库只读实查):
| 项目 | 测试库 | 生产库 |
|---|---:|---:|
| 迁移版本 | 242 | 240 |
| 未删除卡数 | 31 | 98,430 |
| 开启轮询的卡 | 28 | 89,962 |
| 有效绑卡设备 | 6 | 20,109 |
| 跨运营商账户设备 | 5 | 11,607 |
- 生产尚未执行迁移 241(日快照计量 `tb_card_flow_day` / 切换水位)与 242(运营商账户实名管控 `realname_control_enabled`),即 `Iteration/8-11` 的停复机新规则与日快照计量尚未上线生产;测试库虽已有表,切换水位记录为 0,日快照计量也未经测试环境真实卡验证。这两项功能不能视为已获生产验证。
- 因此:change 4(新规则转正)前置为"`Iteration/8-11` 已上线生产,各运营商账户实名管控已按需配置,新规则在生产开启并稳定运行";change 2 中激活前流量结算只对已切换日快照计量的卡生效,前置为"日快照计量已在生产开启并核对结算结果"。
- 上线前演练(停复机新规则在生产开启前,即 `Iteration/8-11` 总开关开启与 change 4 转正之前):
1. 运营先为需要实名的运营商账户设置 `realname_control_enabled = 1`。
2. 执行演练:按新规则对全部停机卡做一次只判断、不执行的评估(`GET /stop-resume-rule/dry-run`,见 14.3 节),按运营商账户 × 停机原因 × 判断结果输出"开启后将被复机 / 将被停机"的卡数与明细,可导出。
3. 运营核对演练结果,确认无误后再开启;需要保持停机的卡先关闭轮询(第 13 节批量操作)。
4. 开启后集中复机受各账户停复机 QPS 与单卡最小重试间隔约束,按账户平滑执行;首日监控复机成功率与终态错误数。
- 测试库只有 31 张卡,不足以验证吞吐与限流参数;各账户 QPS、执行上限的初始值须按生产卡量、轮询频率与上游允许的 QPS 计算,change 1 上线后用其采集的生产调用量与失败分类数据校准。
| 顺序 | change | 价值 | 风险 | 依赖 |
|---|---|---|---|---|
| 1 | 网关限流器(按每次 HTTP 尝试计量)+ 限流组配置 + 失败原因与调用量记录 + 停复机关闭 gateway 内部重试 | 最高:可直接套在现有调度上,先缓解超频与重复重试;失败原因可见,作为各账户 QPS 配置依据 | 低:不动现有调度 | 无 |
| 2 | 分层轮询 + 激活前流量结算(含观测时间归属与统一激活锁)+ 重置日前加密 | 高:直接减少调用量,兜住无套餐跑流量与库存卡开机;无套餐期间用量不计入新套餐;减少重置日前尾部丢失 | 低:只改配置匹配与激活前结算,需前端配合;激活后复机沿用现有路径,change 6 上线后改为请求评估 | 激活前结算依赖日快照计量已上线生产 |
| 3 | 去掉保护期 | 消除反复翻转,简化后续改造 | 低:需前端配合 | 无 |
| 4 | 停复机新规则转正 | 删除总开关与旧口径,实名轮询按运营商账户实名管控跳过 | 高(开启时):生产约 1.5 万张未实名停机卡可能被批量复机,须先完成实名管控配置与上线前演练;转正本身低风险 | `Iteration/8-11` 已上线生产(总开关可仍关闭);分两次发布:第一次发布演练接口与关闭轮询补齐,演练、配置实名管控后开启总开关;稳定后第二次发布删除总开关与旧口径 |
| 5 | 运营商账户调度 + NSQ 分发 + 卡任务 + 租约 + 失败退避与失败告警表 + 业务事件请求检查 | 运营商账户隔离、不丢卡、同卡串行;业务事件检查受限流约束、不再重复 | 高:核心链路重写,需部署 NSQ | 1、3 |
| 6 | 停复机指令队列 + 设备维度判断(含场景合并)+ 自动入口统一 + 到期即停 + 全局开关 `stop_resume_queue_enabled` | 停复机优先、不再 sleep 重试、设备下各卡一致(含跨账户设备);激活、重置、订单复机不丢、不超频;退款停机不再形成重试风暴;暂停轮询的卡到期照常停机 | 中:需拆分 `EvaluateAndAct`;跨账户设备为核心验收场景 | 1、4、5 |
| 7 | 批量开关轮询 + 不轮询清单 + 套餐生效类自动恢复轮询(第 12、13 节);停机被拒视图与导出随失败告警表上线 | 高:补上人工批量操作,运营可按清单处理停机被拒、按账户关闭轮询 | 低:只动开关入口与后台,需前端配合 | 停机被拒视图依赖 5、6(失败告警表在 change 5 建立);自动恢复后的"按规则请求评估"在 change 6 前沿用现有复机路径 |
依赖说明:到期即停依赖停复机指令队列与设备判断场景合并(11.5 节、6.1 节),从原 change 2 移到 change 6;change 6 依赖 change 4,因为暂停轮询、实名管控等判断口径以新规则为唯一口径。
分层轮询改动:`tb_polling_config` 及模型、DTO、后台接口与页面加两个匹配条件与保存校验;`config_manager.go` 匹配逻辑与套餐状态计算;`package_usage_store` 按资产查询套餐状态(单个与批量);`initializer.go`、`lifecycle_service.go`、重入队处传入套餐状态;监控按层统计与漏配告警;`activation_service.go` 与订单即生效处的激活前流量结算;重置日前加密(两列配置、到期时间计算、监控)。后端粗估 4~5 人日。到期即停(`package_activation_handler.go`)计入 change 6。
第 1 步上线时,限流器默认对所有卡操作生效,后台人工点击、通道阈值、自动续费、手动刷新 4 个入口补上"豁免限流"标记;现有轮询 handler、观测序列执行、Outbox 消费者触发的停复机等自动入口无需改动即受限流。
第 1 步在现有 Asynq 调度上的等待策略:Asynq 总协程数为 `queue.concurrency`(默认 10),轮询与 Outbox、导出、佣金等业务共用。若在 handler 内等待限流名额,轮询任务会占满协程、饿死其他业务。因此第 1 步中凡在 Asynq handler 内发起的受限流调用(现有轮询 handler、观测序列执行、Outbox 消费者触发的停复机)**不等待**:拿不到名额立即返回"限流"结果,轮询任务按 `rate_limited_retry_delay` 短延迟 Requeue、不计失败;Outbox 消费者返回"限流"错误,由 Asynq 按下方规则短延迟重试、不计失败;观测序列任务为 `MaxRetry(0)`,遇限流时记一次"被限流"并结束本次尝试(不归档),由后续尝试与普通轮询兜底,观测序列在 change 5 下线。"等待名额后重试"只在第 5 步的 NSQ 消费者中启用(NSQ 消费者按账户独立并发,不占用 Asynq 协程)。限流器接口因此提供两种模式:立即返回(Asynq handler 用)与等待至超时(NSQ 消费者、激活前结算用)。
第 1 步中 Asynq 任务遇到限流的处理(Outbox 消费者、观测序列):
- 现状:Outbox 事件由 Relay 投递为 Asynq 任务 `outbox:deliver`,消费者(如流量入账后调用 `EvaluateAndAct` 停机)返回错误时,由 Asynq 按任务重试;`relay.go` 中的 `retry_count` 只计"投递入队"失败,不计消费失败。`outbox:deliver` 入队未设 `MaxRetry`,使用 Asynq 默认 25 次,重试间隔为 `asynq.DefaultRetryDelayFunc`(`pkg/queue/server.go:44`,约第 n 次等待 n⁴ 秒)。
- 风险:限流立即返回的错误若按普通失败处理,高峰期连续被限流几次后,"流量用完停机"会被推迟数小时(第 8 次约 1 小时、第 10 次约 2.8 小时),期间卡继续跑流量;25 次用完后任务归档,停机不再执行。
- 处理:限流器返回专用错误类型"限流",在 Asynq 服务配置(`pkg/queue/server.go`)中:
- `IsFailure` 对"限流"错误返回 false:不计入失败、不增加重试计数,不会因限流归档;
- `RetryDelayFunc` 对"限流"错误返回固定短延迟 `rate_limited_retry_delay`,不按 n⁴ 递增;其他错误仍用默认函数。
- 同一任务因限流累计推迟超过上限(系统参数)时写告警,任务仍继续重试。
- 只改 Asynq 服务配置与错误类型,不改各消费者业务代码;对所有 Asynq 任务生效,非限流错误的行为不变。
第 1 步的拦截模式:限流器支持"只统计"与"拦截"两种模式,由受控系统配置 `polling.rate_limit_mode`(`observe` / `enforce`,默认 `observe`)全局控制,不按账户覆盖。
- 只统计:照常计数(各账户实际 QPS、本应被限流的次数),不拦截、不等待。
- 拦截:按 4 节执行。
- 上线顺序:change 1 先以只统计模式全量上线,采集至少一周各账户实际调用量与失败分类;按数据配好全部账户的限流组后,整体切到拦截模式。避免上线瞬间所有未配置的账户按默认 QPS 被拦截,导致整体轮询变慢。
---
## 第六部分:与老系统对比
老系统:源码 `/home/zoujin/works/golang/kg/qc/kyhl-src`(Java + Spring `@Scheduled`,定时任务在 `apps/kyhl-monitor`,公共逻辑在 `shared-b`),2026-10-22 按源码复核。
### 1. 老系统轮询逻辑摘要
- 调度:每个上游平台类型(`category`)一个定时任务 `findCardFlow1(category, threadCount)`(`CardLifeJob`),频率与线程数写死,例如移动(3)每秒 4 线程、普天联通(9)每秒 8 线程、电信(1)每 10 分钟;Spring 调度线程池 16,同一任务不重叠执行。
- 高频选卡:只取到期日不早于今天的套餐记录(`CardLifeYueViewComp.findCardFlow1`),按 `update_date_time_new` 升序每轮取 2000 条,排除不轮询卡与批量停机名单中的卡;处理后更新时间,形成轮转。每轮从数据库重新选卡,无中间状态。
- 批量查询:联通 CMP、广电、领网、广电 IoT 先按账户分组批量查询流量与状态,其他平台逐张查询;只有广电 IoT 批次间 sleep 6 秒(`GuangDianIotBatchUtil.java:131`)。
- 每张卡一个函数串行完成(`CardFazhiService.shezhiFazhiTingfuji`):查询(有批量结果则复用)→ 记录日流量 → 计算剩余流量 → 判断停机(剩余低于阈值、电信 IMEI 不在库、临近到期、代理流量池超额)→ 停机前尝试续费 → 当场调上游停机并写停复机记录。
- 临近到期:最新生效套餐距到期天数 ≤ 上游账户配置的提前停机天数,且无下月套餐时,判定"接近过期时间停机";停机前先尝试自动续费,成功则不停机(已停机则复机)。综合套餐月套餐流量不足时先尝试续充。
- 到期停机:`CardJob.stopCard` 每 2 分钟处理当天到期的套餐,停机前复查是否确已过期、有无次月套餐。
- 全量巡检(无套餐兜底):`FindTingjiViewComp.findTingji` 每秒执行,按 `loop_time_3` 轮转每次取 5000 张卡、4 线程(排除串卡、不轮询卡、批量停机名单)。有未过期套餐的卡不调上游,只更新轮转时间;无未过期套餐的卡查上游状态,开机则写入停机队列 `tbl_tingji`,不当场停机;查询失败跳过,等下次轮转。
- 停机队列:`TingjiViewComp.tingji` 每 10 秒取 `tbl_tingji` 中待处理(1)与失败(2)的记录最多 1 万条、8 线程执行。执行前复查(有次月套餐、未到提前停机天数则不停)→ 停机前尝试自动续费 → 停机;上游返回"已存在""当前用户不允许办理""防范实名""参数缺失""密码错误"时结束任务、不再重试,但停复机记录仍记为失败,即"结束"不等于停机成功;电信卡停机或断网任一成功即结束任务;其余失败记为 2,每 10 秒无限重试,无退避。
- 批量停机名单 `tbl_batch_stop_card`:排除名单,名单中的卡不参与轮询与巡检。
- 不轮询名单 `tbl_no_loop_card`:名单中的卡不查上游(高频轮询、全量巡检、移动流量选卡均排除),阈值停复机判断直接跳过;到期停机 `CardJob.stopCard` 不排除,套餐到期照常停机;客户充值支付成功先移出名单再做停复机判断(`WeixinPayComp.java:3021`),后台充值套餐、改有效期后有有效套餐也移出名单。超级管理员通过"不轮询网卡"页面列表筛选、Excel 导入批量加入或移出、单条删除、导出(`NoLoopCardViewComponent`),导卡时可直接加入。
- 退款:只处理订单状态、备用金扣回与佣金冲回,不停卡、不作废套餐记录,卡用到套餐到期后由到期停机处理。
- 限流:每个平台的 HTTP 工具类内一个静态 Guava `RateLimiter`,查询与停复机共用,数值写死(电信 10、普天联通 16、CMP5G 8、领网 5、联通 Jasper 2、瑞信 2、新联通 1、中原 1),单进程内生效,按平台而非账户;广电、广电 IoT、广电网络、甘肃、移动 OneLink、岱川移动无限流。
### 2. 对比
| 对比项 | 老系统 | 本系统现状 | 本系统新方案 |
|---|---|---|---|
| 队列划分维度 | 按上游平台各一个定时任务 | 16 固定分片 × 5 类型 | 运营商账户 × (停复机 / 优先 / 普通) |
| 选卡方式 | 按最后处理时间轮转,每轮 2000 张 | 每卡每类型到期时间 | 每卡每类型到期时间,按卡汇总最早到期 |
| 轮询范围 | 高频只覆盖有未过期套餐的卡;全量巡检对无套餐卡只查状态、开机即停;到期即停 | 开启轮询开关的卡全部按配置轮询,配置只区分网络与实名状态 | 按套餐状态、资产状态分层;无套餐与库存层必配状态检查;到期即停 |
| 检查类型 | 一个函数内完成全部 | 实名、流量、卡状态、保护期、套餐 | 实名、流量、卡状态、套餐 |
| 同卡多类型 | 串行 | 可并行 | 串行,顺序可配置 |
| 批量查询 | 部分平台按账户批量 | 无 | 暂无,预留外部结果入口,gateway 支持后增加 |
| 限流维度 | 平台,QPS,写死,单进程;广电、移动 OneLink 等平台无限流 | 全局 + 任务类型,并发数,无依据 | 运营商账户 → 限流组 → 操作,QPS,可配置,全局生效 |
| 限流覆盖 | 该平台全部请求 | 仅轮询任务 | 所有自动触发的检查与停复机;后台人工点击、通道阈值、自动续费、手动刷新不限流 |
| 停复机触发 | 高频轮询在卡处理函数内当场停机;全量巡检写停机队列 `tbl_tingji`,由独立任务复查后执行 | 轮询任务内同步 + Outbox 消费者同步 | 生成指令进运营商账户停复机队列 |
| 停复机优先级 | 无 | 无 | 最高:先出队,共用组预留 QPS |
| 停复机失败重试 | 停机队列失败记录每 10 秒无限重试,无退避;上游返回"已存在""密码错误"等时结束任务但记录仍为失败 | 同步 3 次,每次 sleep 2 秒 | 放回队列退避重试 |
| 临近到期 | 按账户提前停机天数提前停机,停机前尝试续费 | 无提前停机;每日 07:00 独立扫描提前续费 | 不变(业务规则不在本方案范围) |
| 保护期 | 无 | 有,1 小时 | 无,规则优先 |
| 崩溃恢复 | 每轮从库重选,天然恢复 | 无(出队即删除) | 卡不出队,处理中标记 TTL 到期后自动重新领取 |
| 持续失败 | 无专门处理 | 30 秒兜底重入队,无告警 | 退避重试 + 失败告警 + 账户级汇总 + 运营处理 |
| 可配置性 | 全部写死 | 间隔与类型并发可配置 | 限流、调度、步骤、重试均可配置 |
| 监控维度 | 日志 + 停复机记录 | 任务类型 | 运营商账户 + 任务类型 |
### 3. 评分(满分 100,按权重加权;新方案为设计分)
| 维度(权重) | 老系统 | 现状 | 新方案 |
|---|---|---|---|
| 上游限流是否准确(20) | 5 | 2 | 7 |
| 账户/平台隔离(10) | 7 | 2 | 8 |
| 调用效率(10) | 8 | 3 | 6 |
| 可配置性(10) | 2 | 6 | 9 |
| 可靠性与崩溃恢复(15) | 7 | 3 | 8 |
| 调度时效(10) | 5 | 7 | 8 |
| 并发一致性(5) | 8 | 3 | 10 |
| 停复机处理(10) | 6 | 4 | 10 |
| 可观测性(5) | 5 | 8 | 8 |
| 可维护性(5) | 2 | 6 | 6 |
| **总分** | **56** | **39** | **79** |
新方案得分说明:并发一致性含设备维度判断加锁;停复机处理含设备下各卡一致与到期即停、无套餐兜底;调用效率含分层轮询;可维护性因新增 NSQ 组件与设备判断链路扣分。
新方案扣分点:调用效率(无批量查询,gateway 支持后可补,预计 +4);后台人工点击、通道阈值、自动续费、手动刷新的请求不计入额度(扩展到所有入口预计 +2)。
---
## 第七部分:待确认与后续事项
已定(2026-10-22):
- 套餐激活、流量重置、订单触发的复机改走停复机指令队列(第三部分第 6 节)。
- 无套餐期间的流量归属:套餐激活前做一次流量结算观测(第三部分第 11.9 节)。
- Outbox 三个卡观测消费者触发的停复机同样走停复机指令队列,自动停复机全部经同一出口(第三部分第 6 节)。
- 重置日前加密查流量:按运营商账户重置日,在配置的窗口内缩短流量检查间隔(第三部分第 11.10 节)。
- 运营商账户实名管控修改后主动对受影响的卡批量请求评估;卡或设备恢复轮询沿用现有生命周期重新入队,不另加触发(第三部分第 6 节)。
- 退款后资产处理不再调用 `ManualStopCard`,改为请求评估,停机走停复机指令队列;"不进队列"的人工入口只保留后台人工点击的停复机(第三部分第 6 节)。
- 业务事件不再起观测序列,改为把卡的对应检查设为立即到期并放进优先队列,统一走卡任务;需要延迟确认的按场景配置追加一次延迟检查(第三部分第 5.1 节)。
- 读入口(C 端资产详情、后台资产实时状态、实名链接)同样改为请求检查走卡任务(OpenAPI 查询不触发,2026-10-24 更正),受运营商账户限流约束(第三部分第 5.1 节)。
- 失败原因与调用量记录放入第 1 个 change:gateway 结构化错误;停复机写单独的停复机记录表 `tb_card_stop_resume_record`(按月分区),不再写统一审计与集成日志;查询失败不建表、不逐条落库,Redis 计数 + 卡上最近错误 + 持续失败进告警表(第三部分第 6.2 节)。
- 上游表示已是目标状态(已停机、已开机等)视为成功,结束停复机指令,不计入失败(第三部分第 6.2 节,参考老系统)。
- 上游频率限制、终态不可操作、临时故障分类处理;停复机指令增加按运营商账户配置的单卡最小重试间隔(第三部分第 6、6.2、7.2 节)。
- 限流覆盖所有自动触发的检查与停复机(含激活前流量结算);只有后台人工点击的停复机、通道阈值、自动续费、手动刷新不限流(第三部分第 4 节)。
- ~~关闭轮询即人工接管,不再自动停复机~~(已被 2026-10-23 的不轮询口径取代)。
已定(2026-10-23):
- 暂停轮询沿用老系统不轮询名单口径:不查上游、不做由检查与周期评估触发的自动停复机;套餐到期、退款后无套餐照常停机;客户购买套餐支付成功自动恢复轮询并按规则复机,`gateway_extend` 为风险停机或已销户的卡不恢复;不拆分为两个开关(第三部分第 12 节)。
- 暂停轮询的卡套餐到期、退款后的停机只触发一次,不加补偿扫描;有套餐的卡关闭轮询由运营自行负责(第三部分第 12 节)。
- 人工停机不享有豁免:轮询开启的卡人工停机后,满足复机条件即由套餐步骤自动复机;需保持停机的须同时关闭轮询(第三部分第 12 节)。
- 单卡最小重试间隔按卡计算,停机与复机合计(第三部分第 2、3.2、6 节,7.2 节)。
- 卡任务按预计网关调用数领取,避免超领(第三部分第 3.2 节)。
- 限流组停用后回落为默认 QPS,不存在不限流的自动调用(第三部分第 4 节、7.1 节)。
- ~~切换期间所有入口按卡所属运营商账户分流,切入、切回账户时清理旧或新结构~~(已被 2026-10-24"不灰度、整体切换"取代,见第三部分第 9 节)。
- 激活前流量结算设总超时(第三部分第 11.9 节)。
- 停复机记录表建 DEFAULT 分区并提前建未来分区,记录写入与状态回写分开(第三部分第 6.2 节)。
- 配置存储:账户调度参数、错误分类、业务事件场景各一张新表;步骤与失败告警标量参数放 `tb_system_config`(第三部分第 7 节)。
- 批量开关轮询是本方案主体之一:卡、设备勾选批量接口(单次 500)与 ICCID 文件导入任务;批量开启跳过风险停机、已销户的卡并返回原因,不提供强制参数(第三部分第 13.1 节)。
- 新建不轮询清单表 `tb_card_polling_pause` 记录关闭来源、操作人与时间,调度仍只认 `enable_polling`;所有开关入口同事务写入;恢复时标记已恢复并保留历史(第三部分第 13.2 节)。
- 停机被拒告警单独成列表,可导出、可勾选批量关闭轮询(第三部分第 13.3 节)。
- 自动恢复轮询的入口对齐老系统:订单套餐生效(支付成功、后台下单、批量下单、OpenAPI 下单)、后台改有效期后有生效套餐;风险停机、已销户的卡除外(第三部分第 12 节)。
- 数据库只加不删:`tb_polling_concurrency_config`、`tb_polling_config.protect_check_interval`、`tb_iot_card.last_protect_check_at` 保留不删,代码中去掉读写,注释标记已废弃(第四部分)。
已定(2026-10-24,方案评审):
- 停复机指令带版本号,执行期间被覆盖的新指令在收尾时保留,不被删除(第三部分第 2、3.3、6 节)。
- 激活前流量结算的观测不触发停复机评估,激活提交后只评估一次,避免付费后先停机再被单卡最小重试间隔挡住复机(第三部分第 11.9 节)。
- 处理中标记在执行期间续期,卡任务设总超时;增加执行权 key,防止 NSQ 重投时同一 token 被并行执行(第三部分第 2、3.3 节)。
- 停复机领取增加执行上限 `sr_inflight_limit`;执行上限不得大于各订阅进程 `max_in_flight` 之和(第三部分第 3.2、7.2 节)。
- 第 1 个 change 在 Asynq handler 内的限流调用不等待,拿不到名额立即短延迟重入队,避免占满共用协程池;等待模式只在 NSQ 消费者中启用(第三部分第 4 节、第五部分第 3 节)。
- 限流改为默认限流、显式豁免,只有后台人工点击、通道阈值、自动续费、手动刷新打豁免标记(第三部分第 4 节)。
- 优先队列设最大占比 `priority_max_ratio`;请求检查按场景配置冷却时长,读入口应配置(第三部分第 3.2、5.1、7.2、7.6 节)。
- 分发器按账户加分发锁,同一账户每轮只由一个实例领取(第三部分第 2、3.2 节)。
- ~~跨账户设备:设备下所有卡所属账户均已切换才走新的设备维度停复机路径,否则整机走旧路径~~(已被同日"停复机出口全局开关 `stop_resume_queue_enabled`"取代,见下方与第三部分第 9 节)。
- 每个 change 必须包含 Lua 脚本的真实 Redis 并发测试(第五部分第 1 节)。
- NSQ 保留,作为卡轮询的执行分发组件。
- 限流按每次实际 HTTP 请求扣额度,挂在 `AttemptObserver.BeforeAttempt`,gateway 内部重试同样计入(第三部分第 4 节)。
- 停复机不使用 gateway 内部重试(`maxRetries = 0`),超时按结果未知、下次先查状态(第三部分第 6 节)。
- 流量入账按观测时间归属:观测时间早于套餐激活时间的用量只记已结算;无生效套餐到有生效套餐的激活入口统一资产级激活锁,结算在锁内执行(第三部分第 11.9 节)。
- 只有上游明确返回已是目标状态才视为停复机成功;老系统"结束停机任务"的关键字不作为依据,"密码错误""参数缺失"归为账户配置错误并立即账户级告警(第三部分第 6.2 节)。
- 停复机结果未知不沿用现有恢复扫描(现有普通停复机只有人工核对策略),在指令队列内按"确认延迟 → 查状态 → 已是目标状态结束 / 否则按单卡最小重试间隔重发"处理(第三部分第 6 节第 5 条)。
- 到期即停不走套餐步骤,以"套餐到期"场景直接请求评估;设备判断队列保存并按并集合并请求场景,避免暂停轮询的卡或设备漏停(第三部分第 6.1、11.5 节)。
- ~~跨账户设备:卡任务按账户灰度,停复机出口改为全局开关~~(已被同日"不灰度"取代)。
- 不灰度(2026-10-24 已定):不按运营商账户、设备或卡灰度,每个 change 对全部账户整体切换;只保留 `polling.rate_limit_mode`、`polling.scheduler_mode`、`polling.stop_resume_queue_enabled` 三个全局开关用于整体回退;取消账户调度参数中的 `polling_enabled` 与 `rate_limit_mode`;跨账户设备(约 58%)仍为核心验收场景(第三部分第 9 节)。
- 分层配置的间隔区分三态:正数按间隔、`0` 不检查、空继承;保持空 = 继承不改变现有配置行为。优先级可后台调整(单条、整体排序),相同优先级按 ID 排序;提供匹配预览与"立即重算到期时间"(第三部分第 11.3 节)。
- 所有后台配置、告警、不轮询清单、停复机记录都提供查询与修改接口,供前端建页面;标量参数复用 `/system-configs`(新增 `polling` 模块与 JSON 结构校验);停复机出口全局开关从 yaml 改为受控系统配置(第三部分第 14 节)。
- 复机不看停机原因,包括运营商侧主动停机 `carrier_stopped`,只由本系统规则决定(第三部分第 12 节)。
- 风险停机、已销户的卡必须关闭轮询:保留现有查状态自动关闭;补齐绑定设备的卡(只关该卡自身)与停复机调用直接返回终态两种情况(第三部分第 12 节、6.2 节)。
- 停复机新规则在生产开启前必须完成实名管控配置与上线前演练(只判断不执行的演练接口),生产约 1.5 万张未实名停机卡可能满足复机条件(第三部分第 12 节、第五部分第 3 节)。
- Asynq 任务(Outbox 消费者、观测序列)遇到限流不计入重试次数、按固定短延迟重试(Asynq `IsFailure` 与 `RetryDelayFunc`),避免"流量用完停机"在高峰期被推迟数小时或归档丢失(第五部分第 3 节)。
- change 1 先以"只统计"模式全量上线,按数据配置后逐个账户切到"拦截"(第五部分第 3 节、7.2 节)。
- 去掉保护期时 `device_protect_status` 字段保留、固定返回无保护期并标记废弃,不直接删除(第四部分)。
- OpenSpec 拆分(2026-10-24):7 个 change 对应 `openspec/changes/` 下 `add-carrier-gateway-rate-limit`、`add-tiered-polling-and-pre-activation-settlement`、`remove-device-protect-period`、`finalize-unified-stop-resume-rule`、`add-carrier-polling-scheduler`、`add-stop-resume-command-queue`、`add-polling-pause-list-and-batch-toggle`;拆分时更正:OpenAPI 查询不触发观测、不属于读入口;change 4 分两次发布(先演练与补齐、开启总开关,稳定后删除总开关);失败告警表在 change 5 建立,change 7 只做停机被拒视图与告警页批量关闭;测试按项目规则在测试环境逐项核对,不写自动化测试代码。
- 实施依赖修正:到期即停移到 change 6;change 4 依赖 `Iteration/8-11` 上线生产;激活前结算依赖日快照计量在生产验证;change 6 依赖 change 4(第五部分第 3 节)。
待确认:无。
后续事项(不在本方案范围):
1. 批量查询:gateway 支持后,在分发器按运营商账户凑批、查询结果经 `StepInput.Result` 传入卡任务。
2. 限流覆盖剩余入口(后台人工点击、通道阈值、自动续费、手动刷新):去掉这 4 个入口的"豁免限流"标记即可。
3. 手动刷新后不再立即重新轮询全部类型,改为顺延已刷新类型的 `due`。
4. 停复机业务规则与老系统的差异(提前停机天数、停机前续费、流量超额续充)单独讨论。