- 每卡 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>
31 KiB
卡流量采集写入与扣减技术方案
| 项目 | 内容 |
|---|---|
| 日期 | 2026-10-28 |
| 状态 | 技术方案已确认,2026-10-28 按评审意见修订(T18–T25,T6 照搬老系统、按配置的重置日),代码尚未修改 |
| 前置方案 | docs/卡流量计算技术方案-参考老卡管.md(第 2 版):日快照、按重置日换算、重置日防旧值、按月对账、切换水位。本方案在它的基础上补齐"读数写入前的过滤""采集留痕""扣减口径""换卡""冲正" |
| 对应 Change | add-card-traffic-queue-and-observed-deduction(基于已实现的 rebuild-card-traffic-metering-and-stop-resume) |
| 范围 | 测试环境 |
1. 结论
- 核心问题是多扣和少扣。 现在的卡表基线算法(
last_gateway_reading_mb+ 重置窗口)一个读数就直接生效:暴涨立即扣、窗口内抖动重复扣、延迟重置整月不扣。灰度路径(日快照 + 本月最大值 − 已结算)解决了重置相关的问题,但没有过滤异常点,而且当天快照取最大值,暴涨会被留下来。 - 本方案:
- 读数先进 Redis 队列,队列内读数不下降(允许小容差)才写最后一个点,异常点在写入前拦下。
- 一次性全量切换为日快照 + 本月最大值 − 已结算,卡表基线算法、灰度名单、切换水位下线。
- 有套餐的卡每次采集都留记录,日快照读数为 0 也写;没套餐的卡只在读数 > 0 时写日快照。
- 扣减保持增量扣减,扣费按采集时刻确定套餐,日期按采集时间算。
- 扣错了走人工冲正流水;初期不做自动对账,由人工排查。
1.1 已定决策(2026-10-28)
| # | 事项 | 决定 |
|---|---|---|
| T1 | 无效读数 | 接口失败、限流、缺字段、used 为 null / 空 / 解析失败、负数、NaN:不入队、不写快照;FlexFloat 要能区分"没值"和 0 |
| T2 | 队列存储 | Redis,每卡一个 key,Lua 原子更新 |
| T3 | 队列长度 | N = 3,可配置 |
| T4 | 写入条件 | 队列满 N 个点,相邻两段都不下降(回退在容差内算持平),写最后一个点(即本次采集的点);新点不在队尾时不写 |
| T5 | 跨天清空 | 可配置开关 traffic.queue.clear_on_new_day,默认打开;打开时新点与队列里的点不在同一天(上海时间),先清空再入队 |
| T6 | 重置日 | 照搬老系统(移动 YidongDayFlowService、联通 PtLiantongDayFlowService),只把重置日换成通道配置的重置日:按配置的重置日换算成自然月累计;重置日当天全天防旧值(读数 > 比较基准 × 0.9 按 0 计;比较基准为 0 时当天任何正读数都按 0 计,不论配置的重置日是几号),不按小时区分,不设多日警惕期;重置日当天没取到有效数据,第二天起照常按新周期计;重置日早上的旧周期读数不记回前一天,月末尾巴丢失 |
| T7 | 路径统一 | 测试环境一次性全量切换,不再灰度:所有卡走日快照 + 本月最大值 − 已结算;卡表基线算法、TrafficCalcPolicy、切换水位下线;切换时所有卡打"待建起点"标记(见 6.2) |
| T8 | 写入范围 | 有套餐:每次采集写采集记录;日快照读数为 0 也写;套餐日用量每天一行,没扣也写 0。没套餐:不写采集记录,读数 > 0 才写日快照 |
| T9 | 没套餐期间的用量 | 记为已结算,之后买了套餐不补扣 |
| T10 | 扣减方式 | 增量扣减;按采集时刻生效的套餐扣,套餐到扣费时已用完或到期也照扣 |
| T11 | 停复机判断 | 通道阈值只在写入的点上判断,被队列拦下的点不参与 |
| T12 | 其他来源 | 人工刷新、激活前结算与轮询进同一个队列,规则一致(没有运营商流量推送);人工刷新返回本次读数、是否写入、原因 |
| T13 | 当天没有写入 | 不补写日快照,靠告警发现 |
| T14 | 换卡 | 换卡完成时给新卡打"待建起点"标记;新卡第一次通过队列写入时建起点(本月最大快照全部记为已结算,不扣费),之后正常扣 |
| T15 | 扣错 | 人工冲正,走冲正流水 |
| T16 | 对账 | 初期不做,人工排查 |
| T17 | "写入值 ≥ 上次写入值" | 不单独判断:日快照取最大值、增量 = 最大值 − 已结算,小的值本来就不产生增量 |
| T18 | "有套餐"口径 | 采集侧(写入范围、是否发事件、采集记录)与扣费侧用同一个"采集时刻有效套餐"判断,已用完但仍在有效期内的套餐算有套餐(见 6.1) |
| T19 | 按采集时刻扣费的边界 | 只对当前"生效中"的套餐做状态迁移;停机按当前状态判断;扣费时一个套餐都查不到按成功跳过;采集后套餐流量重置的,扣在重置后的周期(见 8.1) |
| T20 | 读数 0 | 读数校验放宽为"有限且 ≥ 0",有没有套餐决定 0 写不写,不再由读数校验拦(见第 6 节) |
| T21 | 采集间隔上限 | 留 2 次冗余:开关打开时间隔 ≤ 24h ÷ (N+2),关闭时 ≤ max_point_age_hours ÷ (N+2)(见 4.4) |
| T22 | 回退容差 | 相邻两点回退 ≤ traffic.queue.drop_tolerance_mb(默认 1 MB)算持平;重置等大幅下降仍被拦下 |
| T23 | 冲正 | 锁套餐行、按当前值加减;退回后已用量不能小于 0;提交后走停复机判断,不直接复机(见第 11 节) |
| T24 | 日期 | 整条链路的日期统一用上海日期(cardflow.ShanghaiDate),包括消费者的日流量缓冲 key |
| T25 | 套餐日用量 0 行 | 在观测事务里写:当天第一次写入时,为采集时刻的每个有效套餐确保当天一行 |
2. 整体流程
运营商接口
│
├─ ① 解析读数 ──────────── 无效:记采集记录(有套餐的卡),结束
│
├─ ② Redis 队列(Lua 原子):跨天清空(可配)→ 丢弃过期点 → 入队 → 只留最后 N 个
│
├─ ③ 写入判断:新点在队尾、队列满 N 个点且不下降(容差内)→ 写最后一个点 ── 不满足:记采集记录(有套餐的卡),结束
│
├─ ④ 数据库事务(卡级行锁)
│ 有"待建起点"标记:写快照 → 本月最大全部记为已结算 → 清标记,结束(第 10 节)
│ 换算月累计(重置日防旧值)→ 写日快照(取最大)
│ → Δ = 本月最大快照 − 本月已结算 → 记已结算
│ → 采集时刻有套餐:确保当天套餐日用量行(T25);Δ > 0 时写流量事件(outbox,带采集时间、采集 ID)
│ → 通道阈值判断(只在写入的点上)
│ → 写采集记录(有套餐的卡)
│
└─ ⑤ 异步消费流量事件
按采集时刻生效的套餐,按优先级扣减(容量按虚流量阈值)
→ 套餐日用量 upsert(日期 = 采集日期)→ 扣费审计 → 套餐用完触发停机
3. 读数解析
| 运营商返回 | 入队 | 写快照 | 采集记录(有套餐的卡) |
|---|---|---|---|
| 接口失败、超时、非 200 | 否 | 否 | 记,result = failed |
| 限流 | 否 | 否 | 记,result = rate_limited |
| 响应缺 ICCID 等必要字段 | 否 | 否 | 记,result = invalid_payload |
used 为 null、空、无法解析 |
否 | 否 | 记,result = no_reading,读数为空 |
| 负数、NaN、Inf | 否 | 否 | 记,result = invalid_reading |
| ≥ 0 的数 | 是 | 看第 5 节 | 记 |
改动:internal/gateway/models.go:55 的 FlexFloat 目前把 null、空、无法解析都转成 0。改为带"是否有值"的类型(或 *float64),流量查询结果据此区分"没值"和真实的 0;其他使用 FlexFloat 的字段保持原行为。
新类型的零值必须表示"没值":响应里完全没有 used 字段时,JSON 解析不会调用 UnmarshalJSON,字段停在零值。用 *float64(nil)或带 Valid 标志的结构(Valid = false)都满足;不能用零值为 0 的类型。
4. 采集队列(Redis)
4.1 存储
| 项 | 内容 |
|---|---|
| key | traffic:queue:{card_id} |
| 值 | 最近 N 个点,每个点 = 采集时间(Unix 毫秒)+ 运营商原始读数(MB,原样,不换算) |
| 过期 | 每次更新后设为第二天 01:00(上海时间);跨天清空关闭时设为 max_point_age_hours 之后 |
| 内存 | 每卡约 150 字节,100 万张卡约 150 MB |
队列只是写入前的过滤器,不是账:
- key 丢了(Redis 重启、淘汰)→ 队列从空开始,晚写 N−1 次,不多扣也不少扣。
- 入队成功、后面的数据库事务失败 → 队列里多一个点,下次采集重新判断即可。
Redis 淘汰策略:测试环境已确认为 noeviction、未设 maxmemory,队列不会被淘汰;内存需随卡数观察。
4.2 Lua 脚本
入参:card_id、新点(采集时间、读数)、N、clear_on_new_day、max_point_age_ms、过期时间。上海日期由 Go 侧算好传入(每个点存日号),Lua 里不做时区换算。
points = 读出队列
if clear_on_new_day and points 非空 and 上海日期(points 最后一个点) != 上海日期(新点):
points = []
if max_point_age_ms > 0:
丢掉 points 中 新点时间 − 点时间 > max_point_age_ms 的点
按采集时间把新点插入 points(同一时间的点去重)
只保留最后 N 个
写回,设置过期
return points, 新点是否在队尾
按采集时间插入,保证同一张卡同时有两次采集(轮询 + 人工刷新)时顺序正确;观测事务本身仍然加卡级行锁。
乱序:新点插入后不在队尾(比队列里已有的点更早到达顺序靠后),或者插进去就被裁掉,本次不写,decision = out_of_order。队尾的点之前已经判断过,再写一次虽然不影响账(GREATEST + 增量公式),但会让这条采集记录看起来写了自己的读数,排查时误导。
4.3 配置项
放在系统配置里,读法与沉默期总开关 package.silence.enabled 相同(internal/application/packagesilence/settings.go,带短缓存),改了不用重新发布。
| key | 默认 | 说明 |
|---|---|---|
traffic.queue.size |
3 | 队列长度 N,最小 2 |
traffic.queue.clear_on_new_day |
true | 跨天是否清空 |
traffic.queue.max_point_age_hours |
72 | 队列里超过这个时长的点,入队时丢掉;0 表示不限 |
traffic.queue.drop_tolerance_mb |
1 | 相邻两点回退不超过这个值算持平;0 表示不允许回退 |
4.4 跨天清空开关
| 打开(默认) | 关闭 | |
|---|---|---|
| 队列里的点 | 只有当天的 | 可以跨天,最长 max_point_age_hours |
| 每天首次写入 | 当天攒满 N 个点 | 跨天后的新点进来就能判断 |
| 前一天最后一段用量 | 算进第二天第一次写入 | 跨天的点能直接写 |
| 采集间隔上限 | 间隔 ≤ 24h ÷ (N+2)(N=3 时为 4.8 小时) | 间隔 ≤ max_point_age_hours ÷ (N+2)(默认为 14.4 小时) |
关闭时的重置日:队列里存的是原始读数,重置时读数大幅下降、斜率为负,自然被拦下,新周期攒满 N 个不下降的点后才写,不会把新旧周期混着写。
max_point_age_hours 的作用:卡停用几天后重新采集时,不用几天前的旧点来确认当前读数是否稳定。
采集间隔上限:理论最低要求是窗口内采到 N 次(开关打开时 24h ÷ N),但这样一次失败或限流,当天就写不进去,T13 告警会常态触发。上限按 N+2 次算,留 2 次冗余。
间隔还决定每天第一次写入的时间:开关打开时,当天第一次写入在第一次采集之后 (N−1) × 间隔(N=3、间隔 4.8 小时,约为当天第一次采集后 9.6 小时)。这之前的用量(含前一天最后一段)都在这次写入时一起扣,停机也在这时才判断。需要更及时的扣费和停机时,应缩短间隔,而不是只满足上限。
采集间隔校验:只校验启用中的轮询配置,停用的不管。保存(启用状态)或启用轮询配置时,流量采集间隔超过当前开关下的上限直接报错;traffic.queue.size 或开关修改时,同样校验现有启用中的轮询配置,不满足的拒绝保存。测试库启用中的只有 id 29(间隔 60 秒,满足上限);id 25(86400 秒)是停用的,不拦,以后要启用时再按上限调小。
5. 写入判断
同时满足以下条件,写最后一个点(即本次采集的点):
- 新点在队尾(4.2 乱序);
- 队列满 N 个点;
- 相邻两点都不下降:后一个读数 ≥ 前一个读数 −
drop_tolerance_mb。
- 只比较先后读数,与采集间隔是否均匀无关。
- 持平也写:有套餐但没用流量的卡能写入 0 用量。
- 容差:日快照取当天最大值、增量 = 最大值 − 已结算,小幅回退的点写进去也不产生增量,所以容差不会造成多扣;它只是避免读数在几 KB 内来回跳时整窗不写。重置时的大幅下降远超容差,照样被拦下。
N=3、容差 1 MB 的例子:
| 队列 | 结果 |
|---|---|
| 100, 150, 200 | 写 200 |
| 100, 100, 100 | 写 100 |
| 100, 150, 120 | 不写 |
| 100, 99999, 120 | 不写(中间点暴涨被拦下) |
| 100, 110, 99999 | 写 99999(最后一个点暴涨挡不住,见第 14 节) |
| 100.002, 100.001, 100.003 | 回退 0.001 在容差内,写 100.003 |
| 3010, 20, 25(重置) | 不写 |
| 20, 25, 30(新周期) | 写 30 |
不写时,原因记进采集记录(第 7.1 节)。
6. 写入:日快照与结算
沿用灰度路径(internal/application/cardobservation/traffic_flow.go),改动见下。
读数校验放宽:cardflow.ValidReading 现在要求读数 > 0,writeSnapshot 与 writeUnswitchedSnapshot 都以它为前提,读数为 0 的点写不进快照,与 T8 冲突。改为"有限且 ≥ 0"(与第 3 节的入队条件一致);没套餐的卡读数为 0 不写快照,由 6.1 的写入范围判断,不再由读数校验拦。读数 0 在重置日不触发防旧值(isStale 对 ≤ 0 直接返回否),换算结果不变。
- 换算:
cardflow.Convert,按卡所属通道的重置日把被写入那个点的读数换算成自然月累计;重置日当天读数超过比较基准 × 0.9 按 0 计(防旧值)。日期取被写入那个点的采集日期。 - 写日快照
tb_card_flow_day:upsert,month_used_mb取当天最大(GREATEST)。 - 结算:
Δ = 本月最大快照 − 本月已结算,Δ > 0 记入当天settled_mb。 - 事件:采集时刻卡有套餐(6.1.1)且 Δ > 0,同事务写流量事件(outbox),事件带采集时间和采集 ID。
- 停复机:通道阈值只在这里判断(被队列拦下的点不判断)。
6.1 写入范围
| 有套餐 | 没套餐 | |
|---|---|---|
| 被写入的点读数为 0 | 写日快照 | 不写 |
| 被写入的点读数 > 0 | 写日快照 | 写日快照 |
| 套餐日用量 | 每个有效套餐(6.1.1)每天一行,没扣也写一行 0 | — |
| Δ | 发事件扣费 | 只记已结算(T9) |
套餐日用量 0 行在观测事务里写(T25):扣减消费者只在 Δ > 0 时才运行,没用流量的卡走不到那里。所以在观测事务里,当天第一次写入时,为采集时刻的每个有效套餐 INSERT ... ON CONFLICT (package_usage_id, date) DO NOTHING 一行 0;之后扣减按 8.2 累加。由 usage_service 提供方法,观测事务调用,不在 cardobservation 里直接写套餐表。
6.1.1 "有套餐"口径(T18)
采集侧(写入范围、是否发事件、是否写采集记录)与扣费侧(8.1 查套餐)用同一个函数判断"采集时刻有效套餐":
| 条件 | 说明 |
|---|---|
| 状态 | status IN (生效中, 已用完, 已过期);待生效、已失效不算 |
| 已生效 | activated_at ≤ observed_at;activated_at 为空的历史数据按已生效处理(与现有口径一致) |
| 未到期 | expires_at 为空,或 expires_at > observed_at |
| 未退款 | refund_id IS NULL |
| 载体 | 卡自己的套餐;卡自己一个都没有时,看卡当前绑定设备的套餐 |
- 已用完但仍在有效期内的套餐算有套餐:套餐用完到真正停机之间的用量照常发事件,扣费时进最后一个套餐的超出部分(T10)。现在
countActivePackages(traffic_calc_policy.go:148)只认"生效中"、不看expires_at,这段用量被记为已结算、不发事件,recordOverflowToDepletedPackage实际收不到流量,需要改。 - 已过期状态之所以纳入,是因为状态可能在采集之后才变为已过期;是否在采集时刻有效由
expires_at判断。 - 待实名激活、沉默期等待中的套餐处于待生效状态,不算有套餐,期间用量按 T9 记为已结算。
6.2 路径统一
测试环境一次性全量切换,不再灰度(T7):
- 删掉
TrafficCalcPolicy(灰度名单)、卡表基线算法的扣费作用、第一次切换逻辑(firstSwitch)和切换水位(tb_card_flow_switch不再读写)。 - 切换时所有卡打"待建起点"标记(随迁移执行,与换卡同一个标记,第 10 节)。原因:切换前扣费走的是卡表基线算法,日快照上没有本月已结算(测试库
tb_card_flow_day为 0 行);不打标记,切换后第一次写入的 Δ 会是运营商读数对应的整月用量,而这些用量老路径已经扣过。打了标记,每张卡切换后第一次写入只建起点、不扣费。 - 切换过程中老代码还在跑也安全:老代码不认标记,照常按老路径扣;新代码第一次写入只建起点,不会重复扣。
- 代价:老路径最后一次扣费到新路径建起点之间的用量不扣(约 N−1 个采集周期),测试环境可接受。
- 卡表上的
current_month_usage_mb等展示字段由日快照覆盖(与现灰度路径一致);last_gateway_reading_mb不再使用。
7. 留痕
7.1 采集记录(新表)
只记有套餐的卡,每次采集一条,包括接口失败和读数为 0。
| 字段 | 说明 |
|---|---|
id、iot_card_id、observed_at |
|
observation_id |
采集 ID,与流量事件、扣费审计、对接日志串联 |
source、scene |
轮询、人工刷新、激活前结算 |
result |
读数是否有效:ok / failed / rate_limited / invalid_payload / no_reading / invalid_reading |
vendor_used_mb |
运营商原始读数,可为空 |
queue_points |
入队后的队列(jsonb:采集时间 + 读数) |
decision |
读数有效之后怎么判断的,result ≠ ok 时为空:written / baseline(建起点)/ queue_not_full / slope_negative / out_of_order / settled_existing(激活前结算没写入,用已有本月最大快照结算) |
month_used_mb、stale_guarded |
写入时才有:换算后月累计、是否触发防旧值 |
delta_mb、event_id |
写入时才有:本次 Δ、流量事件 ID |
created_at |
- 按
observed_at按月分区,保留 90 天,过期直接删分区(不用DELETE ... LIMIT)。整月都过期才能删,所以同时存在 4 个分区(约 120 天的数据)。 - 数据量:每天行数 ≈ 有套餐的卡数 × 每天采集次数。例:10 万张卡、间隔 4.8 小时(每天 5 次),每天 50 万行,4 个分区约 6000 万行。
- 索引:
(iot_card_id, observed_at DESC)、observation_id。
7.2 排查路径
扣费审计(package_usage.deduct_traffic:扣了哪个套餐、多少、前后值)
→ parent_event_id → 流量事件(卡、增量、采集时间、采集 ID)
→ observation_id → 采集记录(当时的原始读数、队列、判断结果)
→ 卡 + 日期 → 日快照(当天最大值、已结算)
8. 扣减
扣减逻辑沿用 internal/service/package/usage_service.go 的 DeductDataUsage:小数部分攒在 Redis;加油包优先,再按 priority、id;每个套餐容量 = 阈值 − 已用(启用虚流量时阈值为虚总量,否则为真总量);最后一个套餐承接超出部分;全部用完触发停机。
改动两点:
8.1 按采集时刻确定套餐
- 流量事件已带
observed_at,消费者把它传给扣减。 - 查套餐由"当前
status = 生效中"改为"采集时刻处于生效期内":已激活、activated_at ≤ observed_at、未到期(expires_at > observed_at)、未退款、未作废;设备回退口径不变。 - 查询条件与 6.1.1 共用同一个函数,采集侧和扣费侧不会出现"采集说有、扣费说没有"(采集后退款、作废的情况除外,见下)。
- 采集时刻生效、但扣费时已用完或已到期的套餐照扣(T10)。
- 排序、容量、超出承接规则不变。
状态迁移只作用于当前"生效中"的套餐(T19)。现有循环(usage_service.go:124-166)在余量 ≤ 0 或扣到阈值时把套餐改成"已用完"。查询范围扩大后,集合里会有已过期、已用完的套餐,按现有写法会把"已过期"改回"已用完"。改为:
| 套餐当前状态 | 累加 data_usage_mb、写日用量 |
改状态 |
|---|---|---|
| 生效中 | 是 | 扣到阈值改为已用完(同现在) |
| 已用完 | 是(只会作为最后一个套餐承接超出) | 否 |
| 已过期 | 是 | 否 |
- 余量 ≤ 0 且不是最后一个套餐的,跳过;只有当前是"生效中"的才顺带改为已用完。
- 停机判断
checkAndTriggerSuspension不变,仍按当前状态判断是否还有可用套餐。
扣费时一个套餐都查不到:采集时刻有套餐(所以发了事件),扣费前该套餐被退款或作废。现在 DeductDataUsage 返回"没有可用套餐"错误,消费者会一直重试。改为:记告警日志和扣费审计(标明跳过原因),事件按成功处理,不重试;该笔用量需要时走人工冲正。
采集之后套餐流量被重置:日/月重置任务(reset_service.go)把 data_usage_mb 清零。采集时刻早于套餐 last_reset_at、扣费在重置之后的,扣在重置后的周期,不跳过(跳过就是少扣)。审计里记录 observed_at 与 last_reset_at,排查时能看出这笔是跨重置扣的。列入第 14 节已知限制。
8.2 套餐日用量
updateDailyRecord由"先查后插"改为 upsert((package_usage_id, date)唯一),daily_usage_mb累加、cumulative_usage_mb覆盖。date取采集日期(cardflow.ShanghaiDate(observed_at)),不取扣费时间。- 消费者的日流量缓冲 key(
event.go里RedisCardDailyTrafficKey(..., event.ObservedAt.Format(...)))同样改为上海日期;现在直接Format,时间值是 UTC 时上海 0~8 点会落到前一天(T24)。
9. 其他读数来源
| 来源 | 处理 |
|---|---|
| 轮询 | 第 2~6 节 |
| 人工刷新 | 同一个队列、同一套规则;接口返回本次读数、是否写入、不写原因 |
| 激活前结算 | 读数同样过队列;本次没写入时,用卡上已有的本月最大快照做结算(把它全部记为已结算),不新写快照,decision = settled_existing |
激活前结算没写入时,"最近一次写入到激活"之间的用量会算给新套餐,精度到写入粒度(第 14 节)。
10. 换卡
套餐使用记录随换卡整条迁到新卡(internal/service/exchange/migration.go:103),已用量跟着走,所以不需要老系统那套"旧卡流量补算"(tbl_new_card_add_flow)。需要处理的是新卡的起点:
| 问题 | 例子 | 处理 |
|---|---|---|
| 新卡换卡前已有读数 | 出库前测试用了 50 MB,库存期间没轮询 | 新卡建起点(下文),这 50 MB 不扣 |
| 旧卡最后一段 | 最后一次采集 10:00,换卡完成 10:30 | 不处理:旧卡之后的采集按没套餐处理,记为已结算(与 T9 一致) |
建起点:
- 换卡事务内,在新卡上打"待建起点"标记(
tb_iot_card新增标记字段),不在换卡流程里调用运营商接口。 - 新卡的读数照常过队列。第一次满足写入条件时,看到标记:写日快照,把新卡本月最大快照全部记为已结算,不发事件,清掉标记,写采集记录(
decision = baseline)。 - 之后按正常规则处理。
建起点也过队列,是为了不让一个异常读数当起点:第一个读数是 99999 时如果直接当起点,本月最大值一直是 99999,之后整月增量为 0、不扣。
N=3、间隔 1 小时的例子:
| 时间 | 事件 | 读数 | 队列 | 处理 |
|---|---|---|---|---|
| 10-20 10:00 | 换卡完成 | — | — | 打标记 |
| 10-20 11:00 | 采集 | 52 | 52 | 不满,不写 |
| 10-20 12:00 | 采集 | 53 | 52, 53 | 不满,不写 |
| 10-20 13:00 | 采集 | 55 | 52, 53, 55 | 写 55,建起点:55 记为已结算,不扣,清标记 |
| 10-20 14:00 | 采集 | 58 | 53, 55, 58 | 写 58,扣 3 |
代价:换卡完成到建起点之间的用量不扣(比直接用第一个读数多 N−1 个采集周期),与"旧卡最后一段不补扣"口径一致。
设备换货时,设备套餐迁到新设备,新设备绑定的每张卡同样打标记。
11. 人工冲正
新增冲正流水表,冲正只通过它进行,不直接改套餐字段。
| 字段 | 说明 |
|---|---|
id、package_usage_id、iot_card_id / device_id |
|
delta_mb |
正数补扣,负数退回 |
before_usage_mb、after_usage_mb |
套餐已用量前后值 |
reason |
必填 |
ref_observation_id、ref_event_id |
关联的采集记录、流量事件,可选 |
operator_id、created_at |
处理:
- 事务内先
SELECT ... FOR UPDATE锁套餐行(与扣减同一把锁),按锁住后的当前值 +delta_mb计算新值,before_usage_mb取锁住后的值。避免与扣减并发时互相覆盖。 - 退回后已用量小于 0 直接报错,不截成 0。
- 同一事务内写流水、更新套餐
data_usage_mb,按阈值重新计算状态(已用完 ↔ 生效中);已过期、已失效的套餐只改已用量,不改状态(与 8.1 一致)。 - 写审计(新动作码,例如
package_usage.adjust_traffic)。 - 提交后调用现有停复机判断(
evaluator.EvaluateAndAct),不直接复机或停机:卡可能同时因为实名、沉默期、人工等原因停着,冲正只改变了"套餐用完"这一个条件,由停复机判断综合决定。 - 卡上的日快照与已结算不改,冲正只作用在套餐上。
12. 监控与告警
| 指标 | 告警条件 |
|---|---|
| 有套餐的卡一整天没写入 | 开启轮询的卡,当天采集记录里没有 decision = written(T13) |
| 队列拦截率 | 某张卡当天 slope_negative 占比过高,或全局拦截率突增 |
| 待建起点 | 开启轮询的卡,"待建起点"标记超过 1 天未清除(一直没写入);不轮询的卡不告警 |
| 乱序 | out_of_order 数量突增(排查并发采集或时钟问题) |
| 防旧值命中 | 重置日命中数,便于核对重置日配置 |
13. 改动清单
| 位置 | 改动 |
|---|---|
internal/gateway/models.go |
流量读数区分"没值"和 0,零值表示没值 |
internal/task/polling_carddata_handler.go |
无效读数分类;调用队列;写采集记录 |
| 新增队列组件(Redis + Lua)、配置项注册 | 第 4 节;返回新点是否在队尾;写入判断(不下降 + 容差、写最后一个点) |
internal/application/cardobservation/traffic.go、traffic_flow.go |
按 6.1 的写入范围;确保套餐日用量 0 行;通道阈值只在写入点判断;删除未切换分支、firstSwitch 与切换水位 |
internal/domain/cardobservation/traffic.go |
基线算法下线 |
internal/application/cardobservation/traffic_calc_policy.go |
hasActivePackageForCard 改为调用 6.1.1 的共用判断(含已用完、按 expires_at、排除退款);删除灰度名单 |
internal/domain/cardflow/rules.go |
ValidReading 放宽为"有限且 ≥ 0";isStale 去掉 ThisMonthBeforeResetMax > 0 条件,比较基准为 0 时不论配置的重置日是几号都照常防旧值;调用方注释同步 |
internal/infrastructure/cardobservation/event.go |
把 observed_at 传给扣减;日流量缓冲 key 用上海日期 |
internal/service/package/usage_service.go |
按采集时刻查套餐(与采集侧共用判断);状态迁移只作用于当前生效中的套餐;查不到套餐按成功跳过;updateDailyRecord upsert,日期按采集日期(上海);提供"确保当天日用量行"方法供观测事务调用 |
| 人工刷新、激活前结算入口 | 过队列;人工刷新返回写入结果 |
internal/service/exchange |
换卡完成时给新卡打"待建起点"标记 |
| 观测写入 | 有"待建起点"标记时,第一次满足写入条件时建起点并清标记 |
| 轮询配置保存/启用、队列配置保存 | 采集间隔上限校验(24h 或 max_point_age_hours ÷ (N+2)),只校验启用中的配置 |
| 新表 + 迁移 | 采集记录(按月分区)、冲正流水;tb_iot_card 待建起点标记,迁移时所有卡置为待建起点(6.2);(package_usage_id, date) 唯一索引 |
| 后台接口 | 采集记录查询、冲正(锁套餐行、不允许负数、提交后走停复机判断) |
14. 已知限制
| 限制 | 说明 |
|---|---|
| 最后一个点暴涨 | 队列挡不住,靠人工冲正 |
| 运营商连续返回错误且递增 | 队列挡不住,靠人工冲正 |
| 运营商整体抬高、事后下调 | 队列挡不住;初期靠人工,后期可接运营商 T+1 数据对账 |
| 月末尾巴 | 最后一次写入的旧周期读数到运营商归零之间的用量丢失,与老系统一致 |
| 防旧值比较基准为 0 | 没有快照可比(新卡、之前没写入)时,配置的重置日当天任何正读数都按 0 计,次日如实写入;只会晚一天扣,不会多扣 |
| 运营商跨天才归零 | 防旧值只管重置日当天(T6,不设警惕期);运营商晚一天才清零、重置日当天没取到数后第二天拿到旧数、清零后又返回缓存旧数,这些读数都会被当成新周期用量,造成多扣 |
| 写入粒度 | 激活前结算、换卡、没套餐 → 有套餐的切换点,精度都到"最近一次写入" |
| 晚写 | 队列需要攒满 N 个点,读数回退超过容差时会一直不写,扣费与停机相应延后 |
| 切换和换卡的起点 | 切换、换卡后到建起点之间的用量不扣(约 N−1 个采集周期) |
| 跨套餐流量重置 | 采集在套餐重置前、扣费在重置后的,扣在重置后的周期 |
| 采集后退款、作废 | 扣费时查不到套餐,跳过不扣,需要时人工冲正 |
15. 后续
- 对账:接入运营商 T+1 日用量或月账单后,定期从日快照(或运营商数据)重算,与套餐已用量比对;多扣自动退回、少扣告警,调整同样走冲正流水。
- 月末尾巴:重置日把旧周期读数的增量补上(旧周期读数 ≥ 上次旧周期读数时,差额计入本月),可选。