junhong_cmp_fiber/docs/卡流量计算技术方案-参考老卡管.md

卡流量计算技术方案（参考老卡管）

项目	内容
日期	2026-10-20
状态	方案，待评审，代码尚未修改
思路	流量怎么算，照搬老卡管；套餐那边一行不动：只替换"增量从哪来"，增量照旧通过 V1 事件交给现有 DeductDataUsage 扣减
改动范围	观测链路（算增量）+ 新增卡日快照表 + 日流量读取。套餐表、套餐服务、激活/重置/改已用量/换货/退款入口、扣减顺序、停复机全部不改
与旧方案关系	替代 docs/流量事实模型技术方案.md（第 5 版）的计量部分
老卡管依据	反编译 kyhl-api/WEB-INF/lib 下 kyhl-service-1.0.jar、kyhl-dal-1.0.jar、kyhl-common-1.0.jar、kyhl-common-jdbk-1.0.jar

---

1. 结论

1. 漏洞根源：新卡管现在的增量 = 本次读数 − 卡上的基线（tb_iot_card.last_gateway_reading_mb）。基线是跨套餐、跨用户的卡级状态，一旦出错（被异常高读数抬高、重置日没采到）就永久保留：卡被冻结、读数为 0 时重复计、二次销售时多计。
2. 老卡管不依赖基线：每张卡每天存一条"本月累计"快照，任何一段时间的用量都用快照现算（区间内最大值 − 区间开始前的最大值）。它没有"读数下降"的概念，已经稳定运行多年。
3. 本方案：
   • 流量计算照搬老卡管：日快照、按各运营商的重置日（tb_carrier.data_reset_day）换算成自然月、重置日防旧值、按区间取最大值做差。
   • 每次观测的增量 = 今天的快照用量 − 今天已经发出的增量，不再用卡表基线。
   • 增量照旧写进 V1 事件 CardTrafficIncremented，由现有消费者调用 DeductDataUsage 扣减。套餐分配、加油包顺序、虚流量阈值、停复机、流量详单全部沿用现有代码。
4. 二次销售：卡没有生效套餐时，增量照样计算，但只推进"已发出"标记、不发事件。所以激活之前的用量永远不会扣到新套餐上，新套餐只扣激活之后的增长。
5. 先做卡流量计算，补数据放到后期：新方案上线后，冻结卡从切换起恢复正常计量；切换前少扣的部分由后期的独立脚本补（5.5）。补数据依据的是运营商当前读数，只能补执行时所在运营商周期内的部分，更早的补不回来。

1.1 已定决策（2026-10-20）

#	事项	决定
D1	流量计算	照搬老卡管：日快照、写入时按运营商重置日（tb_carrier.data_reset_day，任意 1～28 号）换算成自然月、按区间取最大值做差，没有读数下降判定。重置日不写死，运营商配置改了随之生效
D2	套餐侧	一行不改：增量照旧走 V1 事件与 DeductDataUsage
D3	重置日防旧值	完全照搬老卡管（含比较基准）：只在重置日当天判断，R = 1 比上月最大快照、R > 1 比本月 1～R−1 号最大快照，超过 0.9 倍按 0 记；第二天起照常累加，不挂起、不告警。老卡管多年运行没有暴露问题
D4	卡无生效套餐时的增量	只推进 emitted_mb，不发事件，用量丢弃
D5	快照记录范围	全部被采集的卡
D6	上线方式	按名单灰度，单位是扣减载体，设备整台切；第一批为 103154 所在设备 15276，核对后扩批再全量。非灰度卡行为与现在一致（4.8）
D7	积压的无套餐回执	业务后续手动调整，不在本方案内；处理前不得重放
D8	顺序	先上卡流量计算，补数据放后期（5.5）
D9	补数据：本周期中间重置过套餐的冻结卡	不自动补，进清单，附按天数比例的估算值，由人工决定

2. 现在的漏洞（已验证，详见旧方案第 2 节）

