## ADDED Requirements ### Requirement: 流量读数有效性 系统 SHALL 在运营商流量查询返回后先判断读数是否有效:接口失败、超时、非 200、限流、响应缺少 ICCID 等必要字段、`used` 为空或 null 或无法解析、读数为负数、NaN 或 Inf 的,均为无效读数,MUST NOT 进入采集队列、MUST NOT 写日快照、MUST NOT 产生增量。读数为有限且大于等于 0 的数时为有效读数。系统 MUST 区分运营商"没有给值"与"读数为 0",响应中完全缺少 `used` 字段时按没有给值处理。 #### Scenario: 运营商返回 null - **WHEN** 运营商流量查询成功,但 `used` 为 null - **THEN** 系统不入队、不写快照、不产生增量;卡有套餐时采集记录的结果为"无读数"、读数为空 #### Scenario: 运营商返回 0 - **WHEN** 运营商流量查询成功,`used` 为 0 - **THEN** 系统把 0 作为有效读数入队 #### Scenario: 响应缺少 used 字段 - **WHEN** 运营商流量查询成功,但响应中没有 `used` 字段 - **THEN** 系统按没有给值处理,不把它当成 0 ### Requirement: 采集队列与写入判断 系统 SHALL 为每张卡维护一个最近 N 个有效读数的采集队列(N 默认 3、最小 2),每个点为采集时间与运营商原始读数。新点 MUST 按采集时间插入队列,同一采集时间的点去重,只保留最后 N 个;队列更新 MUST 原子执行。同时满足以下条件时,系统 SHALL 把新点(即队列最后一个点)作为本次写入点进入日快照与结算:新点插入后位于队尾、队列满 N 个点、相邻两点后一个读数大于等于前一个读数减回退容差(默认 1 MB)。任一条件不满足时本次 MUST NOT 写快照、MUST NOT 产生增量、MUST NOT 做通道阈值判定,并记录不写原因(队列未满、读数下降、乱序)。轮询、人工刷新与激活前结算 MUST 使用同一队列与同一规则。队列丢失时系统 SHALL 从空队列重新开始,不补写。 #### Scenario: 中间点暴涨 - **WHEN** 队列为 100、99999、120 - **THEN** 系统不写入,原因为读数下降 #### Scenario: 持续上涨 - **WHEN** 队列为 100、150、200,200 为新点 - **THEN** 系统写入 200 #### Scenario: 持平 - **WHEN** 有套餐的卡队列为 100、100、100 - **THEN** 系统写入 100,增量为 0 #### Scenario: 回退在容差内 - **WHEN** 回退容差为 1 MB,队列为 100.002、100.001、100.003 - **THEN** 系统写入 100.003 #### Scenario: 运营商清零 - **WHEN** 队列为 3010、20、25 - **THEN** 系统不写入;之后队列为 20、25、30 时写入 30 #### Scenario: 迟到的采集点 - **WHEN** 新点的采集时间早于队列中已有的点,插入后不在队尾 - **THEN** 系统不写入,原因为乱序 #### Scenario: 队列丢失 - **WHEN** 卡的队列因 Redis 重启丢失 - **THEN** 系统从空队列开始,攒满 N 个点后照常写入,不多扣也不少扣 ### Requirement: 人工刷新返回写入结果 系统 SHALL 在人工刷新卡流量后返回本次运营商读数、是否写入以及不写入的原因(读数无效、队列未满、读数下降、乱序)。 #### Scenario: 人工刷新被队列拦下 - **WHEN** 管理员人工刷新卡流量,本次读数使队列未满 - **THEN** 接口返回本次读数、未写入、原因为队列未满 ### Requirement: 跨天清空与过期点 系统 SHALL 提供跨天清空开关(默认开启):开启时新点与队列中的点不在同一上海日期,先清空队列再入队。系统 SHALL 在入队时丢弃与新点采集时间相差超过最长点龄(默认 72 小时,0 表示不限)的点。 #### Scenario: 跨天 - **WHEN** 跨天清空开启,队列中是前一天的点,新点是今天的 - **THEN** 系统清空队列后再放入新点,今天攒满 N 个点后才写入 #### Scenario: 卡停用几天后重新采集 - **WHEN** 跨天清空关闭,队列中最新的点是 4 天前的 - **THEN** 系统丢弃这些点,只用新采集的点判断 ### Requirement: 采集队列配置与采集间隔校验 系统 SHALL 在系统配置中提供队列长度、跨天清空开关、最长点龄、回退容差四项配置,修改后无需重新发布即生效。系统 SHALL 只对启用中的轮询配置校验流量采集间隔:跨天清空开启时间隔 MUST 不超过 24 小时 ÷ (N+2),关闭时 MUST 不超过最长点龄 ÷ (N+2)。保存启用状态的轮询配置、启用轮询配置时间隔超限的 MUST 拒绝;修改队列长度或跨天清空开关会使任一启用中的轮询配置超限时 MUST 拒绝修改。停用的轮询配置 MUST NOT 被校验或阻止保存。 #### Scenario: 启用配置间隔过长 - **WHEN** N = 3、跨天清空开启,维护者保存流量采集间隔为 6 小时的启用中轮询配置 - **THEN** 系统拒绝保存并说明上限为 4.8 小时 #### Scenario: 停用配置不校验 - **WHEN** 维护者保存流量采集间隔为 86400 秒的停用轮询配置 - **THEN** 系统正常保存;启用该配置时按上限校验 #### Scenario: 调大队列长度使启用配置超限 - **WHEN** 启用中的轮询配置间隔为 4 小时,维护者把队列长度从 3 改为 4 - **THEN** 系统拒绝修改,因为上限变为 4 小时以下 ### Requirement: 有套餐判断口径 系统 SHALL 用同一个判断确定"采集时刻卡是否有套餐",供写入范围、是否发扣费事件、是否写采集记录与扣费时查找套餐共用:套餐状态为生效中、已用完或已过期,激活时间不晚于采集时间(激活时间为空的历史数据按已生效),到期时间为空或晚于采集时间,未退款;卡自身一个都没有时看卡当前绑定设备的套餐。待生效、已失效的套餐 MUST NOT 算有套餐。 #### Scenario: 已用完但仍在有效期 - **WHEN** 卡唯一的套餐已用完,到期时间晚于采集时间 - **THEN** 系统判定有套餐,增量照常发扣费事件 #### Scenario: 采集时套餐尚未激活 - **WHEN** 采集时间早于套餐激活时间 - **THEN** 系统判定没有套餐,增量只记已结算 #### Scenario: 沉默期等待中的套餐 - **WHEN** 卡只有处于待生效状态的套餐 - **THEN** 系统判定没有套餐 ### Requirement: 待建起点 系统 SHALL 在卡上维护"待建起点"标记。带标记的卡第一次满足队列写入条件时,系统 MUST 写日快照、把该卡本月最大快照全部记为已结算、不发扣费事件、清除标记,并在采集记录中记为建起点;之后按正常规则处理。以下情况 SHALL 置位:全量切换迁移时全部卡;换卡完成时的新卡;设备换货时新设备当前绑定的每张卡。换卡流程内 MUST NOT 调用运营商接口。 #### Scenario: 换卡后建起点 - **WHEN** 新卡出库前已用 50 MB,换卡完成后依次采到 52、53、55、58 - **THEN** 系统在写入 55 时建起点、不扣费,写入 58 时扣 3 MB #### Scenario: 起点读数异常 - **WHEN** 带标记的新卡第一次采到 99999,之后为 52、53 - **THEN** 队列不满足写入条件,系统不以 99999 建起点 #### Scenario: 全量切换不重复扣 - **WHEN** 全量切换后某卡第一次满足写入条件,本月老路径已扣过 800 MB - **THEN** 系统只建起点、不扣费,之后按增量正常扣 ### Requirement: 采集记录 系统 SHALL 为采集时刻有套餐的卡每次采集写一条采集记录,包括接口失败与读数为 0,记录采集时间、采集 ID、来源、读数结果(有效、失败、限流、响应无效、无读数、读数无效)、运营商原始读数、入队后的队列、写入判断(已写入、建起点、队列未满、读数下降、乱序、激活前结算用已有快照),写入时记录换算后的本月累计、是否触发防旧值、本次增量与流量事件 ID。没套餐的卡 MUST NOT 写采集记录。采集记录 SHALL 按采集时间按月分区,保留 90 天,过期按整月分区删除。系统 SHALL 提供后台按卡与时间范围查询采集记录的接口。采集 ID MUST 随流量事件与扣费审计传递,使扣费可追溯到对应采集记录。 #### Scenario: 被队列拦下的采集 - **WHEN** 有套餐的卡本次读数使队列出现下降 - **THEN** 系统写一条采集记录,判断为读数下降,记录队列内容,不写快照 #### Scenario: 从扣费追到采集 - **WHEN** 维护者从一笔扣费审计排查 - **THEN** 可经流量事件的采集 ID 找到对应采集记录中的原始读数与队列 #### Scenario: 没套餐的卡 - **WHEN** 没套餐的卡被采集 - **THEN** 系统不写采集记录 ### Requirement: 流量采集告警 系统 SHALL 对以下情况产生告警:开启轮询且有套餐的卡一整天没有写入;开启轮询的卡待建起点标记超过 1 天未清除;单卡当天读数下降拦截占比过高或全局拦截率突增;乱序数量突增。系统 SHALL 统计重置日防旧值命中数供核对重置日配置。未开启轮询的卡 MUST NOT 触发上述告警。当天没有写入时系统 MUST NOT 补写日快照。 #### Scenario: 有套餐的卡全天未写入 - **WHEN** 开启轮询、有套餐的卡当天采集记录中没有已写入 - **THEN** 系统产生告警,不补写当天快照 #### Scenario: 不轮询的卡 - **WHEN** 未开启轮询的卡一直带待建起点标记 - **THEN** 系统不告警 ## MODIFIED Requirements ### Requirement: 卡日快照记录 系统 SHALL 为每张卡按上海日期每天保存一条"本月自然月累计流量"快照,同时记录当天最后一次写入的运营商原始读数、当天已结算增量合计、当天是否触发重置日防旧值和写入次数。快照只由通过采集队列判断的写入点写入,无效读数与被队列拦下的读数 MUST NOT 写入快照、MUST NOT 产生增量。写入点读数为 0 时,采集时刻有套餐的卡 MUST 写入快照,没套餐的卡 MUST NOT 写入;读数大于 0 时都写入。同一卡同一天多次写入时,本月累计 MUST 取已有值与本次换算值中的较大者,不得变小。快照写入 MUST 为原子写入,轮询、人工刷新与激活前结算并发写同一卡同一天时不得丢失较大值。快照永久保留。 #### Scenario: 同一天读到偏小的旧缓存 - **WHEN** 某卡当天已有本月累计 500 MB 的快照,本次写入点换算值为 480 MB - **THEN** 当天快照的本月累计保持 500 MB,不产生负增量 #### Scenario: 有套餐的卡读数为 0 - **WHEN** 有套餐的卡写入点读数为 0 - **THEN** 系统写入当天快照,增量为 0 #### Scenario: 没套餐的卡读数为 0 - **WHEN** 没套餐的卡写入点读数为 0 - **THEN** 系统不写快照 #### Scenario: 读数无效 - **WHEN** 运营商返回的已用流量为空、null、无法解析或为负数 - **THEN** 系统不入队、不写快照、不产生增量 ### Requirement: 重置日防旧值 系统 SHALL 只在卡所属通道配置的重置日当天判断旧值,当天全天判断、不按小时区分:`R = 1` 时比较基准为上月最大快照,`R > 1` 时比较基准为本月 1~R−1 号最大快照;读数超过比较基准的 0.9 倍时本次读数 MUST 按 0 参与换算,原始读数照常记录,并标记当天触发过防旧值。比较基准为 0 时,不论配置的重置日是几号,重置日当天任何大于 0 的读数 MUST 按 0 参与换算。重置日次日起不再判断,读数照常写入;重置日当天没有取到有效读数的,次日起照常按新周期计。重置日当天采到的上周期读数 MUST NOT 记回前一天,上周期最后一次写入到运营商清零之间的用量不补。 #### Scenario: 重置日读到上周期旧值 - **WHEN** 重置日为 1 的卡在 1 号读到超过上月最大快照 0.9 倍的读数 - **THEN** 当天本月累计按 0 记、标记触发防旧值;次日读到的读数照常写入 #### Scenario: 重置日当天真实用量较大 - **WHEN** 重置日当天真实用量超过比较基准的 0.9 倍 - **THEN** 当天按 0 记,次日如实写入,这部分用量随次日快照计入,不丢失 #### Scenario: 重置日为 27 且比较基准为 0 - **WHEN** 重置日为 27 的卡本月 1~26 号没有快照,27 号读到 3010 MB - **THEN** 当天按 0 记、标记触发防旧值;28 号读数照常写入 #### Scenario: 重置日早上的旧数 - **WHEN** 重置日 00:10 采到上周期读数 3010 MB 并被写入 - **THEN** 系统按 0 计入当天,不更新前一天的快照 ### Requirement: 已切换卡按月对账产生增量 系统 SHALL 对全部卡在写入点写入当天快照后计算增量 `Δ = 本月最大快照 − 本月各天已结算合计`,卡带待建起点标记时按"待建起点"处理。`Δ > 0` 且采集时刻卡有套餐(按"有套餐判断口径")时,系统写一条流量增量事件(携带采集时间与采集 ID)并把 `Δ` 计入当天已结算;`Δ > 0` 但没有套餐时 MUST NOT 写事件,只把 `Δ` 计入当天已结算,之后购买套餐 MUST NOT 补扣;`Δ ≤ 0` 时不写事件。采集时刻有套餐的卡当天第一次写入时,系统 SHALL 在同一事务内为采集时刻每个有效套餐确保当天一行套餐日用量(没有则写 0)。快照、已结算合计、套餐日用量 0 行与事件 MUST 同事务提交或回滚。每个写入点最多写一条事件,系统 MUST NOT 再按卡表基线计算增量。跨月时新月份已结算合计从 0 开始。 #### Scenario: 二次销售不带入上一个用户的用量 - **WHEN** 卡在没套餐期间被写入本月累计 3020 MB,激活新套餐后写入 3050 MB - **THEN** 3020 MB 及之前的增量只计入已结算不写事件,新套餐只被扣 30 MB #### Scenario: 迟到观测抬高昨天的快照 - **WHEN** 今天已发出增量后,一次迟到写入把昨天的快照抬高 - **THEN** 增量仍按本月最大快照减本月已结算合计计算,重叠部分不被扣两次 #### Scenario: 有套餐但当天没用流量 - **WHEN** 有套餐的卡当天第一次写入,增量为 0 - **THEN** 系统不写事件,为每个有效套餐写当天日用量 0 #### Scenario: 只有待生效套餐 - **WHEN** 卡与绑定设备只有待生效套餐 - **THEN** 增量只计入已结算,不写事件 ### Requirement: 已切换卡的通道阈值判定 系统 SHALL 只在写入点做通道阈值判定:本次写入点读数大于 0 且未被重置日防旧值按 0 处理时,用该读数做通道阈值判定。被队列拦下的读数、无效读数 MUST NOT 参与判定。 #### Scenario: 达量 - **WHEN** 写入点读数达到通道阈值 - **THEN** 系统写通道阈值停机锁并创建停机任务 #### Scenario: 被拦下的暴涨读数 - **WHEN** 队列中间点读数超过通道阈值但被队列拦下 - **THEN** 系统不做通道阈值判定 #### Scenario: 重置日读到旧总量 - **WHEN** 卡在重置日写入上周期旧总量并触发防旧值 - **THEN** 本次不做通道阈值判定;同一天之后的真实读数照常判定 ### Requirement: 已切换卡的本月用量与日流量展示 系统 SHALL 对全部卡在写入点写入后用本月最大快照覆盖卡表本月用量,使资产详情、卡列表与设备导出显示快照口径的本月用量;日流量查询 MUST 读取快照,某天用量为当天最大快照减本月此前最大快照,小于 0 按 0,本月第一条快照减数为 0。卡表 `last_gateway_reading_mb` 不再使用。 #### Scenario: 展示本月用量 - **WHEN** 卡写入点写入本月累计 820 MB - **THEN** 资产详情、卡列表与设备导出的本月用量为 820 MB #### Scenario: 中间几天没写入 - **WHEN** 卡连续 3 天没有快照 - **THEN** 这 3 天的用量并入之后第一个有快照的那天,不丢失 ### Requirement: 流量按观测时间归属 系统 SHALL 为每次流量采集记录网关返回时的采集时间,并以写入点的采集时间按"有套餐判断口径"确定本次增量是否扣减及扣减哪些套餐;采集时间早于套餐激活时间的,该套餐不算有套餐,增量 MUST 只记为已结算、不扣减该套餐。该规则 MUST 对轮询、激活前结算、人工刷新全部生效。 #### Scenario: 慢返回的结算晚于另一入口激活 - **GIVEN** 资产无生效套餐,激活前结算 10:00:00 发出查询,另一入口 10:00:02 激活了套餐 - **WHEN** 结算结果 10:00:05 返回并入账,采集时间早于激活时间 - **THEN** 本次增量只记已结算,不扣新套餐 #### Scenario: 激活后的观测正常扣减 - **WHEN** 写入点采集时间晚于套餐激活时间 - **THEN** 增量按扣减规则扣减套餐 ### Requirement: 激活前流量结算 系统 SHALL 在资产从"无生效主套餐"变为"有生效主套餐"之前(实名激活、排队激活、指定激活、队首激活、订单购买即生效),对独立卡查一次流量、对设备逐张查设备下各卡,读数照常经过采集队列,然后再执行激活。本次读数满足写入条件时按观测入账(此时无套餐,增量只记已结算);不满足写入条件时,系统 MUST 用卡上已有的本月最大快照做结算(把它与本月已结算合计的差额全部记为已结算),不新写快照,采集记录判断记为"激活前结算用已有快照"。已有生效主套餐(续费、排队衔接)与流量重置 MUST NOT 执行结算。结算观测 MUST 携带"激活前结算"标记,入账照常但 MUST NOT 触发停复机评估;激活提交后的评估是激活链路唯一一次评估。结算查询 MUST 受运营商账户限流约束;单卡限流等待超过单步超时、查询失败或整次结算达到总超时时,系统 MUST 跳过剩余结算、照常激活,并按卡写告警。 #### Scenario: 二次销售激活 - **GIVEN** 卡上一用户本月已用 3 GB,当前无生效套餐 - **WHEN** 新用户购买套餐即生效 - **THEN** 系统先查流量并把 3 GB 记为已结算,再激活,新套餐不承担这 3 GB #### Scenario: 结算读数未满足写入条件 - **WHEN** 激活前结算的读数使队列未满或出现下降 - **THEN** 系统用已有本月最大快照结算,不新写快照,再激活 #### Scenario: 结算不触发停机 - **WHEN** 结算观测入账时资产无套餐 - **THEN** 系统不生成"无有效套餐"停机,激活提交后再评估一次停复机 #### Scenario: 结算超时 - **WHEN** 设备下第 3 张卡结算时整次结算达到总超时 - **THEN** 系统跳过剩余卡、照常激活,并为未结算的卡写告警 ## REMOVED Requirements ### Requirement: 切换水位 **Reason**: 测试环境一次性全量切换,不再有"第一次切换观测";切换不重复扣改由迁移时全部卡打"待建起点"标记实现。 **Migration**: 迁移时全部卡置待建起点标记;`tb_card_flow_switch` 不再读写,数据保留不删。 ### Requirement: 按扣减载体灰度切换 **Reason**: 测试环境一次性全量切换,全部卡走日快照计量,灰度名单与计量模式下线。 **Migration**: 删除 `JUNHONG_TRAFFIC_CALC_MODE`、`JUNHONG_TRAFFIC_CALC_CARDS` 配置;卡表基线算法不再产生扣费增量。