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

9.3 KiB
Raw Blame History

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 天的用量并入之后第一个有快照的那天,不丢失