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

36 lines
4.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## 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` 值,行为不变。