#	漏洞	证据
1	卡被冻结：读数下降只在重置日当天或前一天才被认作清零，其余日子一律拒绝。基线被抬高后，之后的读数全被拒，套餐不再增长，也不停机	internal/domain/cardobservation/traffic.go:58-67。卡 103154：基线 72535 MB，运营商读数 48808 MB，9-25 之后已用量一直为 0。2026-10-12 统计 15310 张活跃卡中有 3511 张（23%，上限估计）10 月基线没动过
2	读数为 0 被当成清零：重置窗口内读到 0，基线被置 0，下一次真实读数整笔重复计	traffic.go:60-61；电信抽查 124 张中 111 张读数为 0
3	无效响应按 0 处理：used 为空、null、无法解析时当成 0，进而触发第 2 条	internal/gateway/models.go:55-78
4	二次销售多计：新用户激活时，卡上的基线如果不是激活那一刻的值，差额就扣到了新套餐上	资产回收换代见 docs/资产回收换代技术方案.md
5	日流量从来没存成功：tb_card_daily_usage 的表结构和代码不一致，表里 0 行	旧方案 P14
6	无套餐期间的增量会被扣到下一个套餐上：老路径不管卡有没有套餐都发 V1 事件；消费者调 DeductDataUsage 遇到"没有可用套餐"直接返回错误，任务由 Asynq 重试，重试期间套餐一激活，积压的增量就被扣到新套餐上——这是二次销售多计的另一条路径	application/cardobservation/traffic.go:73-76 无套餐判断；infrastructure/cardobservation/event.go:276-277 报错即返回；usage_service.go:110。生产核实（2026-10-20）：回执停在"处理中"（扣减未完成）的有 18,979 条、增量约 11.4 TB；其中 14,838 条对应的卡当前没有生效套餐，4,141 条（2,404 张卡）对应的卡当前有生效套餐，这批任务若被重试或人工重放，会扣到现在的套餐上，不得重放。积压部分由业务后续手动调整，本方案只保证新增的不再产生

3. 老卡管怎么算（反编译核实）

3.1 日快照：每卡每天一条，存"本月累计"

出处：YidongDayFlowService.saveYidongDayFlow、PtLiantongDayFlowService.savePtLiantongDayFlow。

• 表 tbl_*_day_flow：iccid_mark、flow_date、used_flow（自然月累计 MB）；普联通另存 vendor_used_flow（运营商原始读数）。
• 同一天多次查询：用新值覆盖。
  • 移动：新值比旧值小就跳过（每月 1 号除外）。
  • 普联通：读数 ≤ 0 不覆盖；当天第一条就是 0 时，沿用昨天的值。

3.2 联通：写入时把运营商周期换算成自然月

联通每月 27 号 0 点清零，运营商读数是"上月 27 号至今"。老卡管在写快照时就换算成自然月累计（老代码把 27 写死在联通的几个类里；本方案改为读 tb_carrier.data_reset_day，对任意重置日通用，见 4.3），后面统一按自然月计算：

写入日期	存入值
27 号～月底	运营商读数 + 本月 1～26 号的最大快照
1～26 号	运营商读数 − 上月 27 号～月底这段的用量（= 上月最大快照 − 上月 27 号前的最大快照）

老代码第二行取"上月 27 号前"时用的是 < 26 号，少算了一天，本方案按"1 号～重置日前一天"修正。

3.3 重置日防旧值：只有一条规则

运营商	规则
移动（1 号清零）	每月 1 号，读数 > 上月最大快照 × 0.9 → 记为 0
普联通（27 号清零）	每月 27 号，读数 > 本月 1～26 号最大快照 × 0.9 → 运营商读数按 0 计

意思是：重置日读到的值还接近上个周期的总量，就认为运营商还没清零或者读到了旧缓存，当天先不增长。除此之外，老卡管没有任何读数下降的判定。

3.4 按区间取值

出处：YidongDayFlowMapper.xml 的 getQueryTrafficByDate。

区间用量 = max(区间内的快照) − max(本月 1 号 ～ 区间开始前一天的快照)

• 只取 used_flow > 0 的快照；不能跨月查询；结果 < 0 时按 0。
• 取的是最大值，不是最新值，所以旧缓存返回一个偏小的值，不会让用量变小。

3.5 套餐用量（本方案不照搬这一块）

老卡管从套餐开始日到今天按月切段累加，再拿总用量和所有套餐的总额度比较，不区分每个套餐用了多少。新卡管有加油包、独立有效期、by_day 重置、按套餐退款，这一块沿用新卡管现有的 DeductDataUsage，不改。

4. 新方案

4.1 原则

#	原则
R1	流量照搬老卡管：日快照 + 自然月换算 + 重置日防旧值 + 区间取最大值做差
R2	套餐侧零改动：增量照旧走 V1 事件和 DeductDataUsage；套餐表、套餐入口、分配顺序、停复机都不改
R3	不再用卡表基线算增量：增量只由快照得出；卡表三列照旧由老逻辑维护，只作兼容展示
R4	日期一律按 Asia/Shanghai

