## 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.gateway.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` 数据确认前,暂定为系统参数默认值,由维护者上线前填写。