Files
邹进 42e881576d
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
feat: 卡网关按运营商账户限流并记录停复机调用
- 新增网关限流:按本系统运营商账户(卡 carrier_id)→ 限流组 → 操作限制每秒请求数,每次 HTTP 尝试计量,默认限流、仅后台人工点击/通道阈值/自动续费/手动刷新豁免;支持只统计与拦截两种模式,默认只统计
- Asynq 遇限流不计失败、固定短延迟重试;轮询任务与停复机业务重试遇限流短延迟重排
- 停机、复机不再使用网关内部重试,只发一次请求
- 网关返回结构化错误;新增上游错误分类规则表与测试接口
- 新增按月分区的停复机记录表:系统自动停复机只写记录,不再写统一审计与集成日志;普通轮询查询不再写集成日志
- 新增限流组、错误分类、停复机记录、按账户调用统计与枚举后台接口
- 迁移 000243~000246;同步 OpenSpec 提案(含后续 6 个 change)与技术方案、工程约束
2026-10-24 15:06:41 +09:00

5.2 KiB
Raw Blame History

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 峰值与本应被限流次数,作为配置限流组的依据