4.2 数据模型

只新增一张表，不改任何现有表。迁移从当前最新编号之后开始，成对 up/down。

tb_card_flow_day（卡日快照，永久保留；仓库现无分区表，一年约 3,200 万行，靠唯一索引足够，本期不分区）

列	类型	含义
id	bigserial
iot_card_id	bigint
flow_date	date	上海日期
month_used_mb	numeric(14,3)	自然月累计（换算后），计算用
vendor_used_mb	numeric(14,3)	当天最后一次有效的运营商原始读数，排障用
emitted_mb	numeric(14,3)	当天已经发出的增量合计（见 4.5），默认 0
stale_guarded	boolean	重置日当天是否触发过防旧值（读数按 0 记）
obs_count	int	当天有效观测次数
created_at、updated_at	timestamptz

唯一键 (iot_card_id, flow_date)。每卡每天一行，8.9 万卡约 3200 万行/年。

4.3 写快照（照搬 3.1～3.3，按运营商重置日 R 统一）

R 取 tb_carrier.data_reset_day。运营商在每月 R 号 0 点（北京时间，Asia/Shanghai）清零：联通为 27 号 0 点（业务确认，见 docs/engineering/套餐流量计算逻辑核对.md；与老卡管 DateUtil.getLtPeriod 一致），其余为 1 号 0 点。周期边界直接复用现有 carrierthreshold.PeriodStart（上海时区重置日 0 点），下文"今天日号""重置日当天"都按北京时间的日期判断。查询失败、为空或不在 1～28 时，按卡的运营商类型兜底：tb_iot_card.carrier_type = CUCC（联通）取 27，其余取 1，并记日志。不能沿用现有 CarrierStore.GetDataResetDay 一律返回 1 的做法（carrier_store.go:103-104）——联通卡被错当成 1 号重置会让自然月换算出错、累计值被抬高，按取最大值的规则会多扣且收不回。老路径继续用原函数，不改。

注意取值位置：三个入口现在调用 ApplyTrafficObservation 前就用 GetDataResetDay 算好 TrafficObservation.ResetDay 传进来（polling_carddata_handler.go:103、series_runner.go:561、service/iot_card/service.go:1638），查询失败时已经是 1。新逻辑不能使用这个字段，必须在观测事务里按已锁定卡的 carrier_id 严格查一次 data_reset_day，失败再按上面的运营商类型兜底。

每次观测（轮询、人工刷新、系列观测三个入口）读到 r：

1. 无效读数和 0 不写：查询失败、used 为空 / null / 无法解析 / < 0、或 r = 0，一律不写快照、不发增量。（老卡管普联通对 0 是"当天已有行不覆盖、当天第一条沿用昨天的值"，移动是写一条 0；本方案直接不写，因为计算只看最大值，效果相同。）FlowUsageResp 增加"读数是否有效"标记，只给新代码用。
2. 换算成自然月累计 m：
   • R = 1：m = r；
   • R > 1，今天日号 ≥ R：m = r + max(本月 1 号～R−1 号的 month_used_mb)；
   • R > 1，今天日号 < R：m = r − (上月最大 month_used_mb − 上月 1 号～R−1 号的最大 month_used_mb)，< 0 按 0。
3. 重置日防旧值（完全照搬老卡管，比较基准也一致）：只在重置日当天判断，原始读数照存 vendor_used_mb：
   • R = 1：r > 上月最大 month_used_mb × 0.9 时按 r = 0 计算 m（同 YidongDayFlowService.java:123；上月没有快照时比较值为 0，任何正读数当天都按 0 记，次日如实写入，与老卡管一致）；
   • R > 1：本月 1 号～R−1 号的最大 month_used_mb 大于 0，且 r 超过它的 0.9 倍时，按 r = 0 计算 m（同 PtLiantongDayFlowService.java:126：appendFlow > 0 && flow > appendFlow × 1.9）；本月前 R−1 天没有快照时不判断；
   • 触发时置 stale_guarded = true；第二天起不再判断，读数照常写入。
4. 同一天合并：当天已有行时，month_used_mb = max(旧值, m)。

4.4 今天的快照用量（照搬 3.4）

今天用量 U(卡, 今天) = max(今天的 month_used_mb) − max(本月 1 号 ～ 昨天的 month_used_mb)
                      < 0 按 0；今天是本月第一条快照时减数为 0

