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,108 @@
## ADDED Requirements
### Requirement: 卡网关操作按运营商账户限流
系统 SHALL 对卡的 5 个网关操作(查流量、查状态、查实名、停机、复机)按目标卡所属运营商账户与操作类型找到所属限流组,并在每秒请求数达到该组 `max_qps` 时拒绝或延后本次请求。限流窗口 MUST 跨全部 API 与 Worker 进程共享。设备停复机拆分到卡后,每张卡 MUST 各自按其所属运营商账户查找限流组。未被任何启用的限流组覆盖的操作(含所在组已停用)MUST 按默认 QPS 限流,不得出现不限流的自动调用。配置了全局组时,请求 MUST 同时满足账户组与全局组才放行。
#### Scenario: 账户组 QPS 用满
- **GIVEN** 运营商账户 A 的查询组 `max_qps = 20`,当前 1 秒窗口内已放行 20 次查询
- **WHEN** 第 21 次查询 A 账户下卡的流量
- **THEN** 系统在拦截模式下不发出该 HTTP 请求,返回"限流"结果
#### Scenario: 不同账户互不影响
- **GIVEN** 账户 A 的查询组本秒已用满
- **WHEN** 查询账户 B 下卡的状态
- **THEN** 系统按账户 B 的限流组判断,不受账户 A 影响
#### Scenario: 限流组停用
- **WHEN** 账户 A 的停复机组被停用后发起 A 账户下卡的停机
- **THEN** 系统按默认 QPS 限流该次停机,不得不限流放行
#### Scenario: 全局组
- **GIVEN** 配置了覆盖查询操作的全局组且其本秒已用满,账户 A 查询组仍有余量
- **WHEN** 查询账户 A 下卡的流量
- **THEN** 系统按全局组拒绝本次请求
### Requirement: 按每次实际 HTTP 请求计量
系统 SHALL 在每次向网关发出 HTTP 请求之前各取一次限流名额,网关客户端一次方法调用内部的重试请求 MUST 各自计量。拿不到名额时,本次方法调用 MUST 结束且不再发起后续尝试。
#### Scenario: 查询内部重试
- **GIVEN** 查流量第一次请求超时,网关客户端准备进行第二次尝试
- **WHEN** 第二次尝试发出前
- **THEN** 系统为第二次尝试再取一次名额,名额不足时不发出第二次请求并返回"限流"结果
### Requirement: 默认限流与显式豁免
系统 SHALL 对卡的 5 个网关操作默认限流;只有后台人工点击的停复机、通道阈值、自动续费、手动刷新 4 个入口 MAY 携带豁免标记绕过限流,豁免调用 MUST 按豁免来源计数以便监控。未携带豁免标记的调用(含今后新增的入口)MUST 受限流约束。
#### Scenario: 新增自动入口未处理标记
- **WHEN** 任一未声明豁免的入口调用停机
- **THEN** 该调用受所属限流组约束
#### Scenario: 后台人工点击停机
- **WHEN** 运营在后台对单卡点击停机
- **THEN** 该调用不受限流约束,并计入"人工点击"豁免调用量
### Requirement: 高优先级操作预留额度
当同一限流组内包含停机、复机与其他操作且配置了高优先级操作与 `reserved_qps` 时,系统 SHALL 让普通操作最多使用 `max_qps − reserved_qps`,高优先级操作可用满 `max_qps`;高优先级请求等待名额期间,普通操作 MUST 拿不到新名额。保存限流组时,系统 MUST 拒绝 `reserved_qps ≥ max_qps`、高优先级操作不属于本组操作、同一运营商账户下同一操作属于多个组的配置。
#### Scenario: 共享组内普通操作受预留约束
- **GIVEN** 广电账户一个组含全部 5 个操作,`max_qps = 10`,停机与复机为高优先级,`reserved_qps = 3`
- **WHEN** 本秒已放行 7 次查询后再发起查询
- **THEN** 系统拒绝该查询;同一秒内的停机仍可放行至第 10 次
#### Scenario: 同一操作重复归组
- **WHEN** 维护者为账户 A 新建组并包含已属于另一组的"查流量"
- **THEN** 系统拒绝保存并提示该操作已属于其他组
### Requirement: 只统计与拦截两种模式
系统 SHALL 按受控系统配置 `polling.rate_limit_mode` 全局决定限流模式:`observe` 时照常计数(实际 QPS、本应被拦截的次数)但不拦截、不等待;`enforce` 时按限流组拦截。默认值 MUST 为 `observe`。模式修改 MUST 即时生效,不需要重新部署。模式不得按运营商账户覆盖。
#### Scenario: 只统计模式下超出上限
- **GIVEN** 模式为 `observe`,账户 A 查询组本秒已达上限
- **WHEN** 再查询 A 账户下一张卡
- **THEN** 系统照常发出请求,并把该次计入"本应被限流"次数
#### Scenario: 切换为拦截
- **WHEN** 超级管理员把 `polling.rate_limit_mode` 改为 `enforce`
- **THEN** 下一次请求起按限流组拦截,无需重启进程
### Requirement: Asynq 任务内遇限流不等待且不计失败
在拦截模式下,系统 SHALL 让 Asynq 任务内发起的受限调用拿不到名额时立即返回"限流"错误,不在任务内等待名额。轮询任务遇限流 MUST 按 `rate_limited_retry_delay` 短延迟重新入队且不计为失败。其余 Asynq 任务(含 Outbox 消费者、观测序列)返回"限流"错误时,Asynq MUST 不将其计为失败、不增加重试计数,并按固定短延迟重试;其他错误的重试行为 MUST 不变。同一任务因限流累计推迟超过上限时,系统 MUST 写告警且任务继续重试。
#### Scenario: 流量用完停机遇限流
- **GIVEN** 流量入账后的 Outbox 消费者判断需要停机,停复机组本秒已用满
- **WHEN** 消费者调用停机拿不到名额
- **THEN** 任务以"限流"错误结束,Asynq 不增加重试计数,几秒后重试,不会因连续限流推迟数小时或被归档
#### Scenario: 非限流错误
- **WHEN** Outbox 消费者因数据库错误失败
- **THEN** Asynq 按原有重试次数与递增间隔处理
### Requirement: 停复机不使用网关内部重试
系统 SHALL 对停机、复机网关调用只发出一次 HTTP 请求,不使用网关客户端的内部重试,对全部停复机入口生效(含后台人工点击、通道阈值、自动续费)。超时或连接失败 MUST 按结果未知返回给调用方。
#### Scenario: 停机超时
- **WHEN** 停机请求超时
- **THEN** 系统不在同一次调用内再发停机请求,向调用方返回结果未知
#### Scenario: 后台人工点击停机网络抖动
- **WHEN** 运营点击停机时连接失败
- **THEN** 页面返回失败,由运营重新操作,系统不自动重试
### Requirement: 限流组与限流参数可后台维护
系统 SHALL 提供限流组的列表(按运营商账户筛选,含全局组)、新建、详情、修改、启停、删除接口;修改类接口仅超级管理员可用并写统一审计。保存后 MUST 同步到共享缓存,下一次请求起生效。限流模式、限流短延迟、限流累计推迟告警上限等标量参数 SHALL 通过受控系统配置 `module = polling` 维护,列表 MUST 支持按 `polling` 模块筛选。
#### Scenario: 修改 QPS 即时生效
- **WHEN** 超级管理员把账户 A 查询组 `max_qps` 从 20 改为 30
- **THEN** 下一次请求起按 30 判断,无需重启
#### Scenario: 非超级管理员修改
- **WHEN** 非超级管理员提交限流组修改
- **THEN** 系统拒绝并保留原配置

