## 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:` 在启动时展开为该设备当前绑定的全部卡,`iot_card:` 指单卡套餐的卡;名单中的 `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 天的用量并入之后第一个有快照的那天,不丢失