Some checks failed
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Has been cancelled
卡流量计量(按名单灰度,默认 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
46 lines
5.2 KiB
Markdown
46 lines
5.2 KiB
Markdown
## 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;打开停复机总开关前先在管理端设定需要实名管控的通道,并预演会集中复机、停机的卡。
|