View File

@@ -0,0 +1,61 @@
## ADDED Requirements
### Requirement: 网关结构化错误
系统 SHALL 让网关客户端在失败时返回结构化错误,包含错误类别(网络、超时、HTTP 异常、响应无效、上游业务错误、限流)、网关业务码与信息、耗时。上游信息 MUST 脱敏截断后才可落库或展示。
#### Scenario: 上游业务错误
- **WHEN** 网关返回业务码 400 与信息"当前用户已销户,无法操作"
- **THEN** 调用方拿到类别"上游业务错误"、业务码 400、该信息与本次耗时
### Requirement: 上游错误分类
系统 SHALL 按后台维护的关键字规则把上游错误归入频率限制、终态不可操作、已是目标状态、临时故障、业务错误、账户配置错误之一;规则包含关键字、匹配方式、类别、适用操作、启用状态。只有明确表示卡已处于目标状态的返回 MAY 归入"已是目标状态";"密码错误""参数缺失"MUST 归入账户配置错误;"当前用户不允许办理""防范实名"MUST NOT 归入已是目标状态。未命中任何规则的上游业务错误 MUST 归入业务错误。系统 SHALL 提供测试接口:输入一段上游返回信息与操作,返回命中的规则与类别。
#### Scenario: 已停机返回
- **WHEN** 停机返回信息命中"已是目标状态"规则
- **THEN** 该次结果归为已是目标状态
#### Scenario: 密码错误
- **WHEN** 停机返回"密码错误"
- **THEN** 该次结果归为账户配置错误,不视为停机成功
#### Scenario: 测试规则
- **WHEN** 运营在新增规则前用测试接口输入"3分钟内同一张卡相同操作仅允许一次"
- **THEN** 系统返回命中的规则与"频率限制"类别,不写任何业务数据
### Requirement: 停复机调用逐次记录
系统 SHALL 在每次实际调用上游停机或复机后写一条停复机记录:卡、ICCID、运营商账户、动作、来源与场景、停机原因、尝试序号、结果(成功、失败、结果未知、已是目标状态)、错误类别、上游返回码与信息(脱敏截断)、耗时、记录时间。系统自动停复机(轮询、Outbox、激活、重置、退款等系统任务发起,且未带限流豁免标记)MUST 不再写统一审计与集成日志;后台人工点击、通道阈值、自动续费(带豁免标记),以及账户、个人客户、OpenAPI 发起的停复机 MUST 仍写统一审计与集成日志并同时写停复机记录(通道阈值与自动续费的结果未知恢复依赖集成日志标识)。未调用上游的拒绝类审计(如通道阈值锁拒绝复机)保持不变。被本系统限流拒绝、未发出请求的停复机 MUST NOT 写记录。记录写入失败 MUST 只记日志与计数,不影响卡状态与停机原因回写。记录按月分区,系统 MUST 提前创建未来若干个月的分区并保留默认分区,使任何月份的插入都不因分区缺失失败;保留期可配置,到期整区删除。
#### Scenario: 流量用完自动停机
- **WHEN** 轮询判定流量用完并成功停机
- **THEN** 系统写一条结果为成功的停复机记录,不写统一审计事件与集成日志
#### Scenario: 后台人工点击复机失败
- **WHEN** 运营点击复机且上游返回业务错误
- **THEN** 系统写统一审计,并写一条结果为失败、带错误类别与上游信息的停复机记录
#### Scenario: 未来月份分区缺失
- **WHEN** 某月分区尚未创建时写入记录
- **THEN** 记录写入默认分区,插入成功
### Requirement: 查询调用不逐条落库
系统 SHALL 不为普通轮询查询(查流量、查状态、查实名)逐条写集成日志,包括"数据有变化"的成功调用;本轮同时是一次优先执行时,按优先轮询可追溯要求仍写集成日志并回写优先项;改为在共享缓存中按"运营商账户 × 操作 × 结果类别"做分钟级计数与耗时分布,并在卡上保留各检查类型最近一次错误(类别、码、信息、时间)。业务事实变化(网络、实名、套餐、有效流量)MUST 仍按现有规则持久化业务记录。
#### Scenario: 查流量失败
- **WHEN** 轮询查流量超时
- **THEN** 系统不写集成日志,对应分钟计数的"超时"加一,卡上流量类型的最近错误更新为超时
### Requirement: 按账户调用量与停复机记录可查询
系统 SHALL 提供:按运营商账户的调用量统计(各操作实际 QPS、成功率、按类别的失败数、p95 耗时、本应被限流次数、豁免调用量,分钟级趋势);停复机记录列表(按 ICCID、运营商账户、动作、来源、结果、错误类别、时间范围筛选,时间范围必填且有上限)与单卡停复机历史;前端下拉所需的操作类型、错误类别等枚举。查询接口 MUST 需要登录并遵守现有数据权限。
#### Scenario: 无时间范围查询记录
- **WHEN** 请求停复机记录列表未带时间范围
- **THEN** 系统拒绝请求并提示时间范围必填
#### Scenario: 只统计期间评估 QPS
- **WHEN** 运营在 `observe` 模式下查看账户 A 近一周统计
- **THEN** 系统返回各操作实际 QPS 峰值与本应被限流次数,作为配置限流组的依据

