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,109 @@
## REMOVED Requirements
### Requirement: 停复机新规则总开关
**Reason**: 新规则转正为唯一口径,不再保留旧口径与总开关。
**Migration**: 删除配置项与部署变量 `JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED`;发布前完成实名管控配置与规则演练。
## MODIFIED Requirements
### Requirement: 自动停机条件
系统 SHALL 对开机的卡在满足任一条件时自动停机:卡(绑定设备时按设备)没有套餐;流量已用完;卡所属通道开启实名管控且卡未实名。停机原因按命中条件分别记为 `no_package`、`traffic_exhausted`、`not_realname`。无套餐与流量用完扩散到设备下全部开机卡,未实名只停该卡。系统 MUST NOT 因卡当前开机是由外部、人工或其他原因造成而改变判断。
#### Scenario: 套餐到期
- **WHEN** 开机卡绑定的设备没有套餐
- **THEN** 系统停机设备下全部开机卡,停因为 `no_package`
#### Scenario: 通道开启实名管控的未实名卡
- **WHEN** 卡所属通道开启实名管控,卡未实名且开机
- **THEN** 系统只停这张卡,停因为 `not_realname`
#### Scenario: 通道未开启实名管控的未实名卡
- **WHEN** 卡所属通道未开启实名管控,卡未实名、有套餐、流量未用完且开机
- **THEN** 系统不停机
### Requirement: 自动复机条件不看停机原因
系统 SHALL 对停机的卡在同时满足以下条件时自动复机:卡(绑定设备时按设备)有套餐;流量未用完;卡已实名或卡所属通道未开启实名管控。系统 MUST NOT 以停机原因决定是否复机:运营商侧主动停机(`carrier_stopped`)、卡管人工停机(`manual`)、历史保护期停机(`protect_period`)、未实名、无套餐、流量耗尽及停因为空的卡满足条件都复机,是否复机只由本系统规则决定。持有本周期通道阈值锁的卡 MUST 拒绝复机。设备复机时系统 SHALL 逐张判断设备下全部停机卡,不满足实名条件的卡跳过并记停因 `not_realname`,其他卡照常复机。外部反复停机时,系统每次评估均按上述条件复机,不设次数上限。停机原因只用于展示与审计。上游对复机返回终态时,按"风险停机与已销户关闭轮询"处理,不重试。
#### Scenario: 外部停机后满足条件
- **WHEN** 卡被外部停机后记为 `carrier_stopped`,有套餐、流量未用完、实名条件满足
- **THEN** 下一次评估时系统自动复机并清空停因
#### Scenario: 人工停机后满足条件
- **WHEN** 管理员手动停机的卡有套餐、流量未用完、实名条件满足
- **THEN** 下一次评估时系统自动复机
#### Scenario: 开启实名管控的通道中未实名的停机卡
- **WHEN** 卡所属通道开启实名管控,卡未实名、停机、有套餐
- **THEN** 系统不复机;卡实名后下一次评估复机
#### Scenario: 持有通道阈值锁
- **WHEN** 停机卡在本周期持有通道阈值锁,其他条件均满足
- **THEN** 系统拒绝复机并保留锁
### Requirement: 通道实名管控配置、权限与审计
系统 SHALL 在运营商通道上提供独立的实名管控开关 `realname_control_enabled`(0 不管控、1 管控),默认 0,MUST NOT 复用通道现有的实名链接类型等字段。开启时,通道下所有卡停复机只按卡是否已实名判断,MUST NOT 以行业卡身份或卡、设备上的实名策略放行;实名策略仍只用于购买与首次实名激活流程。仅超级管理员和平台用户 SHALL 在通道新建或编辑时配置该开关,非平台账号提交该字段 MUST 被拒绝;修改并入通道更新审计。从 0 改为 1 时,管理端 MUST 二次确认并提示该通道未实名的开机卡数。查询卡所属通道的实名管控失败时,系统本次不对该卡发起停复机并记录日志。人工复机同样按本要求判断实名。
#### Scenario: 默认不管控
- **WHEN** 通道未修改实名管控,非行业卡未实名、卡实名策略为 `after_order`、有套餐且流量未用完
- **THEN** 系统不因未实名停机,人工复机不因未实名被拒
#### Scenario: 开启后行业卡不再放行
- **WHEN** 通道开启实名管控,行业卡未实名且开机
- **THEN** 系统停机该卡,停因为 `not_realname`
#### Scenario: 越权修改实名管控
- **WHEN** 非超级管理员、非平台用户提交通道实名管控字段
- **THEN** 系统拒绝请求且不修改配置
#### Scenario: 查询通道失败
- **WHEN** 停复机评估时卡所属通道的实名管控查询失败
- **THEN** 系统本次不对该卡发起停复机命令并记录日志
### Requirement: 暂停轮询的卡不自动停复机
卡或其绑定设备暂停轮询的,系统 SHALL NOT 对该卡发起自动停机或自动复机,包括套餐激活、套餐重置、充值等非轮询触发的复机;人工停机与人工复机照常执行。网关扩展状态为风险停机或已销户的卡 MUST 关闭该卡自身轮询,不论是否绑定设备:查卡状态返回该扩展状态时关闭;停复机调用直接返回命中"自动关闭轮询"规则的终态时,同样关闭并回写网关扩展状态。关闭只作用于该卡,MUST NOT 级联关闭设备与设备下其他卡。机卡分离停机等其他运营商异常状态 MUST NOT 自动关闭轮询,由人工判断。未暂停轮询的卡,不论运营商扩展状态如何,均按停机与复机条件处理,上游拒绝复机时按现有失败处理。
#### Scenario: 暂停轮询的卡充值后
- **WHEN** 已被人工暂停轮询的停机卡充值并激活套餐
- **THEN** 系统不自动复机;人工复机照常可用
#### Scenario: 恢复轮询后
- **WHEN** 维护者为该卡恢复轮询
- **THEN** 下一次评估起系统按停机与复机条件正常处理
#### Scenario: 设备卡出现机卡分离停机
- **WHEN** 设备下的卡运营商扩展状态为机卡分离停机且未被暂停轮询
- **THEN** 系统不自动暂停轮询,按停机与复机条件处理
#### Scenario: 设备下的卡被销户
- **WHEN** 查卡状态返回绑定设备的某张卡扩展状态为已销户
- **THEN** 系统关闭该卡轮询,设备与设备下其他卡的轮询不变
#### Scenario: 复机返回风险停机
- **WHEN** 复机调用返回"当前卡为风险停机状态,仅支持风险复机"且该规则标记自动关闭轮询
- **THEN** 系统不重试,关闭该卡轮询并回写扩展状态为风险停机
## ADDED Requirements
### Requirement: 实名轮询按通道实名管控跳过
系统 SHALL 在卡所属运营商账户未开启实名管控时跳过该卡的实名查询(结果不影响停复机),开启时照常查询;MUST NOT 再按卡类别(行业卡)跳过实名查询。
#### Scenario: 未开管控账户的普通卡
- **WHEN** 卡所属账户 `realname_control_enabled = 0`,实名检查到期
- **THEN** 系统不调用网关查实名,按正常间隔安排下次检查
#### Scenario: 开启管控账户的行业卡
- **WHEN** 卡所属账户开启实名管控,行业卡实名检查到期
- **THEN** 系统调用网关查实名
### Requirement: 停复机规则演练
系统 SHALL 提供只判断不执行的停复机规则演练:对停机卡与开机卡按本能力规则判断目标状态,按运营商账户 × 停机原因 × 判断结果(将复机、将停机、不动作及不动作原因)返回汇总与明细,可按运营商账户与停机原因筛选,可传入假设的通道实名管控配置预演。演练 MUST NOT 调用网关、MUST NOT 写任何卡、指令或调度状态。明细 SHALL 可通过统一导出任务导出。接口仅超级管理员与平台用户可用。
#### Scenario: 开启前预演
- **WHEN** 运营在所有账户实名管控为 0 时执行演练
- **THEN** 系统返回各账户将被复机的 `not_realname` 卡数与明细,卡状态不变
#### Scenario: 假设开启管控
- **WHEN** 运营假设账户 A 开启实名管控执行演练
- **THEN** 系统按假设配置返回账户 A 将停机的未实名开机卡数,实际配置不变

