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,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** 系统返回各检查类型下次到期时间、最近错误与是否执行中,不改变任何状态