• 中间有几天没采到，那几天的用量自然并入今天，不会丢。
• 每天的日流量就是 U(卡, 那天)，直接替代 Redis 日流量缓冲、02:00 落盘和 tb_card_daily_usage。

4.5 算增量并发出（替代 r − 基线）

在观测事务（事务 1，现有 ApplyTraffic 所在事务）里，对已切换的卡：

1. SELECT ... FOR UPDATE 锁住该卡今天的快照行（不存在就插入）；
2. 按 4.3 更新快照；
3. 增量 Δ = U(卡, 今天) − emitted_mb；
4. Δ > 0 且该卡有可扣的生效套餐（与 resolveActivePackages 同口径：卡自身有**生效中（status=1）**的套餐，或卡当前绑定的设备有生效中的套餐；已用完（2）、待生效（0）不算；只读查询，不加锁）：写一条 V1 事件 CardTrafficIncremented，载荷与现在完全相同（只是增量值换了来源），同时 emitted_mb += Δ；
5. Δ > 0 但没有生效套餐：不发事件，只 emitted_mb += Δ。这部分用量不属于任何套餐，丢弃（日流量照常可见）；
6. Δ ≤ 0：不发事件。

说明：

• 增量与发出标记在同一事务里，和 Outbox 事件一起提交或一起回滚，不会重复发、也不会漏发。同卡并发观测由快照行锁串行。
• 消费者完全不改：现有消费者照旧调用 DeductDataUsage 扣减（先加油包、后主套餐、超额记最后一个），写流量详单，调用 EvaluateAndAct 判断停复机，回执表照旧保证幂等。
• 没有生效套餐时不发事件：现有消费者遇到"没有可用套餐"会报错重试（第 2 节第 6 条），所以不能把这部分增量发出去。只推进 emitted_mb，激活之前的用量永远不会扣到新套餐上，二次销售天然正确，而且比老卡管按天算更精确：激活当天、激活之前的那部分也不会算给新用户。
• 是否有生效套餐只在事务 1 里只读判断一次，不改套餐侧代码；判断出错时按"有套餐"处理并发事件（保持现有行为，不丢量）。
• 卡表三列（last_gateway_reading_mb 等）和通道阈值判定：老 ApplyTraffic 照常计算、照常写，只是它算出的增量对已切换的卡不再使用。last_gateway_reading_mb 是观测的 CAS 条件，新代码只读不写。
• 已切换的卡不再发老增量的 V1：老 ApplyTraffic 算出的 decision.IncrementMB 对已切换的卡丢弃，现在第 73-76 行的发事件逻辑只在未切换分支执行；每次观测只会发一条 V1，Outbox 量不增加。
• 只有已用完或待生效套餐的卡，增量同样丢弃。这和现状一致：现状下这类增量会因"没有可用套餐"扣减失败并积压（第 2 节第 6 条），并不会扣到已用完的套餐上。

未切换的卡：事务 1 一切照旧（老增量、老 V1）；快照在事务 1 提交后单独写，失败只告警（见 4.7），用于切换前积累数据和比对。

4.6 切换当天的衔接

卡切换后的第一次观测，如果今天的快照行已经存在（切换前已经写过），先把 emitted_mb 初始化为"写入本次读数之前的 U(卡, 今天)"，再按 4.5 计算。这样今天切换前已经由老路径扣过的部分不会再扣一次，只发本次观测带来的增长。

限制：同一张卡退回老路径后当天不要再切回。当天快照上的 emitted_mb 已经不是 0，再切回时不会重新初始化，退回期间老路径扣过的部分会被再扣一次。

4.7 失败处理

失败	处理
Gateway 查询失败 / 无效读数 / 读数为 0	不写快照、不发增量
运营商重置日查不到或非法	按运营商类型兜底：联通（CUCC）27 号 0 点，其余 1 号 0 点，北京时间；记日志。老路径照旧
已切换卡：快照写入失败	随事务 1 回滚，观测重入队（与现在观测失败的处理一致）
未切换卡：快照写入失败	只告警，不影响观测；总开关可整体停写
某天没采到	用量并入下一个有快照的日子

4.8 对非灰度卡的影响核对

硬约束：非灰度的卡和设备，扣费、停复机、观测结果、页面展示都与现在一致。 新代码碰到非灰度卡的每一处：