View File

@@ -0,0 +1,36 @@
## MODIFIED Requirements
### Requirement: 通道阈值停机与周期恢复
系统 SHALL 为每个已启用运营商通道按通道既有的上游流量重置日(与网关计数器清零同一事实,上海时区周期边界)判断运营商回传的每张卡当前周期累计流量,累计流量仅取网关累计读数换算,不使用本地用量统计或套餐真流量;每张卡独立判断,不扩散到设备维度,不进入既有停复机的设备扩散路径。达到或超过阈值时,系统为当前周期创建通道阈值停机锁并创建可靠停机任务;同一周期重复判定、并发或任务重放不得重复创建锁或重复发起停机。改阈值不生效于当前周期已持锁卡:当前周期维持拒绝复机,新周期按新阈值判断。
持锁卡在当前周期内 MUST 拒绝一切复机,包括自动复机、手动复机和机卡分离复机;拒绝时保留锁并记录拒绝事实。停机调用失败或结果未知时保留锁与任务状态,由本能力新增的恢复扫描处理:只查询运营商状态回填、确认成功后补写卡状态;自提交起超过约定窗口仍无法确认结果的,标记异常并转人工处理,不自动删除锁。本能力新增停因 `channel_threshold`,不参与既有自动复机判定,复机仅由周期处理发起。
新周期开始时,系统 SHALL 对仍持锁卡解除通道锁;复机条件为 `card-stop-resume` 的复机条件:有套餐、流量未用完、卡已实名或卡所属通道未开启实名管控,且卡与其绑定设备未暂停轮询;不以其他停机原因或网关扩展状态阻止复机,条件满足时创建自动复机任务,不满足时只解锁不调用运营商。复机失败或结果未知同样由恢复扫描处理。卡更换运营商后,旧周期锁保留,新周期按新运营商的重置日计算。
#### Scenario: 达量后人工复机
- **WHEN** 当前计费周期内持有通道阈值停机锁的卡请求复机
- **THEN** 系统拒绝复机且保留该锁
#### Scenario: 达量后机卡分离复机被拒
- **WHEN** 当前计费周期内的持锁卡触发机卡分离复机
- **THEN** 系统拒绝复机、保留该锁并记录拒绝事实
#### Scenario: 停机结果未知恢复确认
- **WHEN** 通道阈值停机调用后结果未知,恢复扫描向运营商查询确认卡已停机
- **THEN** 系统补写卡停机状态并将任务结果记为已确认
#### Scenario: 停机结果未知超期转人工
- **WHEN** 通道阈值停机任务自提交起超过约定窗口仍无法确认结果
- **THEN** 系统标记异常并留存安全失败原因转人工处理,不自动删除锁
#### Scenario: 换运营商后周期归属
- **WHEN** 持锁卡更换运营商后到达新计费周期
- **THEN** 旧周期锁保留,新周期按新运营商的上游流量重置日计算并处理
#### Scenario: 新周期存在其他停因
- **WHEN** 新周期开始的持锁卡停因记录为人工停机,有套餐、流量未用完、实名条件满足且未暂停轮询
- **THEN** 系统解除通道阈值锁并创建自动复机任务
#### Scenario: 新周期卡已暂停轮询
- **WHEN** 新周期开始的持锁卡已被暂停轮询
- **THEN** 系统解除通道阈值锁但不调用运营商复机

View File

@@ -0,0 +1,13 @@
## ADDED Requirements
### Requirement: 终态规则可标记自动关闭轮询
系统 SHALL 允许错误分类规则标记"自动关闭轮询",且只允许类别为"终态不可操作"的规则勾选;保存其他类别的规则并勾选时 MUST 拒绝。初始数据中"已销户""风险停机"类终态规则 MUST 置位,"物联网号码封存"等其他终态不置位。
#### Scenario: 非终态规则勾选
- **WHEN** 维护者为"频率限制"类规则勾选自动关闭轮询
- **THEN** 系统拒绝保存
#### Scenario: 号码封存
- **WHEN** 停机返回"用户状态是物联网号码封存,禁止办理物联网停机"
- **THEN** 该次归为终态不可操作,不自动关闭轮询,按失败告警处理

View File

@@ -0,0 +1,5 @@
## REMOVED Requirements
### Requirement: 停复机遵循实际生效实名策略
**Reason**: 停复机新规则转正,实名门槛唯一由 `card-stop-resume` 的通道实名管控决定,行业卡与卡、设备实名策略不再参与停复机。
**Migration**: 需要实名的运营商账户设置 `realname_control_enabled = 1`;发布前用停复机规则演练核对受影响卡。