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,31 @@
## ADDED Requirements
### Requirement: 流量按观测时间归属
系统 SHALL 为每次流量观测记录网关返回时的观测时间;入账时若资产已有生效主套餐但观测时间早于该套餐的激活时间,本次增量 MUST 只记为已结算、不扣减该套餐。该规则 MUST 对全部流量观测生效(轮询、激活前结算、手动刷新)。
#### Scenario: 慢返回的结算晚于另一入口激活
- **GIVEN** 资产无生效套餐,激活前结算 10:00:00 发出查询,另一入口 10:00:02 激活了套餐
- **WHEN** 结算结果 10:00:05 返回并入账,观测时间早于激活时间
- **THEN** 本次增量只记已结算,不扣新套餐
#### Scenario: 激活后的观测正常扣减
- **WHEN** 观测时间晚于套餐激活时间
- **THEN** 增量按现有规则扣减套餐
### Requirement: 激活前流量结算
对已切换日快照计量的卡,系统 SHALL 在资产从"无生效主套餐"变为"有生效主套餐"之前(实名激活、排队激活、指定激活、队首激活、订单购买即生效),对独立卡查一次流量、对设备逐张查设备下各卡,并按现有观测入账(此时无套餐,增量只记已结算),然后再执行激活。已有生效主套餐(续费、排队衔接)与流量重置 MUST NOT 执行结算。结算观测 MUST 携带"激活前结算"标记,入账照常但 MUST NOT 触发停复机评估;激活提交后的评估是激活链路唯一一次评估。结算查询 MUST 受运营商账户限流约束;单卡限流等待超过单步超时、查询失败或整次结算达到总超时时,系统 MUST 跳过剩余结算、照常激活,并按卡写告警。未切换日快照计量的卡 MUST 不做结算。
#### Scenario: 二次销售激活
- **GIVEN** 卡上一用户本月已用 3 GB,当前无生效套餐
- **WHEN** 新用户购买套餐即生效
- **THEN** 系统先查流量并把 3 GB 记为已结算,再激活,新套餐不承担这 3 GB
#### Scenario: 结算不触发停机
- **WHEN** 结算观测入账时资产无套餐
- **THEN** 系统不生成"无有效套餐"停机,激活提交后再评估一次停复机
#### Scenario: 结算超时
- **WHEN** 设备下第 3 张卡结算时整次结算达到总超时
- **THEN** 系统跳过剩余卡、照常激活,并为未结算的卡写告警

View File

@@ -0,0 +1,13 @@
## ADDED Requirements
### Requirement: 无套餐到有套餐的激活入口共用资产级激活锁
系统 SHALL 让所有使资产从"无生效主套餐"变为"有生效主套餐"的入口(实名激活、排队激活、指定激活、队首激活、订单购买即生效)在同一把资产级激活锁内执行"激活前流量结算 → 激活事务"。锁 TTL MUST 大于结算总超时与激活事务耗时之和;抢锁失败的入口 MUST 按各自现有的冲突处理返回或重试,不得在锁外执行激活。订单购买路径原有的卡或设备行锁 MUST 保留。
#### Scenario: 实名激活与订单购买并发
- **WHEN** 同一资产的实名回调激活与客户购买即生效同时到达
- **THEN** 两者串行执行,后执行者看到已有生效主套餐,不再做结算并按排队规则处理
#### Scenario: 续费不加结算
- **WHEN** 资产已有生效主套餐时续费
- **THEN** 系统不做激活前结算,按现有排队衔接处理

View File

