## 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.gateway.rate_limit_mode` 全局决定限流模式:`observe` 时照常计数(实际 QPS、本应被拦截的次数)但不拦截、不等待;`enforce` 时按限流组拦截。默认值 MUST 为 `observe`。模式修改 MUST 即时生效,不需要重新部署。模式不得按运营商账户覆盖。 #### Scenario: 只统计模式下超出上限 - **GIVEN** 模式为 `observe`,账户 A 查询组本秒已达上限 - **WHEN** 再查询 A 账户下一张卡 - **THEN** 系统照常发出请求,并把该次计入"本应被限流"次数 #### Scenario: 切换为拦截 - **WHEN** 超级管理员把 `polling.gateway.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** 系统拒绝并保留原配置