Files
邹进 96771a204f
Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
feat: 卡流量改为日快照计量并统一停复机规则
卡流量计量(按名单灰度,默认 off):
- 新增卡日快照与切换水位表(000241),按通道上游流量重置日换算自然月、重置日防旧值
- 已切换的卡按月对账产生增量,无生效中套餐只结算不发事件;第一次切换写水位
- 已切换卡读数有效即判定通道阈值,卡表本月用量用快照覆盖,日流量读快照
- 配置 JUNHONG_TRAFFIC_CALC_MODE/CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED

停复机规则(总开关 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED,默认关闭):
- 复机不看停机原因,持通道阈值锁仍拒绝;暂停轮询的卡不自动停复机
- 通道新增实名管控 realname_control_enabled(000242,默认 0),开启后不区分行业卡与实名策略
- 实名管控从 0 改 1 需确认,修改并入通道更新审计

OpenSpec Change: rebuild-card-traffic-metering-and-stop-resume
2026-10-20 17:49:26 +09:00

81 lines
9.9 KiB
Markdown
Raw Permalink 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/卡流量计算技术方案-参考老卡管.md`(第 2 版)。本文只记录实现层的关键决策。
现状:
- `internal/domain/cardobservation/traffic.go` 的 `ApplyTraffic` 用"读数 − `last_gateway_reading_mb`"算增量,读数下降只在重置日当天或前一天被当作清零,其余一律拒绝;`internal/application/cardobservation/traffic.go` 在同一事务里锁卡行、CAS 更新卡表、正增量写 V1 Outbox,读数被接受时才判定通道阈值(第 84 行)。
- V1 消费者(`internal/infrastructure/cardobservation/event.go`)调 `DeductDataUsage`;没有生效中套餐时报"没有可用套餐"并由 Asynq 重试。
- 停复机集中在 `internal/service/iot_card/stop_resume_service.go`:自动复机只认 `traffic_exhausted`、`no_package`、`not_realname`;实名门槛 `isRealnameOK` 放行行业卡、已实名卡和实际生效策略为 `none` 的卡。停复机判断只读套餐用量与状态,不读卡表用量字段。
- 卡表 `current_month_usage_mb` 被资产详情、卡列表、设备导出直接读取。
- 约束:套餐侧、V1 消费者、Gateway 与三个观测入口不改;自动化测试为 N/A,验证在维护者指定的测试环境进行;生产迁移由维护者手工执行。
## Goals / Non-Goals
**Goals:**
- 已切换的卡不再依赖卡表基线计量,冻结、读数为 0 重复计、二次销售多计、无套餐积压不再新增。
- 切换可灰度、可退回,不重不漏;未切换的卡行为不变。
- 停复机按"停机看套餐、流量、通道实名管控;复机看套餐、流量、实名,不看停因"的统一规则执行,由总开关控制上线时机。
**Non-Goals:**
- 冻结卡历史少扣的补数据脚本(后期另立 Change,依赖本 Change 的切换水位)。
- 积压"处理中"回执的处理(业务手动,处理前不得重放)。
- 套餐扣减口径、加油包顺序、虚流量阈值、`DeductDataUsage` 及消费者的任何改动。
- 卡级、设备级实名管控字段;按运营商扩展状态自动暂停轮询。
- Gateway 按日期区间查询(电信读数为 0 的问题本期不解决)。
## Decisions
**D1 计量照搬老卡管日快照,而不是修补基线规则。** 基线是一个可被任意一次异常读数永久污染的单值状态;日快照取最大值做差,单次异常只影响当月,且可按快照复算。替代方案"放宽读数下降判定"仍依赖基线,无法根治二次销售与冻结。
**D2 增量按月对账(本月最大快照 − 本月已结算合计),不按天对账。** 按天对账遇到跨零点的迟到观测会重复扣;按月对账与观测先后无关,且已结算合计同时承载"发出的增量"、"无套餐丢弃的增量"和"切换时视为老算法已结算的部分"。
**D3 新逻辑放在 `ApplyTrafficObservation` 的已切换分支内,同一事务。** 卡行已在事务开头加锁,同卡观测天然串行,快照不另加行锁;快照、已结算、切换水位、Outbox 同事务提交。老 `ApplyTraffic` 照常计算并写卡表三列(`last_gateway_reading_mb` 仍是 CAS 条件,新代码只读),只是已切换卡不使用它的增量(第一次切换观测除外)。未切换卡在事务提交后用 `INSERT ... ON CONFLICT DO UPDATE SET month_used_mb = GREATEST(...)` 原子写快照,失败只告警。
**D4 切换水位表,而不是要求阶段 1 覆盖整月。** 平均每卡约 1.5 天才采一次,阶段 1 无法保证每张卡本月都有快照;水位让第一次切换观测沿用老增量并把此前部分记为已结算,同时为补数据提供截断点与冻结卡判定依据(切换后卡表本月计入仍由老逻辑维护,不能用来判定冻结卡)。退回时删除水位,再切回会重新执行。
**D5 无生效中套餐时在观测事务内只读判断并丢弃增量。** 与 `resolveActivePackages` 同口径(卡自身或当前绑定设备的 status=1 套餐),不改消费者;判断出错按有套餐处理,保持不丢量。
**D6 重置日在事务内按卡的 `carrier_id` 严格读取。** 入口传入的 `ResetDay` 在查询失败时已被兜底为 1,联通卡被当作 1 号重置会抬高自然月累计且按最大值规则收不回;失败时按卡表 `carrier_type` 兜底(`CUCC` 取 27,其余取 1)。
**D7 不新增"读数是否有效"标记。** Gateway 的 `FlexFloat` 已把空、null、无法解析转为 0,新逻辑对 0 与负数一律不写快照,结果相同,Gateway 与三个入口不改。
**D8 灰度单位为扣减载体,启动时展开为内存集合。** 设备整台切,避免同一设备套餐同时收到两种算法的增量;判定不查库,出错走老算法。切换、扩批、退回都要先停掉 API 与全部 Worker 再一起启动,避免新旧进程并存时老进程发的增量不计入已结算合计。
**D9 已切换卡的展示与通道阈值。** 卡表 `current_month_usage_mb` 用本月最大快照覆盖(写在同一条 `Updates` 里),三处读取方不改;通道阈值判定条件改为"读数大于 0 且本次未被防旧值处理",`EvaluateInTx` 只做达量写锁、无低读数复机,放开不会误复机。
**D10 停复机统一目标状态判断。** 新增一个判断函数供 `EvaluateAndAct` 开机分支、停机分支、`resumeSingleCard`、`resumeDeviceCards`、`ResumeCardIfStopped` 共用:先判断暂停轮询(卡或设备 `enable_polling = false`,与 `ShouldEnqueue` 同口径)→ 不动作;开机时命中无套餐、流量用完、通道实名管控且未实名即停;停机时满足有套餐、流量未用完、已实名或通道未管控即复机,删除 `isPollingStopReason` 限制,保留通道阈值持锁拒绝。设备复机改为取设备下全部停机卡。套餐判断沿用 `HasValidByCarrier` 与 `isTrafficExhausted` 现有口径。
**D11 实名管控为通道独立开关,`isRealnameOK` 是唯一实现点。** 总开关开启时:通道 `realname_control_enabled = 0` 返回满足,`= 1` 时以 `real_name_status` 判断,删除行业卡与资产实名策略分支;通道查询失败返回错误、本次不动作。停机、复机、设备复机、人工复机、保护期一致性检查(仅通道管控且未实名时跳过)都经过它。替代方案"复用卡/设备实名策略"会让购买流程与停复机继续耦合,且需要修数据。
**D12 通道阈值新周期恢复复用 D10 的复机条件(总开关开启时)。** 避免同一张卡在通道阈值路径与常规路径上复机条件不一致。
## Risks / Trade-offs
- [停复机总开关打开时集中动作:外部停机、人工停机的卡被集中复机;开启实名管控通道的未实名卡(含行业卡)被集中停机] → 总开关默认关闭;打开前在管理端设定需要管控的通道并预演统计,业务确认后再开。
- [人工停机不再长期有效,下一次评估满足条件即复机] → 需要长期停用的卡由人工暂停轮询;已在规格中明确。
- [外部系统反复停卡,卡管反复复机] → 按原则不设上限;需要卡管停止管理时人工暂停轮询。
- [第一次切换观测沿用老增量,若恰好撞上老算法缺陷(如重置窗口读到 0 后又读到真实值)会扣一次] → 每张卡最多一次,灰度第一批核对。
- [事务 1 判断有生效中套餐、消费者扣减前前一条事件刚好扣完唯一套餐,事件仍会积压] → 概率低;灰度期监控"处理中"回执新增数,确有发生再评估消费者调整。
- [重置日前最后一次采集到清零之间的用量丢失,采得越稀丢得越多;重置日当天未采到的卡不触发防旧值] → 与老卡管一致,轮询吞吐另行处理。
- [月中修改通道重置日导致当月换算跳变] → 修改安排在运营商实际重置日前后并核对受影响卡。
- [`ApplyTraffic` 为全部卡共用路径,改动出错会波及全部卡] → 新逻辑只在已切换分支,老分支不改;测试环境回归非灰度卡观测结果与改动前一致。
- [卡换绑设备后第一次观测把整张卡周期读数算给设备套餐] → 与现状一致,列入已知限制。
## Migration Plan
1. 迁移:新增 `tb_card_flow_day`、`tb_card_flow_switch`,`tb_carrier` 增加 `realname_control_enabled smallint not null default 0`;成对 up/down,生产由维护者执行。
2. 发版:计量模式 `off`、快照开关开、停复机总开关关;全部卡开始写快照,其余行为不变。
3. 阶段 1 至少跑满一个完整自然日(最好跨过一次各运营商重置日)后进入灰度:名单 `device:15276`,先停后启全部进程。
4. 扩批条件:灰度卡逐日增量 = 按快照复算;无误停误复;跨过一次各运营商清零;冻结卡恢复计量、二次销售不带入旧用量。之后扩批、全量;全量后下线 Redis 日流量缓冲与 02:00 落盘。
5. 停复机:管理端设定需要实名管控的通道 → 预演 → 打开总开关并先停后启全部进程。
6. 回滚:计量模式改回 `off` 或移出名单并删除对应卡的切换水位,先停后启;停复机总开关改回关闭。快照与水位表保留不影响老路径。
## Open Questions
- "有套餐"的口径:本 Change 沿用现有口径(生效中或待生效都算有套餐);若业务要求只认生效中,需另行确认,会改变现有停机行为。
- 套餐在扣减前刚好用完导致的积压,是否在灰度后调整消费者,待灰度监控结果再定。
- 自动续费成功后的可靠复机(`asset-auto-renewal`「成功后的可靠复机」,实现为 `autoRenewalCardReady`)仍按"可轮询停因、非风险停机/销户"判断,本 Change 未改:总开关开启后,这条路径跳过的卡会在下一次套餐轮询评估时按新规则复机。是否让该路径也改用新复机条件,需另立 Change 修改 `asset-auto-renewal` 规格。