#	接触点	设计	结论
1	写快照（阶段 1 起全部卡都写）	非灰度卡在观测事务提交之后单独写，失败、超时只告警，不让观测失败、不重入队；总开关 JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED 关掉即停写，不用发版	不影响扣费与观测；数据库多一次写入（现约 2,400 次/小时），上线后观察轮询耗时，异常即关开关
2	判断走新路径还是老路径	观测事务内用启动时载入内存的卡集合判断，不查库；判断出错一律走老路径	不影响
3	增量计算	非灰度卡仍用"读数 − 基线"，仍发 V1 事件，代码不改	不影响
4	无套餐时不发事件	只对灰度卡生效	不影响
5	Gateway 返回加"读数是否有效"标记	只给新代码用，老路径照旧（无效仍按 0 处理）	不影响
6	日流量查询	非灰度卡仍读老来源	不影响
7	数据库迁移	只新建表，不改现有表	不影响
8	设备部分卡切换	不允许：设备整台切（5.2）	不影响

唯一无法靠设计消除的风险：ApplyTraffic 是所有卡共用的代码，改动出错可能波及全部卡。约束：新逻辑只放在"判定为灰度卡"的分支里，老分支一行不改；评审重点核对这一处；测试环境回归"非灰度卡观测一次"的结果与改动前完全一致。

5. 上线

5.0 上线前提核实（2026-10-20，生产只读抽样）

新算法依赖"运营商读数在 data_reset_day 清零"。对生产卡表做 10% 块抽样，取本月有读数被接受的卡，比较当前读数与本月计入量：

运营商分组	抽样卡数	读数 ≈ 本月计入	读数略大	读数远大于本月计入	结论
重置日 1 号（移动、电信、广电共 11 个运营商账号）	765	712（93%）	28	25	读数在 1 号清零，与配置一致
重置日 27 号（联通共 10 个运营商账号）	406	134	243	29	读数含 9-27～9-30，略大于自然月计入，符合 27 号清零

• 两组都符合各自配置的重置日。
• "读数远大于本月计入"的少数卡（约 4%～7%）需要在灰度期抽查，可能是单卡读数口径异常或基线问题。
• 抽样未覆盖的运营商账号（本月抽样中没有被接受读数的卡）：1、10、11、12、16、17、20～23、25、27、30、34、37，灰度扩批前补查。
• tb_card_flow_day 在生产库与测试库均不存在（两边迁移版本均为 240），代码中无引用，新建无冲突。

5.1 阶段

阶段	内容	对业务影响
1 写快照	建 tb_card_flow_day，全部卡在观测事务提交后写快照	无，只写不用
2 灰度切换	名单内的卡按 4.5 算增量；其余照旧	只影响名单内的卡
3 全量	全部卡切换；之后下线 Redis 日流量缓冲与 02:00 落盘	—

阶段 1 至少跑满一个完整自然日再进入阶段 2；跨月或跨运营商重置日时，最好已有上个周期的快照（防旧值要用）。

5.2 切换方式

• 环境变量 JUNHONG_TRAFFIC_CALC_MODE：off（默认）/ gray / full；JUNHONG_TRAFFIC_CALC_CARDS：灰度名单，写扣减载体：iot_card:103154（单卡套餐的卡）或 device:15276（设备，展开为当前绑定的全部卡）；JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED：快照写入总开关，默认开。改完重启 API 和全部 Worker（见下方配置位置）。
• 判定在事务 1 里做，用启动时展开的内存集合，不查库；判定出错一律按老路径。
• 配置位置：新增 pkg/config/config.go 的 TrafficCalc 配置段与 pkg/config/defaults/config.yaml 的 traffic_calc: 默认值（mode: off、名单为空、快照开关开），沿用现有"嵌入默认配置 + JUNHONG_ 环境变量覆盖"机制。生产上由维护者写入各运行目录的 .env.prod：API（/opt/junhong_cmp/api/.env.prod，人工刷新走 API 进程）、调度 Worker（/opt/junhong_cmp/worker/.env.prod）和三个执行 Worker（worker-1/2/3/.env.prod）五处必须一致，否则同一张卡在不同进程里会走不同路径。改完重启对应服务。
• 灰度单位是扣减载体，设备必须整台切：名单里的设备，当前绑定的全部卡一起切换；名单里写 iot_card:X 但这张卡实际用的是设备套餐（与 resolveActivePackages 同口径），启动日志报错并跳过该项，不阻止 worker 启动。否则同一个设备套餐会同时收到新旧两种算法的增量，设备上没切换的卡也会被连带影响。
• 灰度期间灰度设备不换绑、不新绑卡：名单在启动时展开成卡集合，之后新绑到灰度设备上的卡要重启后才会切换，这期间设备处于"部分切换"状态。确需换绑的，换绑后立即重启 API 和全部 Worker 重新展开；或先把该设备移出名单。
• 退回：从名单删除或改回 off 并重启。老 ApplyTraffic 一直在维护卡表基线，退回后老路径接着算（冻结卡会回到冻结状态）。

