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

46 lines
5.2 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
卡流量现在按"本次运营商读数 − 卡上基线(`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;打开停复机总开关前先在管理端设定需要实名管控的通道,并预演会集中复机、停机的卡。