Files
junhong_cmp_fiber/openspec/changes/add-tiered-polling-and-pre-activation-settlement/design.md
邹进 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

4.9 KiB
Raw Blame History

Context

完整推导见 docs/engineering/轮询按运营商账户限流技术方案.md 第三部分第 11 节。

现状:

  • internal/polling/config_manager.go:MatchConfigs 按 priority 升序遍历启用配置;MergedTaskIntervals(第 176 行)对每种类型取最高优先级的非 NULL 间隔,即 NULL = 继承。字段注释(internal/model/polling.go:17-21)与 DTO 说明(polling_config_dto.go:10-14)写的是"NULL 表示不检查",与实际相反;DTO 校验 min=30/60,不允许 0。配置变更经 Redis 通知即时刷新,另每 5 分钟定时刷新。
  • 生产 2026-10-24:tb_polling_config 7 条,无 0 值,3 条优先级同为 1,数据库无优先级唯一约束。
  • 卡的下次到期时间在执行收尾时按当时配置算好写入分片 ZSET,配置修改不会改变已排程时间。
  • 流量(internal/application/cardobservation/traffic_flow.go,8-11 已切换分支):增量 = 本月最大快照 − 本月已结算;入账时按 hasActivePackageForCard 判断有无套餐,无套餐只记已结算。
  • 激活入口:排队、指定、队首激活用 Redis 锁 RedisPackageActivationLockKey(30 秒);订单购买用卡或设备行锁 FOR UPDATE(order/service.go:2300);实名激活 ActivateByRealname 无锁。
  • 自动化测试为 N/A。

Goals / Non-Goals

Goals:

  • 按套餐状态与资产状态分层,直接减少网关调用量;无套餐与库存层兜底开机即停。
  • 间隔含义无歧义;调整配置后可预览、可立即生效。
  • 无套餐期间与上一用户用量不计入新套餐;减少重置日前尾部用量丢失。

Non-Goals:

  • 到期即停(依赖第 6 个 Change 的停复机指令队列与场景合并);本 Change 期间沿用现有套餐轮询发现过期后停机。
  • 激活后复机改为请求评估(第 6 个 Change)。
  • 调度结构改造(第 5 个 Change);本 Change 在现有分片调度上实现,第 5 个 Change 沿用同一套间隔计算函数。

Decisions

  1. 保留 NULL = 继承,新增 0 = 不检查。备选"把 NULL 改成不检查":会改变生产现有配置的行为,放弃。合并函数改为:遇到非 NULL 即采用(0 表示该类型不入队)。
  2. 稳定排序:查询 ORDER BY priority, id;不加唯一约束(生产已有重复),只在保存时提示。
  3. 套餐状态按使用时计算:套餐状态修改点约 15 个文件 45 处,不逐处挂钩子;在收尾、初始化、生命周期重新匹配时查询(新增按资产查询套餐状态的单个与批量方法),初始化按批查询避免 N+1。
  4. 重算到期时间:异步任务按运营商账户分批读卡,读取各类型上次检查时间,按 min 规则只提前;写分片 ZSET 用 ZADD LT,天然只提前。
  5. 重置日前加密:在统一的"计算下次到期"函数中处理窗口截断与收尾提前量,初始化、收尾、生命周期共用;重置时刻取 tb_carrier.data_reset_day,与流量计量重置日口径一致。
  6. 观测时间归属:观测携带 observed_at(网关返回时刻);入账判断"有无可扣套餐"时改为"是否存在 activated_at ≤ observed_at 的生效主套餐"。这是正确性的根本保证,锁只减少并发与重复结算。
  7. 结算不触发评估:观测元数据带"激活前结算"标记,traffic_flow 入账后不写触发停复机评估的 Outbox 事件(或消费者识别标记跳过);避免先停机、复机又被单卡最小重试间隔挡住。
  8. 统一激活锁:沿用 RedisPackageActivationLockKey(carrierType, carrierID),实名激活与订单购买即生效补上;锁内顺序为"结算 → 激活事务",TTL 提为大于结算总超时 + 事务耗时。订单路径的行锁保留在事务内。
  9. 结算的限流与超时:结算是自动触发的查询,受第 1 个 Change 的限流约束,使用"等待至超时"模式(处于同步回调链路,单步超时与总超时均为系统参数)。

Risks / Trade-offs

  • [支付、实名回调链路变长] → 总超时兜底,超时照常激活并告警。
  • [锁 TTL 变长导致激活冲突返回增多] → 各入口沿用现有冲突处理;监控抢锁失败次数。
  • [运营把某层间隔设为 0 后漏查] → 无套餐与库存层强制卡状态正数;匹配预览可在保存前确认。
  • [重置日窗口内查询集中] → 仍受账户 QPS 约束;按监控调整窗口与间隔。
  • [依赖 8-11 未上线生产] → 本 Change 实施前确认 rebuild-card-traffic-metering-and-stop-resume 已归档、日快照计量生产开启。

Migration Plan

  1. 迁移:tb_polling_config 加 4 个可空列;现有数据不变。
  2. 测试环境部署并按 tasks 第 8 节核对;运营按新维度新增分层配置(先用预览确认),再执行重算到期时间。
  3. 生产由维护者手工迁移与发布。回退:删除新增分层配置即恢复原匹配;代码回退时新列保留。