Files
junhong_cmp_fiber/openspec/changes/add-tiered-polling-and-pre-activation-settlement/proposal.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.8 KiB
Raw Blame History

Why

开启轮询的卡全部按配置轮询,配置只能区分网络、实名、卡类别与运营商账户:库存卡、无套餐卡与在用卡同频调网关,"无套餐仍在跑流量""库存卡在上游开机"没有专门兜底。流量计量方面,无套餐期间若不查流量,按月对账会把这段用量(以及二次销售前上一用户本月的用量)算进新激活的套餐;流量查询稀疏时,每张卡在重置日清零前最后一次查询到清零之间的用量永远查不到。另外现有配置合并把间隔为空当"继承",字段说明却写"空表示不检查",分层后会让"无套餐层不查流量"失效。本 Change 是《轮询按运营商账户限流技术方案》第五部分第 3 节第 2 步。

What Changes

  • 轮询配置新增两个匹配维度:套餐状态(有生效套餐 / 套餐已用完 / 只有待生效套餐 / 无套餐)、资产状态(在库 / 已销售 / 已换货 / 已停用),为空表示不限;层级在卡任务收尾、全量初始化与生命周期重新匹配时计算,不在套餐状态修改点挂钩子。
  • 间隔三态:正数按间隔、0 不检查(停止向下继承)、空继承;保持"空 = 继承"不改变现有配置行为;修正字段注释与接口文档的错误说明。
  • 保存校验:匹配"无套餐、已销售"或"在库"的配置,卡状态检查间隔必须为正数。已销售无套餐、在库卡未匹配任何配置时告警。
  • 优先级可后台调整:单条修改与整体排序接口;相同优先级按 ID 稳定排序;提供匹配预览(输入 ICCID,返回命中配置与每种检查最终间隔及来源,可带未保存修改预演);提供"立即重算到期时间"(只提前不推后,异步任务,可按运营商账户限定)。
  • 重置日前加密查流量:配置新增 pre_reset_window、pre_reset_carddata_interval,在运营商账户重置日前窗口内缩短流量检查间隔,最后一次查询贴近清零时刻。
  • 激活前流量结算:资产从"无生效主套餐"变为"有生效主套餐"之前,先查一次流量入账(只记已结算),再激活;结算观测不触发停复机评估;结算失败或超时不阻塞激活并告警;整次结算设总超时;结算受运营商账户限流约束。
  • 流量按观测时间归属:观测时间早于套餐激活时间的用量只记已结算,不扣新套餐(对所有流量观测生效)。
  • 统一资产级激活锁:实名激活与订单购买即生效补上现有 RedisPackageActivationLockKey,结算与激活在锁内执行。
  • 激活后复机沿用现有路径,第 6 个 Change 上线后改为请求评估。
  • 按层统计、漏配告警、重置日前加密效果统计接口。

Capabilities

New Capabilities

  • tiered-polling:轮询配置的套餐状态与资产状态维度、间隔三态与合并规则、优先级调整与稳定排序、匹配预览、重算到期时间、重置日前加密、无套餐与库存层兜底校验、按层统计。

Modified Capabilities

  • card-traffic-metering:新增激活前流量结算与"按观测时间归属"规则(该能力由 rebuild-card-traffic-metering-and-stop-resume 引入,本 Change 要求其先归档)。
  • package-lifecycle:无生效主套餐到有生效主套餐的各激活入口统一资产级激活锁,激活前先做流量结算。

Impact

  • 依赖:rebuild-card-traffic-metering-and-stop-resume 已完成并归档、日快照计量已在生产开启并核对;第 1 个 Change(限流器)已上线,结算查询受限流约束。
  • 数据库:tb_polling_config 新增 4 个可空列(package_state、asset_status、pre_reset_window、pre_reset_carddata_interval);新的成对迁移。
  • 代码:internal/polling/config_manager.go(三态合并、稳定排序、新维度、重置日前到期计算)、internal/service/polling/config_service.go 与 DTO、internal/store/postgres/package_usage_store.go(按资产查询套餐状态,单个与批量)、internal/polling/initializer.go、lifecycle_service.go 与重入队处传入套餐状态;internal/service/package/activation_service.go、internal/service/order/service.go(激活锁与结算);internal/application/cardobservation/traffic_flow.go(观测时间归属、结算标记不触发评估)。
  • 接口:/polling-configs 增加 4 个字段、间隔支持 0;新增 PUT /polling-configs/priorities、GET /polling-configs/match-preview、POST /polling-configs/recalculate-due、GET /polling-configs/recalculate-due/:task_id、GET /polling-stats/tiers、GET /polling-stats/pre-reset。前端轮询配置页改为"按间隔 / 不检查 / 继承"三态并支持拖拽排序。
  • 行为:激活链路多一次流量查询,有总超时;生产现有 7 条轮询配置无 0 值,行为不变。