5.3 冻结卡与历史误差

• 切换后冻结卡（如 103154）立即恢复正常计量：增量只看快照，不看卡表基线。
• 切换前少扣的部分放到后期补，用独立脚本执行，见 5.5。
• 上个周期及更早少扣的补不回来：运营商读数已经清零，没有任何记录；期间套餐已经重置的，那个计费周期也已结束。
• 第一批灰度：103154 所在设备 15276（联通 103154、移动 99426、电信 106882，三张卡本月计入都为 0）。核对无误后再放其他冻结卡、电信读数常为 0 的卡、二次销售的卡、联通卡、带加油包的载体。

5.4 扩批条件

1. 灰度卡逐日的增量合计 = 按快照手工复算的结果；
2. 无误停、无误复；
3. 至少跨过一次运营商清零（每个运营商各自的重置日）；
4. 冻结卡恢复计量，二次销售卡没有带入上一个用户的用量。

5.5 补数据（后期，独立脚本）

定位：卡流量计算上线后再做，不阻塞主方案。只补冻结卡在执行时所在运营商周期内少扣的部分；更早周期的补不回来（运营商读数已清零）。

生产现状（2026-10-20 只读核实）：

项	结果
tb_package_usage_daily_record 是否漏记扣减	没有漏记：生效中和已用完的套餐中，没有一个"已用量 > 最新日记录累计值"（10,718 个一致；1,972 个已用量为 0、是重置后尚未扣减；10,399 个从未扣减）
疑似冻结卡（最近两天在采集、本月计入为 0、上月 ≥ 100 MB）	3,425 张：设备卡 1,705（联通 1,073、移动 450、电信 182），单卡 1,720（广电 931、电信 339、联通 236、移动 214）。含本月确实没用的卡，是上限
103154 所在设备 15276	联通 103154、移动 99426、电信 106882 三张卡本月计入都是 0，不只联通卡冻结
设备下混有不同重置日的卡（联通 27 号 + 其他 1 号）	7,438 台设备、19,466 张卡，是设备套餐的大头
套餐计费起点落在本运营商周期内（多为 by_day 每 30 天重置）	10,919 个载体

后两项说明：按"载体读数之和 − 载体本周期扣减"的算法，大部分载体会因"重置日不同"或"起点在周期内"被排除，所以改为按卡补冻结卡。

算法（按卡）：冻结卡在整个本运营商周期里一条读数都没被接受，本周期计入为 0，所以

这张卡本周期少扣 = 运营商当前读数 r

• 每张卡按自己运营商的重置日确定周期起点，设备下混着不同运营商的卡也能用；不需要按套餐拆分日记录。
• r 在执行时现场查询 Gateway，限速执行；查询失败、无效、读数为 0 的跳过，进清单。

判定为冻结卡（全部满足才自动补）：

条件	原因
卡（或其所在设备）有**生效中（status=1）**的套餐（与 4.5 同口径）	只有已用完或待生效套餐时，DeductDataUsage 找不到可扣套餐会报错，补扣事件会积压（第 2 节第 6 条）；这类卡进清单
最近两天在被采集，本月计入（current_month_usage_mb）为 0	本周期没有任何读数被老路径接受
现场读数 r < 卡表基线 last_gateway_reading_mb	基线属于上个周期或被异常值抬高，读数一直被拒
卡所在扣减载体的套餐计费起点（激活或最近一次重置）早于本运营商周期起点	否则 r 里有一部分属于已经结束的上个计费周期，不该补到新周期
本周期内没有回收换代、换绑	读数和套餐对不上；也排除了二次销售

不满足的进人工清单。其中"计费起点在本周期内"的冻结卡，清单里附按时间比例估算的参考值（r × 起点至今天数 ÷ 本周期已过天数），由人工决定，不自动扣。

执行（套餐侧不改）：