@@ -0,0 +1,79 @@
## ADDED Requirements
### Requirement: 按套餐状态与资产状态分层匹配
系统 SHALL 在现有匹配维度(网络与实名状态、卡类别、运营商账户)之外,按套餐状态(有生效套餐、套餐已用完、只有待生效套餐、无套餐)与资产状态(在库、已销售、已换货、已停用)匹配轮询配置;维度为空表示不限。绑定设备的卡 MUST 按设备计算套餐状态,独立卡按卡计算,口径与现有"是否有有效套餐"判断一致。系统 MUST 在卡任务执行完收尾、全量初始化、生命周期重新匹配时计算层级,卡的层级最迟在下一次执行时更新。
#### Scenario: 套餐到期后降层
- **GIVEN** 卡原匹配"有生效套餐"层,套餐已过期
- **WHEN** 该卡下一次轮询执行完收尾
- **THEN** 系统按"无套餐"层的间隔计算各检查类型下次到期时间
#### Scenario: 设备卡同层
- **WHEN** 设备下 2 张卡分属不同运营商账户,设备有生效套餐
- **THEN** 两张卡都按"有生效套餐"匹配
### Requirement: 检查间隔三态与合并
系统 SHALL 区分每种检查类型间隔的三种取值:正数(秒)表示按此间隔检查并停止向下查找;`0` 表示不检查并停止向下查找;空表示继承,继续查找优先级更低的配置。系统 MUST 按优先级升序、优先级相同按配置 ID 升序遍历启用的匹配配置,对每种检查类型取第一个非空取值。接口 MUST 接受 `0` 或不小于该类型最小间隔的正数,拒绝其他值。
#### Scenario: 无套餐层不查流量
- **GIVEN** "无套餐"层流量间隔为 `0`,优先级更低的兜底配置流量间隔为 3600
- **WHEN** 无套餐卡匹配这两条配置
- **THEN** 该卡不做流量检查
#### Scenario: 空值继承
- **GIVEN** 高优先级配置实名间隔为空,低优先级配置实名间隔为 7200
- **WHEN** 卡同时匹配两条配置
- **THEN** 该卡实名检查间隔为 7200
#### Scenario: 相同优先级
- **WHEN** 两条启用配置优先级都为 1 且同时匹配一张卡
- **THEN** 系统按配置 ID 较小者优先,结果在多次计算间保持一致
### Requirement: 无套餐层与库存层必须检查卡状态
系统 SHALL 拒绝保存匹配"无套餐且已销售"或"在库"的配置中卡状态检查间隔为空或 `0` 的情况。已销售无套餐、在库的卡未匹配到任何配置时,系统 MUST 告警且不入队。
#### Scenario: 库存层未配卡状态
- **WHEN** 维护者保存资产状态为"在库"、卡状态间隔为 `0` 的配置
- **THEN** 系统拒绝保存并提示该层必须配置卡状态检查
### Requirement: 优先级调整、匹配预览与重算到期时间
系统 SHALL 允许超级管理员单条修改配置优先级,以及一次提交全部配置顺序整体重排(事务内完成)。保存时若与其他启用配置优先级相同且匹配条件可能重叠,系统 MUST 提示但不拦截。系统 SHALL 提供匹配预览:输入 ICCID(可附带未保存的修改),返回该卡各匹配维度取值、命中配置列表,以及每种检查类型最终采用的间隔与来源(按间隔、不检查、继承自某配置、未匹配),预览 MUST 不写任何数据。系统 SHALL 提供"立即重算到期时间"异步任务(可按运营商账户限定),新到期时间 = min(当前到期, 上次检查时间 + 新间隔),只提前不推后,只更新调度状态、不调网关,返回任务 ID 与进度。
#### Scenario: 整体排序
- **WHEN** 超级管理员提交新的配置顺序
- **THEN** 系统按顺序重排优先级,各进程在配置刷新后按新顺序匹配
#### Scenario: 预览未保存修改
- **WHEN** 运营带上"把某配置流量间隔改为 0"的未保存修改预览一张卡
- **THEN** 系统返回修改后的最终间隔与来源,配置与调度状态不变
#### Scenario: 缩短间隔后重算
- **GIVEN** 某层流量间隔从 86400 改为 3600,卡 A 上次查流量在 2 小时前、当前到期在 20 小时后
- **WHEN** 执行重算到期时间
- **THEN** 卡 A 流量检查到期时间改为上次检查后 1 小时(即立即到期),且仍受运营商账户限流约束执行
### Requirement: 重置日前加密查流量
系统 SHALL 在配置了 `pre_reset_window` 与 `pre_reset_carddata_interval` 的层内,于卡所属运营商账户重置时刻(重置日当天 0 点,业务时区)前的窗口内,按窗口间隔安排流量检查:窗口内下次到期 = 当前 + 窗口间隔,若越过重置时刻则改为"重置时刻 − 收尾提前量"(已过则不再加查);窗口前按正常间隔算出的到期越过窗口起点时截断到窗口起点;越过重置时刻后恢复正常间隔。两列为空表示该配置不加密。
#### Scenario: 窗口内最后一次查询
- **GIVEN** 重置日为 1 号,窗口 6 小时,窗口间隔 30 分钟,收尾提前量 5 分钟,当前为 31 号 23:40
- **WHEN** 计算流量下次到期
- **THEN** 下次到期为 31 号 23:55,而不是 1 号 00:10
#### Scenario: 截断到窗口起点
- **GIVEN** 正常间隔 1 天,当前为 31 号 10:00,窗口起点 31 号 18:00
- **WHEN** 计算流量下次到期
- **THEN** 下次到期为 31 号 18:00
### Requirement: 分层与加密效果可观测
系统 SHALL 提供按层的卡数与漏配告警卡数统计,以及按运营商账户、按重置周期的"有生效套餐但窗口内未查到流量"卡数与最后一次查询距重置时刻的分布。
#### Scenario: 查看分层统计
- **WHEN** 运营查询分层统计
- **THEN** 系统返回每层卡数与未匹配任何配置的已销售无套餐、在库卡数