feat: 卡网关按运营商账户限流并记录停复机调用
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m33s
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:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-10-24
|
||||
73
openspec/changes/add-carrier-gateway-rate-limit/design.md
Normal file
73
openspec/changes/add-carrier-gateway-rate-limit/design.md
Normal file
@@ -0,0 +1,73 @@
|
||||
## Context
|
||||
|
||||
完整推导、生产数据与评审记录见 `docs/engineering/轮询按运营商账户限流技术方案.md`(第三部分第 4、6.2、7.1、7.4 节,第五部分第 3 节第 1 步)。本文只记录本 Change 的实现决策。
|
||||
|
||||
现状:
|
||||
|
||||
- `internal/gateway/client.go:141` `executeWithRetry`:一次方法调用最多 `maxRetries + 1` 次 HTTP 请求(默认 2 次重试),仅对超时、连接失败重试;每次尝试前后调用 `AttemptObserver`(`stop_resume_audit.go`、`gateway_integration.go` 已用于审计与集成日志)。
|
||||
- `internal/gateway/flow_card.go`:`StopCard` / `StartCard` 用默认重试;`SetCardSpeedTier` 已设 `maxRetries = 0`。
|
||||
- 业务错误只拼在错误字符串(`client.go:274`),集成日志 `provider_code`、`provider_message` 为空。
|
||||
- 轮询并发:`internal/task/polling_base.go` 的全局 + 任务类型计数(本 Change 不动,第 5 个 Change 下线)。
|
||||
- Asynq:`pkg/queue/server.go` 显式使用 `asynq.DefaultRetryDelayFunc`,未设 `IsFailure`;`outbox:deliver` 入队未设 `MaxRetry`(默认 25 次)。`queue.concurrency` 默认 10,轮询与 Outbox、导出、佣金共用。
|
||||
- Redis 单节点;自动化测试为 N/A,验证在维护者指定的测试环境进行。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
|
||||
- 所有自动触发的卡网关调用受运营商账户限流约束,口径为每次实际 HTTP 请求。
|
||||
- 上线不造成整体变慢:先只统计,配好后整体拦截。
|
||||
- 限流不导致"流量用完停机"被推迟数小时或丢失。
|
||||
- 失败原因与调用量可见,停复机逐次可查。
|
||||
|
||||
**Non-Goals:**
|
||||
|
||||
- 不改轮询调度、分片、并发计数(第 5 个 Change)。
|
||||
- 不改停复机业务规则与触发路径(第 4、6 个 Change);现有 `stopCardWithRetry` 的业务层 sleep 重试保留到第 6 个 Change。
|
||||
- 不做批量查询;不对后台人工点击、通道阈值、自动续费、手动刷新限流。
|
||||
|
||||
## Decisions
|
||||
|
||||
1. **限流在每次 HTTP 尝试前执行**,而不是方法入口。方法入口只能扣一次,内部重试会漏计。实现为网关客户端的调用守卫 `gateway.CallGuard`(`BeforeAttempt` / `AfterAttempt`),在 `executeWithRetry` 每次尝试前、现有 `AttemptObserver` 之前调用;卡操作类型由 5 个卡方法写入 ctx。没有复用 ctx 里的 `AttemptObserver`,因为 ctx 只能放一个观察器,会与停复机、设备的审计观察器互相覆盖。限流拒绝发生在审计观察器之前,因此被拒绝的尝试不写集成日志。
|
||||
2. **滑动窗口 Lua(ZSET 毫秒时间戳)**,key `gateway:qps:{cid}:{group}`;一次脚本同时校验账户组与全局组、普通操作与预留额度、`high_waiting`。备选令牌桶:突发更平滑但"本秒剩余"口径与后续分发器领取不一致,放弃。
|
||||
3. **默认限流、显式豁免**:ctx 中只有豁免标记(带来源),没有"受限流"标记。备选"带标记才限流":新入口忘记打标记就漏网,与"不存在不限流的自动调用"冲突,放弃。
|
||||
4. **两种模式全局开关**:`polling.rate_limit_mode` 放受控系统配置(`tb_system_config`,`module = polling`),不按账户覆盖(不灰度,见方案第三部分第 9 节)。API 与 Worker 各自用独立注册表读取同一份配置数据,进程内缓存 5 秒,后台修改数秒内生效。
|
||||
- 限流组与错误分类规则同样在进程内缓存 5 秒(`GatewayRateLimitConfigTTL`),后台保存后本进程立即失效、其他进程 5 秒内刷新;未另建 Redis 配置缓存。
|
||||
- 运营商账户口径为本系统 `tb_carrier`(卡上的 `carrier_id`),与网关客户端自身的 appId 无关:已知卡的调用方用 `gateway.WithCarrier` 传入,否则守卫按 ICCID 查本系统卡表并缓存 10 分钟;查不到时按账户 0(未知账户)单独计量。
|
||||
- Redis 故障时限流失败开放(放行并记日志),避免限流组件故障阻断全部网关调用。
|
||||
5. **Asynq 内不等待**:限流器提供"立即返回"与"等待至超时"两种模式,本 Change 只用立即返回。等待会占住共用的 10 个协程、饿死 Outbox 等业务。等待模式留给第 5 个 Change 的 NSQ 消费者。
|
||||
6. **限流错误不计失败**:在 `pkg/queue/server.go` 设置 `IsFailure`(`errors.Is(err, ErrRateLimited)` 时返回 false)与 `RetryDelayFunc`(限流错误返回 `rate_limited_retry_delay`,其余回落 `DefaultRetryDelayFunc`)。只改服务配置与错误类型,各消费者业务代码不改。轮询 handler 另外自行短延迟 Requeue(它们是 `MaxRetry(0)`)。累计推迟告警:任务载荷或 Redis 记首次限流时间,超过上限写告警。
|
||||
7. **停复机 `maxRetries = 0`**:与 `SetCardSpeedTier` 同一做法(复制 Client 并置 0)。超时返回 `CodeGatewayTimeout`,现有调用方按失败或结果未知处理。
|
||||
8. **结构化错误**:新增 `GatewayError{Category, ProviderCode, ProviderMessage, Duration}` 实现 `error` 并保留现有错误码(`CodeGatewayError` 等),调用方用 `errors.As` 取结构,既有 `errors.Is`/错误码判断不受影响。
|
||||
9. **错误分类**:表 `tb_gateway_error_classification` + Redis 缓存;分类器按"适用操作 + 启用 + 优先级"匹配关键字(包含 / 前缀 / 正则)。初始数据按方案第 6.2 节表格写入迁移。
|
||||
10. **停复机记录表**:PostgreSQL 声明式分区(`PARTITION BY RANGE (created_at)`),主键 `(id, created_at)`,建 DEFAULT 分区;Worker 定时任务提前创建未来 N 个月分区(N 为系统参数)并按保留期删除过期分区。记录写入在业务事务之外,失败只记日志与计数。
|
||||
11. **审计替换**:以"是否带限流豁免标记或由账户、个人客户、OpenAPI 发起"区分(`legacyCommandLogging`):
|
||||
- 系统自动停复机(系统任务发起、无豁免标记)只写停复机记录,不写 `tb_audit_event` 与集成日志;未调用上游的拒绝类审计保留。
|
||||
- 后台人工点击、通道阈值、自动续费,以及账户、个人客户、OpenAPI 发起的停复机保持原审计与集成日志并额外写记录。通道阈值与自动续费的可靠任务用集成日志标识做结果未知恢复,不能去掉。
|
||||
- 设备停复机(后台点击)在设备服务内同样写记录。
|
||||
- 普通轮询查询不再写集成日志(含有变化时的成功记录);同时是优先执行的轮次仍写,以满足优先轮询"返回集成交互日志标识"的现行要求。
|
||||
12. **分钟计数**:key `gateway:stat:{cid}:{op}:{yyyyMMddHHmm}` Hash(按结果类别计数、耗时分桶),TTL 8 天,覆盖 `observe` 一周的评估需要。
|
||||
|
||||
13. **观测序列遇限流**:观测序列任务为 `MaxRetry(0)`,现有逻辑在限流时记一次"被限流"并结束本次尝试(不归档、不报错),后续两次尝试与普通轮询兜底;本 Change 不做顺延重入队(需改序列幂等认领),观测序列在第 5 个 Change 下线。
|
||||
14. **业务层停复机重试**:`stopCardWithRetry` / `resumeCardWithRetry` 遇限流立即返回,不再 sleep 重试、不写失败审计,由调用方既有重试或兜底路径处理。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- [默认 QPS 设得不合理] → 先 `observe` 至少一周,按 `/polling-stats/carriers` 数据为全部账户配置限流组后再整体 `enforce`;`enforce` 后异常可即时改回 `observe`。
|
||||
- [停复机不再内部重试,人工点击网络抖动直接失败] → 已接受;页面提示重试。
|
||||
- [移除系统自动停复机审计后,原审计查询看不到] → 停复机记录提供同等字段与查询;后台人工点击仍有统一审计。
|
||||
- [`IsFailure` 对全部 Asynq 任务生效] → 只对 `ErrRateLimited` 返回 false,其余错误行为不变;限流错误只由限流器产生。
|
||||
- [分区表维护任务失败] → DEFAULT 分区兜底插入不失败;监控分区创建结果。
|
||||
- [Redis 计数 key 量] → 账户 37 × 操作 5 × 分钟,8 天约 210 万个小 Hash;上线前按生产 Redis 余量评估,必要时改为 5 分钟粒度。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. 测试环境:执行迁移(三张新表、`tb_system_config` 配置项与错误分类初始数据),部署 API 与 Worker,默认 `observe`。
|
||||
2. 按 tasks 第 9 节核对清单逐项验证,包括 `enforce` 下 Outbox 限流不计失败。
|
||||
3. 生产:维护者按生产运行说明手工执行迁移与发布,保持 `observe` 至少一周。
|
||||
4. 运营按统计为全部账户配置限流组,确认后改 `enforce`。
|
||||
5. 回退:改回 `observe` 即停止拦截;代码回退时新表保留不删。
|
||||
|
||||
## Open Questions
|
||||
|
||||
- 默认 QPS 初值:在测试环境与 `observe` 数据确认前,暂定为系统参数默认值,由维护者上线前填写。
|
||||
37
openspec/changes/add-carrier-gateway-rate-limit/proposal.md
Normal file
37
openspec/changes/add-carrier-gateway-rate-limit/proposal.md
Normal file
@@ -0,0 +1,37 @@
|
||||
## Why
|
||||
|
||||
上游按运营商账户限频,本系统却只有"全局 + 任务类型"的并发计数,数值没有依据,且自动停复机、业务事件观测完全不受约束。生产 2026-10-22:退款触发的停机 24 小时失败约 26.8 万次、单卡每 1~2 秒调用一次;轮询失败约 37 万次但失败原因全部为空,无法区分限频、卡错误与超时。本 Change 是《轮询按运营商账户限流技术方案》(`docs/engineering/轮询按运营商账户限流技术方案.md`)第五部分第 3 节的第 1 步:不动现有调度,先给网关调用加上按运营商账户的限流,并让失败原因与调用量可见,作为后续各 Change 和各账户 QPS 配置的依据。
|
||||
|
||||
## What Changes
|
||||
|
||||
- 新增网关限流器:按"运营商账户 → 限流组 → 操作"对卡的 5 个网关操作(查流量、查状态、查实名、停机、复机)做每秒请求数限制,滑动窗口,跨 Worker 共享;**按每次实际 HTTP 尝试计量**(挂在 `AttemptObserver.BeforeAttempt`),网关内部重试同样计入。
|
||||
- 默认限流、显式豁免:只有后台人工点击停复机、通道阈值、自动续费、手动刷新 4 个入口打豁免标记,其余卡操作一律受限。
|
||||
- 限流组配置(新表 `tb_carrier_rate_limit_group`):组内操作、`max_qps`、高优先级操作与预留额度、可选全局组;未覆盖或组已停用的操作按默认 QPS,不存在不限流的自动调用。
|
||||
- 两种模式:受控系统配置 `polling.rate_limit_mode`,`observe`(只统计、不拦截,默认)与 `enforce`(拦截),全局生效、不按账户覆盖。上线先 `observe` 采集至少一周,配好全部账户限流组后整体切到 `enforce`。
|
||||
- 拦截时在 Asynq 任务内**不等待**:拿不到名额立即返回"限流"错误;轮询任务短延迟重入队且不计失败;Asynq 服务配置 `IsFailure` 对"限流"错误返回 false、`RetryDelayFunc` 返回固定短延迟,Outbox 消费者与观测序列因此不会因限流消耗重试次数、推迟数小时或归档。
|
||||
- **BREAKING** `StopCard` / `StartCard` 不再使用网关内部重试(`maxRetries = 0`),对全部停复机入口生效(含后台人工点击):避免超时后几百毫秒内对同一张卡连发 2~3 次撞上游单卡频率限制。
|
||||
- 网关返回结构化错误(错误类别、网关业务码与信息、耗时),不再只拼在错误字符串里。
|
||||
- 上游错误分类:新表 `tb_gateway_error_classification`(关键字 → 类别:频率限制 / 终态不可操作 / 已是目标状态 / 临时故障 / 业务错误 / 账户配置错误),后台可增补,提供测试接口。只有明确返回已是目标状态才视为成功。
|
||||
- 停复机记录:新表 `tb_card_stop_resume_record`(按月分区 + DEFAULT 分区,提前建未来分区),每次实际调用上游停机或复机写一条;**BREAKING** 系统自动停复机不再写统一审计 `tb_audit_event` 与集成日志 `tb_integration_log`(后台人工点击仍写统一审计);轮询查询不再写集成日志。
|
||||
- 查询类调用不逐条落库:Redis 按"运营商账户 × 操作 × 结果类别"做分钟级计数与耗时分布。
|
||||
- 后台接口:限流组增删改查、错误分类增删改查与测试、停复机记录查询、按账户调用量统计、`polling` 模块系统配置注册(含 JSON 结构校验)、枚举选项。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `carrier-gateway-rate-limit`:按运营商账户的网关限流、计量口径、豁免、只统计与拦截模式、限流组配置、Asynq 任务遇限流的重试语义、停复机不做网关内部重试。
|
||||
- `gateway-call-observability`:网关结构化错误、上游错误分类、停复机记录表、查询调用分钟计数、按账户调用量与失败查询接口。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
- `polling-load-control`:"业务变化与轮询异常仍可追溯"改为:系统自动停复机写停复机记录表而非统一审计与集成日志;查询失败以分钟计数与卡上最近错误保留可调查信息,不逐条写集成日志。
|
||||
|
||||
## Impact
|
||||
|
||||
- 依赖:无前置 Change;不改现有轮询调度、并发计数与停复机业务规则。
|
||||
- 数据库:新增 `tb_carrier_rate_limit_group`、`tb_gateway_error_classification`、`tb_card_stop_resume_record`(分区表);`tb_system_config` 插入 `module = polling` 配置项。均为新的成对迁移。
|
||||
- 代码:`internal/gateway/client.go`、`internal/gateway/flow_card.go`;新增限流器与错误分类器;`pkg/queue/server.go`(`IsFailure`、`RetryDelayFunc`);`internal/task/polling_*_handler.go`(限流重入队);`internal/service/iot_card/stop_resume_service.go` 与 `stop_resume_audit.go`(记录表替代审计);`internal/infrastructure/systemconfig` 注册;新增 Handler / 路由 / DTO 并同步 `cmd/api/docs.go`、`cmd/gendocs/main.go`。
|
||||
- 接口:新增 `/polling-rate-limit-groups`、`/gateway-error-classifications`、`/card-stop-resume-records`、`/iot-cards/:id/stop-resume-records`、`/polling-stats/carriers`、`/polling-options`;`/system-configs` 的 `module` 枚举增加 `polling`。前端需新增限流组、错误分类、停复机记录页面,系统配置页增加 `polling` 模块。
|
||||
- 行为:后台人工点击停复机遇网络超时不再自动重试,页面直接显示失败;系统自动停复机的审计查询改到停复机记录。
|
||||
- 运营:`observe` 期间按调用量统计为全部运营商账户配置限流组,确认后切 `enforce`。
|
||||
@@ -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** 系统拒绝并保留原配置
|
||||
@@ -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 峰值与本应被限流次数,作为配置限流组的依据
|
||||
@@ -0,0 +1,17 @@
|
||||
## MODIFIED Requirements
|
||||
|
||||
### Requirement: 业务变化与轮询异常仍可追溯
|
||||
系统 SHALL 在轮询产生网络、实名、套餐或有效流量等业务事实变化时持久化必要的业务事实与审计记录。外部调用失败、响应无效或结果未知时,系统 MUST 保留可调查的失败或恢复信息,且不得把失败静默降级为正常无变化观测。系统自动停复机的每次上游调用 MUST 以停复机记录保留结果与失败原因,不再写统一审计与集成日志;查询类调用失败 MUST 以按运营商账户的分钟计数与卡上各检查类型最近一次错误保留可调查信息,普通轮询不逐条写集成日志;同时是优先执行的轮次仍写集成日志供优先项追溯。
|
||||
|
||||
#### Scenario: 轮询产生网络状态变化
|
||||
- **GIVEN** 渠道返回的网络状态与当前业务事实不同
|
||||
- **WHEN** 系统成功应用该状态变化
|
||||
- **THEN** 系统持久化业务状态变化及相应审计事实
|
||||
|
||||
#### Scenario: 轮询渠道调用失败
|
||||
- **WHEN** 轮询调用渠道超时、失败或返回无效响应
|
||||
- **THEN** 系统更新对应分钟计数与该卡该检查类型的最近错误,并按既有策略安排后续处理
|
||||
|
||||
#### Scenario: 自动停机失败
|
||||
- **WHEN** 系统自动停机时上游返回业务错误
|
||||
- **THEN** 系统写一条带错误类别与上游信息的停复机记录,不写统一审计与集成日志
|
||||
66
openspec/changes/add-carrier-gateway-rate-limit/tasks.md
Normal file
66
openspec/changes/add-carrier-gateway-rate-limit/tasks.md
Normal file
@@ -0,0 +1,66 @@
|
||||
## 1. 迁移与模型
|
||||
|
||||
- [x] 1.1 新增成对迁移:建 `tb_carrier_rate_limit_group`(`carrier_id` 可空表示全局组、`group_code`、`group_name`、`max_qps`、`operations`、`high_priority_operations`、`reserved_qps`、`status`、审计字段);down 删表。
|
||||
- [x] 1.2 新增成对迁移:建 `tb_gateway_error_classification`(关键字、匹配方式、类别、适用操作、优先级、启用状态),写入方案第 6.2 节的初始规则;down 删表。
|
||||
- [x] 1.3 新增成对迁移:建分区表 `tb_card_stop_resume_record`(按 `created_at` 月分区,主键 `(id, created_at)`,DEFAULT 分区,当前月起若干个月分区,索引 `(card_id, created_at)`、`(carrier_id, created_at)`、`(result, created_at)`);down 删表。
|
||||
- [x] 1.4 新增成对迁移:`tb_system_config` 插入 `module = polling` 配置项(`polling.rate_limit_mode` 默认 `observe`、`rate_limited_retry_delay`、限流累计推迟告警上限、默认 QPS、停复机记录保留月数与提前建分区月数);down 删除这些键。
|
||||
- [x] 1.5 新增对应 model 与 Store;`internal/infrastructure/systemconfig` 注册上述键(类型、取值范围、枚举),`SystemConfigListRequest.Module` 枚举增加 `polling`;为 JSON 类型注册项增加结构校验接缝。
|
||||
|
||||
## 2. 网关结构化错误与停复机不重试
|
||||
|
||||
- [x] 2.1 `internal/gateway`:新增 `GatewayError`(类别、业务码、信息、耗时),`executeHTTPRequest` 与业务错误分支返回它并保留现有错误码;上游信息脱敏截断。
|
||||
- [x] 2.2 `flow_card.go`:`StopCard` / `StartCard` 改为 `maxRetries = 0`(同 `SetCardSpeedTier` 写法)。
|
||||
- [x] 2.3 全仓检查对网关错误字符串的解析(如按 `Gateway 业务错误: code=` 匹配),改为读取结构化字段,行为保持一致。
|
||||
|
||||
## 3. 限流器
|
||||
|
||||
- [x] 3.1 新增限流器:滑动窗口 Lua(账户组 + 全局组 + 预留额度 + `high_waiting`),返回放行或需等待毫秒数;提供立即返回与等待至超时两种调用方式。
|
||||
- [x] 3.2 限流组配置读取:数据库 → Redis 缓存,变更后即时刷新;按目标卡 `carrier_id` + 操作查组,未覆盖或停用回落默认 QPS。
|
||||
- [x] 3.3 实现限流 `AttemptObserver`,在 `BeforeAttempt` 取名额;与现有审计观察器链式组合;拿不到名额返回 `ErrRateLimited`(结构化错误类别"限流")。
|
||||
- [x] 3.4 豁免标记:ctx 携带豁免来源;在后台人工点击停复机、通道阈值、自动续费、手动刷新 4 处入口打标记,其余不改。
|
||||
- [x] 3.5 `observe` / `enforce` 模式:`observe` 只计数(含本应被限流次数)不拦截;模式读取受控系统配置并即时生效。
|
||||
|
||||
## 4. Asynq 遇限流的重试语义
|
||||
|
||||
- [x] 4.1 `pkg/queue/server.go`:`IsFailure` 对 `ErrRateLimited` 返回 false;`RetryDelayFunc` 对其返回 `rate_limited_retry_delay`,其余回落 `DefaultRetryDelayFunc`。
|
||||
- [x] 4.2 现有轮询 handler(`internal/task/polling_*_handler.go`)遇 `ErrRateLimited` 按短延迟 Requeue、不计失败、不写失败审计。
|
||||
- [x] 4.3 限流累计推迟告警:记录任务首次被限流时间,超过上限写告警,任务继续重试。
|
||||
|
||||
## 5. 错误分类与调用计数
|
||||
|
||||
- [x] 5.1 错误分类器:按适用操作、启用状态、优先级匹配关键字;规则缓存于 Redis 并在变更后刷新;未命中归业务错误。
|
||||
- [x] 5.2 网关调用分钟计数:每次尝试结束按"账户 × 操作 × 结果类别"计数并记录耗时分桶,含豁免调用量与本应被限流次数。
|
||||
- [x] 5.3 卡上最近错误:查询失败时写该卡该检查类型的最近错误(类别、码、信息、时间)。
|
||||
|
||||
## 6. 停复机记录替代审计
|
||||
|
||||
- [x] 6.1 每次实际调用上游停机或复机后写停复机记录(来源、场景、尝试序号、结果、错误类别、上游信息、耗时);写入失败只记日志与计数。
|
||||
- [x] 6.2 系统自动停复机不再写 `tb_audit_event` 与集成日志;后台人工点击停复机保留统一审计并同时写记录。
|
||||
- [x] 6.3 轮询查询删除集成日志写入(含有变化时的成功记录),业务事实变化的持久化不变。
|
||||
- [x] 6.4 Worker 定时任务:提前创建未来分区、按保留期删除过期分区,失败写告警。
|
||||
|
||||
## 7. 后台接口
|
||||
|
||||
- [x] 7.1 限流组:`GET/POST /polling-rate-limit-groups`、`GET/PUT/DELETE /polling-rate-limit-groups/:id`、`PUT /:id/status`;保存校验(`reserved_qps < max_qps`、高优先级属于本组、同账户同操作只属一组);修改仅超级管理员并写统一审计。
|
||||
- [x] 7.2 错误分类:`GET/POST /gateway-error-classifications`、`PUT/DELETE /:id`、`PUT /:id/status`、`POST /gateway-error-classifications/test`。
|
||||
- [x] 7.3 停复机记录:`GET /card-stop-resume-records`(时间范围必填且有上限)、`GET /iot-cards/:id/stop-resume-records`。
|
||||
- [x] 7.4 调用量统计:`GET /polling-stats/carriers`(实际 QPS、成功率、按类别失败数、p95、本应被限流次数、豁免调用量)与 `GET /polling-stats/carriers/:carrier_id/trend`。
|
||||
- [x] 7.5 枚举:`GET /polling-options`(操作类型、错误类别、匹配方式等)。
|
||||
- [x] 7.6 同步可执行路由、`cmd/api/docs.go`、`cmd/gendocs/main.go`,运行 `go run cmd/gendocs/main.go` 重新生成接口文档。
|
||||
|
||||
## 8. 编译与规范校验
|
||||
|
||||
- [x] 8.1 `gofmt -w` 变更文件;`go build ./cmd/api ./cmd/worker` 通过。
|
||||
- [x] 8.2 `openspec validate add-carrier-gateway-rate-limit` 与 `openspec doctor --json` 通过。
|
||||
|
||||
## 9. 测试环境验证(自动化测试为 N/A,按 ENG-TEST-001 在维护者指定测试环境逐项核对)
|
||||
|
||||
- [x] 9.1 迁移在测试库执行成功;未来分区与 DEFAULT 分区存在。
|
||||
- [ ] 9.2 `observe`:超过限流组上限的请求照常发出,统计接口显示本应被限流次数。
|
||||
- [ ] 9.3 `enforce`:账户组用满时请求被拒;不同账户互不影响;停用组回落默认 QPS;全局组生效;预留额度下停机仍可放行。
|
||||
- [ ] 9.4 内部重试计量:构造查询超时,确认第二次尝试单独取名额。
|
||||
- [ ] 9.5 停复机超时只发一次请求,返回结果未知;后台人工点击不受限流。
|
||||
- [ ] 9.6 Outbox 消费者遇限流:Asynq 重试计数不增加、按短延迟重试;非限流错误按原规则重试;累计推迟超限写告警。
|
||||
- [ ] 9.7 错误分类:测试接口与实际调用的分类一致;"密码错误"归账户配置错误,"已存在"不归已是目标状态。
|
||||
- [ ] 9.8 系统自动停复机只写停复机记录、不写统一审计与集成日志;人工点击两者都写;记录写入失败不影响卡状态回写。
|
||||
- [ ] 9.9 生成的接口文档包含新增接口;`/system-configs?module=polling` 返回新增配置项且 JSON 结构校验生效。
|
||||
Reference in New Issue
Block a user