1. 预演（只读）：输出每张卡的卡号、运营商、扣减载体、r、基线、补扣量、补扣后是否超额；汇总补扣总量、预计停机数、清单与原因。
2. 确认后正式执行：每张卡写一条一次性的 V1 事件，事件 ID 由卡、运营商周期、批次组成，重复执行同一批次不重复写；由现有消费者调用 DeductDataUsage 扣减，超额照常停机，补扣量照常写入 daily_record。
3. 已切换到新方案的卡，切换之后的用量由新方案计算，补扣只补切换之前那段；脚本按"切换时刻已知的读数"截断，避免与新方案重复。
4. 补扣写审计，注明"冻结卡补扣"与补扣量。
5. 现有消费者会把每条 V1 事件的增量累加进当天的 Redis 日流量缓冲，所以未切换卡的日流量会在补扣当天出现一次突增（已切换卡的日流量读快照，不受影响）。执行前告知运营，或在预演清单中标出。

6. 改动清单

位置	改动
migrations/	新建 tb_card_flow_day
internal/gateway/models.go	FlowUsageResp 增加"读数是否有效"标记（老路径行为不变）
新增 internal/domain/cardflow/	纯函数：自然月换算、重置日防旧值、今天用量；表驱动单测
新增 internal/store/postgres/card_flow_day_store.go	快照读写（含行锁）
internal/application/cardobservation/traffic.go	已切换的卡：增量改为 4.5 的算法，V1 事件载荷不变，按卡的 carrier_id 严格查重置日；未切换的卡：老逻辑不变，提交后写快照
三个观测入口（polling_carddata_handler.go、service/iot_card/service.go、series_runner.go）	只把"读数是否有效"传进 TrafficObservation（新增字段 ReadingInvalid，默认值表示有效，老调用方不受影响）；快照的写入都在 ApplyTrafficObservation 里完成：已切换的卡在事务 1 内写，未切换的卡在事务 1 提交后写
日流量查询	已切换的卡读快照
pkg/config	三个环境变量（模式、灰度名单、快照写入总开关）
后期：补数据脚本（cmd/）	预演（只读）+ 正式执行（写 V1 事件），见 5.5
套餐表、internal/service/package/、V1 消费者、激活/重置/改已用量/换货/退款入口	不改

7. 测试用例

领域层（表驱动）

场景	期望
移动同月读数上涨	今天用量 = 今天最大快照 − 本月此前最大快照
重置日 R = 27：26 号 23:59 读数 5000，27 号 00:05 清零后读数 100（北京时间）	27 号 month_used_mb = 100 + 26 号前最大值；自然月累计连续
重置日 R = 15（任意非 1 号）	换算规则同上，以 15 号为界，结果连续
重置日 R = 1	不换算，month_used_mb = 读数
运营商的 data_reset_day 被修改	从修改后的下一次写入起按新重置日换算
R > 1 时 1 号～R−1 号换算	减去上月 R 号～月底的用量，按"1 号～R−1 号"取值，不少一天
重置日当天读到上周期旧值（> 90%）	当天按 0 记，stale_guarded = true；之后读到真实低值正常累计
重置日次日起仍读到旧值	照常累加（与老卡管一致）
重置日当天真实用量超过上周期 90%	当天按 0 记；次日如实写入，取最大值把这部分带回来，只晚一天，不丢
周期中途读到偏小的旧缓存	当天快照取最大值，用量不变小，不发负增量
读数 0 / 无效	不写快照，不发增量
运营商重置日查询失败：联通卡	按 27 号换算与防旧值，记日志
运营商重置日查询失败：非联通卡	按 1 号处理，记日志
R = 1 重置日当天读数 > 上月最大快照 × 0.9	当天按 0 记
R = 27 重置日当天读数 > 本月 1～26 号最大快照 × 0.9	当天按 0 记
中间 3 天没采到	3 天的用量并入采到的那天
跨自然月	本月第一条快照减数为 0，从本月累计开始算

应用层