View File

@@ -0,0 +1,17 @@
## MODIFIED Requirements
### Requirement: 业务变化与轮询异常仍可追溯
系统 SHALL 在轮询产生网络、实名、套餐或有效流量等业务事实变化时持久化必要的业务事实与审计记录。外部调用失败、响应无效或结果未知时,系统 MUST 保留可调查的失败或恢复信息,且不得把失败静默降级为正常无变化观测。系统自动停复机的每次上游调用 MUST 以停复机记录保留结果与失败原因,不再写统一审计与集成日志;查询类调用失败 MUST 以按运营商账户的分钟计数与卡上各检查类型最近一次错误保留可调查信息,普通轮询不逐条写集成日志;同时是优先执行的轮次仍写集成日志供优先项追溯。
#### Scenario: 轮询产生网络状态变化
- **GIVEN** 渠道返回的网络状态与当前业务事实不同
- **WHEN** 系统成功应用该状态变化
- **THEN** 系统持久化业务状态变化及相应审计事实
#### Scenario: 轮询渠道调用失败
- **WHEN** 轮询调用渠道超时、失败或返回无效响应
- **THEN** 系统更新对应分钟计数与该卡该检查类型的最近错误,并按既有策略安排后续处理
#### Scenario: 自动停机失败
- **WHEN** 系统自动停机时上游返回业务错误
- **THEN** 系统写一条带错误类别与上游信息的停复机记录,不写统一审计与集成日志