Files
邹进 9c3c258f16
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m27s
feat: 卡流量读数先过采集队列再入账,扣减按采集时刻确定套餐
- 每卡 Redis 采集队列(默认 N=3、跨天清空、回退容差 1 MB),攒满且不下降才写最后一个点
- 测试环境全量切换日快照计量,下线灰度名单、切换水位与卡表基线扣费;全部卡置待建起点
- 读数区分没给值与 0;有套餐的卡读数 0 也写快照与日用量 0 行;重置日比较基准为 0 照常防旧值
- 新增采集记录(按月分区保留 90 天)、人工冲正流水与后台接口、采集告警
- 扣减按采集时刻有效套餐查找,只对生效中套餐做状态迁移,查不到套餐按成功跳过
- 换货新卡(新设备下的卡)打待建起点;采集间隔上限只校验启用中的轮询配置

Change: add-card-traffic-queue-and-observed-deduction

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 12:18:47 +09:00

19 KiB
Raw Blame History

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 配置;卡表基线算法不再产生扣费增量。