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

53 lines
4.9 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.
## 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. 生产由维护者手工迁移与发布。回退:删除新增分层配置即恢复原匹配;代码回退时新列保留。