Files
junhong_cmp_fiber/openspec/changes/rebuild-card-traffic-metering-and-stop-resume/proposal.md
邹进 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

5.2 KiB
Raw Blame History

Why

卡流量现在按"本次运营商读数 − 卡上基线(last_gateway_reading_mb)"计算增量。基线是跨套餐、跨用户的卡级状态,一旦被异常高读数抬高或重置日没采到就会一直错下去:卡被冻结(2026-10-12 统计约 23% 活跃卡 10 月基线未动,上限估计)、读数为 0 时整笔重复计、二次销售把上一个用户的用量算给新用户、无套餐期间的增量积压后扣到新套餐上。老卡管用"每卡每天一条本月累计快照、区间取最大值做差"多年稳定,本 Change 照搬它的计量方式。

停复机同时存在两个问题:外部停机后卡管不再复机(只认流量耗尽、无套餐、未实名三种停因),实名与停复机默认强绑定且耦合行业卡和资产实名策略,想放开只能修数据。依据为 docs/卡流量计算技术方案-参考老卡管.md(第 2 版)。

What Changes

卡流量计量(方案第 1~9 章)

  • 新增卡日快照:每卡每天一条"自然月累计",写入时按通道上游流量重置日换算成自然月;重置日当天读数超过上周期最大快照 0.9 倍按 0 记;快照只增不减;读数为 0 或无效不写。全部被采集的卡都写快照。
  • 已切换的卡:增量 = 本月最大快照 − 本月已结算合计(按月对账),照旧写 V1 流量事件交给现有扣减;卡没有生效中套餐时增量只记为已结算、不发事件。
  • 新增切换水位:卡第一次走新算法时,这一次沿用老算法增量,此前部分记为已结算,切换不重复扣、不依赖切换前是否已有快照。
  • 已切换的卡:读数有效且本次未被防旧值处理即判定通道阈值;卡表 current_month_usage_mb 用本月最大快照覆盖;日流量读快照。
  • 按扣减载体名单灰度(off / gray / full),设备整台切;切换、扩批、退回先停全部进程再一起启动,退回时删除水位。未切换的卡扣费、停复机、观测结果、展示与现在一致。
  • 不在本 Change:冻结卡历史少扣的补数据脚本(后期另立 Change)、积压"处理中"回执的处理(业务手动)。

停复机规则与实名管控(方案第 10 章,总开关控制,默认关闭)

  • BREAKING(开关开启后)停机:卡开机且满足任一——没有套餐、流量用完、卡所属通道开启实名管控且卡未实名。
  • BREAKING(开关开启后)复机:卡停机且同时满足——有套餐、流量没用完、卡已实名或通道关闭实名管控;不看停机原因(外部停机、手动停机、设备手动停机都复机)。持有本周期通道阈值锁的卡不复机。
  • 新增通道配置 realname_control_enabled,默认 0(不管控),不复用通道现有实名字段;开启后不再区分行业卡,不看卡或设备实名策略。不迁移、不修改任何卡或设备数据。
  • 卡或所在设备暂停轮询时卡管不自动停复机;运营商异常状态(风险停机、机卡分离停机、已销户)由人工判断并暂停轮询,现有独立卡风险停机/已销户自动暂停轮询逻辑不变。
  • 通道阈值新周期解锁后的复机条件随新规则调整。

Capabilities

New Capabilities

  • card-traffic-metering:卡日快照、自然月换算与重置日防旧值、按月对账增量、切换水位、按名单灰度、已切换卡的通道阈值判定、本月用量与日流量展示。
  • card-stop-resume:自动停复机条件、复机不看停机原因、通道实名管控配置、暂停轮询的卡不自动停复机、新规则总开关。

Modified Capabilities

  • polling-operations:"停复机遵循实际生效实名策略"限定为停复机新规则总开关关闭时适用;开启后实名改由 card-stop-resume 的通道实名管控决定。
  • carrier-channel-traffic-threshold:新周期解锁后的自动复机条件在新规则开启时改为 card-stop-resume 的复机条件。

Impact

  • 数据库:新增 tb_card_flow_day、tb_card_flow_switch;tb_carrier 增加 realname_control_enabled。均为新的成对迁移,不改既有表结构以外的数据。
  • 代码:internal/application/cardobservation/traffic.go(已切换分支)、新增 internal/domain/cardflow/、快照与水位 Store;internal/service/iot_card/stop_resume_service.go、iot_card_store.go、polling_protect_handler.go;internal/model/carrier.go、service/carrier 与 DTO;internal/application/carrierthreshold/ 周期恢复;日流量查询;pkg/config、pkg/constants。
  • 不改:套餐表与套餐服务、V1 消费者、激活/重置/改已用量/换货/退款入口、Gateway 与三个观测入口、外部停机仍记 carrier_stopped 的规则、购买与激活流程的实名策略。
  • 接口:通道创建、修改、详情增加 realname_control_enabled;重新生成接口文档。
  • 配置:JUNHONG_TRAFFIC_CALC_MODE、JUNHONG_TRAFFIC_CALC_CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED、JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED;API 与全部 Worker 必须一致。
  • 运营:灰度第一批为设备 15276;打开停复机总开关前先在管理端设定需要实名管控的通道,并预演会集中复机、停机的卡。