场景	期望
卡 103154 类：卡表基线 72535，运营商读数 48808	切换后增量按快照正常发出，套餐恢复增长
二次销售：上一个用户本月用到 3000；新用户 15 号 14:00 激活；激活前当天又读到 3020，激活后读到 3050	3020 及之前的增量在无套餐时只推进 emitted_mb、不发事件；新套餐只扣 30
卡只有已用完或待生效的套餐	不发事件，增量丢弃
灰度卡观测一次	只发一条 V1（新算法增量），不再发老增量的 V1
无套餐期间连续观测，之后激活	Outbox 里没有该卡积压的 V1 事件；激活后只扣激活之后的增长
同一次观测重复处理 / 同卡并发观测	行锁串行，emitted_mb 保证每段增长只发一次
事务 1 回滚	快照、emitted_mb、Outbox 一起回滚，不重不漏
切换当天切换前老路径已扣过一部分	按 4.6 初始化，不重复扣
名单写 device:15276	设备当前绑定的 3 张卡全部切换
联通卡观测时运营商表查询失败（入口传进来的 ResetDay 已被兜底成 1）	新逻辑不用入口的值，自行严格查询，失败按 27 号处理
名单写 iot_card:X，但该卡实际用设备套餐	启动日志报错并跳过该项，worker 正常启动，该卡仍走老路径
非灰度卡观测一次	卡表、V1 事件、扣减、停复机结果与改动前完全一致；快照在提交后单独写
关闭快照写入总开关	立即停写快照；非灰度卡不受任何影响
主套餐 + 加油包	与现有 DeductDataUsage 行为完全一致（不改）
退回老路径后的下一次观测	老路径照常运行
查询失败	不写快照、不发增量、不改套餐状态

补数据脚本（后期）

场景	期望
单卡冻结：读数 48808 < 基线 72535，本月计入 0，套餐起点早于周期起点	补扣 48808；超额则停机
设备 3 卡（联通、移动、电信）都冻结	每张卡按自己的周期起点各补其读数，合计扣到设备套餐
套餐在本周期中间激活（含二次销售）	不补，进清单
本周期内回收换代 / 换绑	不补，进清单
读数查询失败 / 为 0	不补，进清单
冻结卡只有已用完的套餐	不补，进清单
少扣为负（多扣）	不退，进清单
同一批次重复执行	事件 ID 相同，不重复写
套餐计费起点在本周期内的冻结卡	不自动补，进清单并附按时间比例的估算值

测试环境验证：103154 同类卡、三卡共用设备、二次销售卡、重置日为 27 号与 1 号的运营商各跨一次重置日、另构造一个非常规重置日（如 15 号）各一组，逐日核对快照、增量与套餐已用量。

8. 工作量（粗估）

#	任务	人天
1	迁移与模型	0.25
2	领域层：自然月换算、防旧值、今天用量 + 单测	1.5
3	快照存储（含行锁）+ 三个观测入口写快照 + 无效读数标记	1.0
4	ApplyTraffic 已切换卡的增量替换与切换当天衔接	1.0
5	切换机制（模式、名单、启动展开）	0.5
6	日流量读侧	0.5
7	集成测试与测试环境验证	1.5
	合计	约 6.25

后期补数据脚本（5.5：预演、条件判断、写 V1 事件、清单）另计约 1.5 人天。

不含灰度观察期：至少跨过一次运营商清零，约 30 天内。

9. 已知限制

限制	说明
切换前的误差	后期按 5.5 补，只能补执行时所在运营商周期内的部分；更早的补不回来；不满足条件的进人工清单
上一代套餐仍为"生效中"	DeductDataUsage 只按状态选套餐、不看世代，回收换代后上一代套餐如果仍为生效中，新用户的增量可能扣到它上面。这是套餐侧问题，按 docs/资产回收换代技术方案.md 单独修复，本方案不改套餐侧
旧周期尾部	旧周期最后一次采集到清零之间的用量拿不到，老卡管同样如此
防旧值	完全照搬老卡管：阈值 0.9、只在重置日当天判断。运营商延迟清零超过一天时，次日的旧值会被累加（老卡管同样如此，多年未暴露问题）
积压的无套餐回执	18,979 条卡在"处理中"的回执（含 4,141 条对应卡当前有生效套餐）由业务后续手动调整，不在本方案内；处理前不得重放
修改运营商重置日	月中修改 data_reset_day 会让当月换算前后不连续，可能产生一次跳变多扣。修改应安排在运营商实际重置日前后，并在修改后核对受影响卡的当日增量
采集不足	轮询吞吐问题（约 2.4k 次/小时）不在本方案范围；采不到只会晚扣，不会丢
扣错收不回	套餐侧仍是增量扣减，一旦扣错只能人工改已用量。快照可以完整复算每天应扣多少，作为核对依据
电信	老卡管的电信是直接按日期区间向运营商查询（TelecomUtilNew.queryThisMonthDianxinDayFlow）；新卡管 Gateway 目前只返回当前周期累计，本期统一按快照处理，读数为 0 的电信卡仍扣不到。后续安排 Gateway 支持按日期区间查询：支持后，电信卡改为按区间查询的结果写快照，算增量的逻辑不变；同时可以用来补旧周期尾部、补更早周期的少扣数据