卡流量计量(按名单灰度,默认 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
9.3 KiB
ADDED Requirements
Requirement: 卡日快照记录
系统 SHALL 为每张被采集的卡按上海日期每天保存一条"本月自然月累计流量"快照,同时记录当天最后一次有效的运营商原始读数、当天已结算增量合计、当天是否触发重置日防旧值和有效观测次数。运营商读数查询失败、为空、为 null、无法解析、小于 0 或等于 0 时 MUST NOT 写入快照、MUST NOT 产生增量。同一卡同一天多次观测时,本月累计 MUST 取已有值与本次换算值中的较大者,不得变小。快照写入 MUST 为原子写入,轮询、人工刷新与系列观测并发写同一卡同一天时不得丢失较大值。快照永久保留。
Scenario: 同一天读到偏小的旧缓存
- WHEN 某卡当天已有本月累计 500 MB 的快照,本次换算值为 480 MB
- THEN 当天快照的本月累计保持 500 MB,不产生负增量
Scenario: 读数为 0 或无效
- WHEN 运营商返回的已用流量为空、null、无法解析或为 0
- THEN 系统不写快照、不产生增量
Scenario: 未切换卡快照写入失败
- WHEN 未切换新算法的卡在观测事务提交后写快照失败或超时
- THEN 系统只记录告警,本次观测结果、扣费与停复机不受影响,观测不重新入队
Scenario: 关闭快照写入总开关
- WHEN 维护者把
JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED设为关闭并重启 - THEN 未切换的卡停止写快照,其观测、扣费与停复机不受影响
Requirement: 快照按通道重置日换算自然月
系统 SHALL 按卡所属通道的上游流量重置日 R(1~28,上海时区 R 号 0 点清零)把运营商周期读数 r 换算为自然月累计 m:R = 1 时 m = r;R > 1 且今天日号 ≥ R 时 m = r + 本月 1~R−1 号最大快照;R > 1 且今天日号 < R 时 m = r − (上月最大快照 − 上月 1~R−1 号最大快照),结果小于 0 按 0。重置日 MUST 在观测事务内按卡的通道严格读取,不得使用调用方预先计算的值;读取失败、为空或不在 1~28 时,运营商类型为联通(CUCC)的卡按 27、其余按 1 处理并记录日志。
Scenario: 联通卡跨重置日连续
- WHEN 重置日为 27 的卡 26 号最大快照为 5000 MB,27 号清零后读到 100 MB
- THEN 27 号快照的本月累计为 5100 MB,自然月累计连续
Scenario: 重置日查询失败的联通卡
- WHEN 联通卡观测时通道重置日查询失败,调用方传入的重置日已被兜底为 1
- THEN 系统按 27 号换算并记录日志
Scenario: 非常规重置日
- WHEN 通道重置日为 15
- THEN 系统以 15 号为界按同一规则换算,自然月累计连续
Requirement: 重置日防旧值
系统 SHALL 只在重置日当天判断旧值:R = 1 时读数超过上月最大快照的 0.9 倍(上月无快照时比较值为 0),或 R > 1 时本月 1~R−1 号最大快照大于 0 且读数超过其 0.9 倍,本次读数 MUST 按 0 参与换算,原始读数照常记录,并标记当天触发过防旧值。重置日次日起不再判断,读数照常写入。
Scenario: 重置日读到上周期旧值
- WHEN 重置日为 1 的卡在 1 号读到超过上月最大快照 0.9 倍的读数
- THEN 当天本月累计按 0 记、标记触发防旧值;次日读到的读数照常写入
Scenario: 重置日当天真实用量较大
- WHEN 重置日当天真实用量超过上周期最大快照的 0.9 倍
- THEN 当天按 0 记,次日如实写入,这部分用量随次日快照计入,不丢失
Requirement: 已切换卡按月对账产生增量
对已切换新算法且已有切换水位的卡,系统 SHALL 在观测事务内写入当天快照后计算增量 Δ = 本月最大快照 − 本月各天已结算合计。Δ > 0 且卡自身或卡当前绑定设备存在生效中(status=1)套餐时,系统写一条载荷与现有格式相同的 V1 流量增量事件并把 Δ 计入当天已结算;Δ > 0 但没有生效中套餐时 MUST NOT 写事件,只把 Δ 计入当天已结算;Δ ≤ 0 时不写事件。快照、已结算合计与事件 MUST 同事务提交或回滚。已切换的卡每次观测最多写一条 V1 事件,MUST NOT 再写按卡表基线计算的增量事件。生效中套餐查询出错时按有套餐处理。跨月时新月份已结算合计从 0 开始。
Scenario: 冻结卡切换后恢复计量
- WHEN 卡表基线 72535 MB 而运营商读数 48808 MB 的卡切换后读数继续上涨
- THEN 系统按快照计算出正增量并写 V1 事件,套餐已用量恢复增长
Scenario: 二次销售不带入上一个用户的用量
- WHEN 卡在无生效中套餐期间被观测到本月累计 3020 MB,激活新套餐后读到 3050 MB
- THEN 3020 MB 及之前的增量只计入已结算不写事件,新套餐只被扣 30 MB
Scenario: 迟到观测抬高昨天的快照
- WHEN 今天已发出增量后,一次迟到观测把昨天的快照抬高
- THEN 增量仍按本月最大快照减本月已结算合计计算,重叠部分不被扣两次
Scenario: 只有已用完或待生效套餐
- WHEN 卡与绑定设备都没有生效中套餐,只有已用完或待生效套餐
- THEN 增量只计入已结算,不写事件
Requirement: 切换水位
卡已在新算法名单中但没有切换水位时,系统 SHALL 把这次观测作为第一次切换观测:写入当天快照;本次增量沿用按卡表基线计算的结果,大于 0 且有生效中套餐时写 V1 事件,否则不写;把本月最大快照与本月已结算合计的差额计入当天已结算;同事务写入切换水位,记录切换时刻、本月最大快照、运营商读数、卡表基线、卡表本月计入、本次基线算法是否接受读数及其增量。退回老算法时维护者 MUST 删除对应卡的切换水位;再次切换时系统重新执行第一次切换观测。
Scenario: 切换时本月尚无快照
- WHEN 正常计量的卡切换后的第一次观测发生在本月还没有任何快照时
- THEN 系统只写按卡表基线计算的这一笔增量,不把整月累计当作增量写出
Scenario: 冻结卡第一次切换观测
- WHEN 基线算法拒绝读数的冻结卡第一次切换观测
- THEN 系统不写增量事件,切换水位记录读数未被接受及当时的运营商读数;下一次观测起按快照正常写增量
Scenario: 退回后同一天再切回
- WHEN 卡退回老算法并删除切换水位后,同一天再次切换
- THEN 系统重新写切换水位,退回期间老算法已扣的部分不被重复扣
Requirement: 按扣减载体灰度切换
系统 SHALL 支持 off、gray、full 三种计量模式与灰度名单。名单单位为扣减载体:device:<id> 在启动时展开为该设备当前绑定的全部卡,iot_card:<id> 指单卡套餐的卡;名单中的 iot_card 实际使用设备套餐时,系统在启动日志报错并跳过该项,不阻止进程启动。是否走新算法 MUST 用启动时载入的内存集合判断,判断出错一律走老算法。API 与全部 Worker 进程 MUST 使用一致的模式与名单。未切换的卡,卡表、V1 事件、扣减、停复机、观测结果与页面展示 MUST 与本变更前一致。
Scenario: 名单写设备
- WHEN 灰度名单为
device:15276 - THEN 该设备当前绑定的全部卡走新算法
Scenario: 名单中的单卡实际用设备套餐
- WHEN 灰度名单写
iot_card:X,但该卡实际从绑定设备的套餐扣减 - THEN 启动日志报错并跳过该项,进程正常启动,该卡仍走老算法
Scenario: 非灰度卡观测
- WHEN 不在名单中的卡被观测一次
- THEN 卡表、V1 事件、扣减与停复机结果与变更前完全一致
Requirement: 已切换卡的通道阈值判定
对已切换且已有切换水位的卡,系统 SHALL 在本次读数大于 0 且本次读数未被重置日防旧值按 0 处理时,用本次运营商读数做通道阈值判定,MUST NOT 以基线算法是否接受读数作为判定前提。第一次切换观测仍按基线算法的条件判定。未切换的卡保持原判定条件。
Scenario: 冻结卡切换后达量
- WHEN 已切换的冻结卡读数达到通道阈值
- THEN 系统写通道阈值停机锁并创建停机任务
Scenario: 重置日读到旧总量
- WHEN 已切换卡在重置日读到上周期旧总量并触发防旧值
- THEN 本次不做通道阈值判定;同一天之后的真实读数照常判定
Requirement: 已切换卡的本月用量与日流量展示
对已切换的卡,系统 SHALL 在观测事务内用本月最大快照覆盖卡表本月用量,使资产详情、卡列表与设备导出显示快照口径的本月用量;日流量查询 MUST 读取快照,某天用量为当天最大快照减本月此前最大快照,小于 0 按 0,本月第一条快照减数为 0。未切换的卡仍读原来源。
Scenario: 冻结卡切换后展示本月用量
- WHEN 冻结卡切换后被观测
- THEN 资产详情、卡列表与设备导出的本月用量等于本月最大快照,不再为 0
Scenario: 中间几天没采到
- WHEN 已切换卡连续 3 天没有快照
- THEN 这 3 天的用量并入之后第一个有快照的那天,不丢失