卡流量计量(按名单灰度,默认 off): - 新增卡日快照与切换水位表(000241),按通道上游流量重置日换算自然月、重置日防旧值 - 已切换的卡按月对账产生增量,无生效中套餐只结算不发事件;第一次切换写水位 - 已切换卡读数有效即判定通道阈值,卡表本月用量用快照覆盖,日流量读快照 - 配置 JUNHONG_TRAFFIC_CALC_MODE/CARDS、JUNHONG_TRAFFIC_FLOW_SNAPSHOT_ENABLED 停复机规则(总开关 JUNHONG_STOP_RESUME_UNIFIED_RULE_ENABLED,默认关闭): - 复机不看停机原因,持通道阈值锁仍拒绝;暂停轮询的卡不自动停复机 - 通道新增实名管控 realname_control_enabled(000242,默认 0),开启后不区分行业卡与实名策略 - 实名管控从 0 改 1 需确认,修改并入通道更新审计 OpenSpec Change: rebuild-card-traffic-metering-and-stop-resume
9.9 KiB
Context
完整推导、老卡管反编译依据与生产核实数据见 docs/卡流量计算技术方案-参考老卡管.md(第 2 版)。本文只记录实现层的关键决策。
现状:
internal/domain/cardobservation/traffic.go的ApplyTraffic用"读数 −last_gateway_reading_mb"算增量,读数下降只在重置日当天或前一天被当作清零,其余一律拒绝;internal/application/cardobservation/traffic.go在同一事务里锁卡行、CAS 更新卡表、正增量写 V1 Outbox,读数被接受时才判定通道阈值(第 84 行)。- V1 消费者(
internal/infrastructure/cardobservation/event.go)调DeductDataUsage;没有生效中套餐时报"没有可用套餐"并由 Asynq 重试。 - 停复机集中在
internal/service/iot_card/stop_resume_service.go:自动复机只认traffic_exhausted、no_package、not_realname;实名门槛isRealnameOK放行行业卡、已实名卡和实际生效策略为none的卡。停复机判断只读套餐用量与状态,不读卡表用量字段。 - 卡表
current_month_usage_mb被资产详情、卡列表、设备导出直接读取。 - 约束:套餐侧、V1 消费者、Gateway 与三个观测入口不改;自动化测试为 N/A,验证在维护者指定的测试环境进行;生产迁移由维护者手工执行。
Goals / Non-Goals
Goals:
- 已切换的卡不再依赖卡表基线计量,冻结、读数为 0 重复计、二次销售多计、无套餐积压不再新增。
- 切换可灰度、可退回,不重不漏;未切换的卡行为不变。
- 停复机按"停机看套餐、流量、通道实名管控;复机看套餐、流量、实名,不看停因"的统一规则执行,由总开关控制上线时机。
Non-Goals:
- 冻结卡历史少扣的补数据脚本(后期另立 Change,依赖本 Change 的切换水位)。
- 积压"处理中"回执的处理(业务手动,处理前不得重放)。
- 套餐扣减口径、加油包顺序、虚流量阈值、
DeductDataUsage及消费者的任何改动。 - 卡级、设备级实名管控字段;按运营商扩展状态自动暂停轮询。
- Gateway 按日期区间查询(电信读数为 0 的问题本期不解决)。
Decisions
D1 计量照搬老卡管日快照,而不是修补基线规则。 基线是一个可被任意一次异常读数永久污染的单值状态;日快照取最大值做差,单次异常只影响当月,且可按快照复算。替代方案"放宽读数下降判定"仍依赖基线,无法根治二次销售与冻结。
D2 增量按月对账(本月最大快照 − 本月已结算合计),不按天对账。 按天对账遇到跨零点的迟到观测会重复扣;按月对账与观测先后无关,且已结算合计同时承载"发出的增量"、"无套餐丢弃的增量"和"切换时视为老算法已结算的部分"。
D3 新逻辑放在 ApplyTrafficObservation 的已切换分支内,同一事务。 卡行已在事务开头加锁,同卡观测天然串行,快照不另加行锁;快照、已结算、切换水位、Outbox 同事务提交。老 ApplyTraffic 照常计算并写卡表三列(last_gateway_reading_mb 仍是 CAS 条件,新代码只读),只是已切换卡不使用它的增量(第一次切换观测除外)。未切换卡在事务提交后用 INSERT ... ON CONFLICT DO UPDATE SET month_used_mb = GREATEST(...) 原子写快照,失败只告警。
D4 切换水位表,而不是要求阶段 1 覆盖整月。 平均每卡约 1.5 天才采一次,阶段 1 无法保证每张卡本月都有快照;水位让第一次切换观测沿用老增量并把此前部分记为已结算,同时为补数据提供截断点与冻结卡判定依据(切换后卡表本月计入仍由老逻辑维护,不能用来判定冻结卡)。退回时删除水位,再切回会重新执行。
D5 无生效中套餐时在观测事务内只读判断并丢弃增量。 与 resolveActivePackages 同口径(卡自身或当前绑定设备的 status=1 套餐),不改消费者;判断出错按有套餐处理,保持不丢量。
D6 重置日在事务内按卡的 carrier_id 严格读取。 入口传入的 ResetDay 在查询失败时已被兜底为 1,联通卡被当作 1 号重置会抬高自然月累计且按最大值规则收不回;失败时按卡表 carrier_type 兜底(CUCC 取 27,其余取 1)。
D7 不新增"读数是否有效"标记。 Gateway 的 FlexFloat 已把空、null、无法解析转为 0,新逻辑对 0 与负数一律不写快照,结果相同,Gateway 与三个入口不改。
D8 灰度单位为扣减载体,启动时展开为内存集合。 设备整台切,避免同一设备套餐同时收到两种算法的增量;判定不查库,出错走老算法。切换、扩批、退回都要先停掉 API 与全部 Worker 再一起启动,避免新旧进程并存时老进程发的增量不计入已结算合计。
D9 已切换卡的展示与通道阈值。 卡表 current_month_usage_mb 用本月最大快照覆盖(写在同一条 Updates 里),三处读取方不改;通道阈值判定条件改为"读数大于 0 且本次未被防旧值处理",EvaluateInTx 只做达量写锁、无低读数复机,放开不会误复机。
D10 停复机统一目标状态判断。 新增一个判断函数供 EvaluateAndAct 开机分支、停机分支、resumeSingleCard、resumeDeviceCards、ResumeCardIfStopped 共用:先判断暂停轮询(卡或设备 enable_polling = false,与 ShouldEnqueue 同口径)→ 不动作;开机时命中无套餐、流量用完、通道实名管控且未实名即停;停机时满足有套餐、流量未用完、已实名或通道未管控即复机,删除 isPollingStopReason 限制,保留通道阈值持锁拒绝。设备复机改为取设备下全部停机卡。套餐判断沿用 HasValidByCarrier 与 isTrafficExhausted 现有口径。
D11 实名管控为通道独立开关,isRealnameOK 是唯一实现点。 总开关开启时:通道 realname_control_enabled = 0 返回满足,= 1 时以 real_name_status 判断,删除行业卡与资产实名策略分支;通道查询失败返回错误、本次不动作。停机、复机、设备复机、人工复机、保护期一致性检查(仅通道管控且未实名时跳过)都经过它。替代方案"复用卡/设备实名策略"会让购买流程与停复机继续耦合,且需要修数据。
D12 通道阈值新周期恢复复用 D10 的复机条件(总开关开启时)。 避免同一张卡在通道阈值路径与常规路径上复机条件不一致。
Risks / Trade-offs
- [停复机总开关打开时集中动作:外部停机、人工停机的卡被集中复机;开启实名管控通道的未实名卡(含行业卡)被集中停机] → 总开关默认关闭;打开前在管理端设定需要管控的通道并预演统计,业务确认后再开。
- [人工停机不再长期有效,下一次评估满足条件即复机] → 需要长期停用的卡由人工暂停轮询;已在规格中明确。
- [外部系统反复停卡,卡管反复复机] → 按原则不设上限;需要卡管停止管理时人工暂停轮询。
- [第一次切换观测沿用老增量,若恰好撞上老算法缺陷(如重置窗口读到 0 后又读到真实值)会扣一次] → 每张卡最多一次,灰度第一批核对。
- [事务 1 判断有生效中套餐、消费者扣减前前一条事件刚好扣完唯一套餐,事件仍会积压] → 概率低;灰度期监控"处理中"回执新增数,确有发生再评估消费者调整。
- [重置日前最后一次采集到清零之间的用量丢失,采得越稀丢得越多;重置日当天未采到的卡不触发防旧值] → 与老卡管一致,轮询吞吐另行处理。
- [月中修改通道重置日导致当月换算跳变] → 修改安排在运营商实际重置日前后并核对受影响卡。
- [
ApplyTraffic为全部卡共用路径,改动出错会波及全部卡] → 新逻辑只在已切换分支,老分支不改;测试环境回归非灰度卡观测结果与改动前一致。 - [卡换绑设备后第一次观测把整张卡周期读数算给设备套餐] → 与现状一致,列入已知限制。
Migration Plan
- 迁移:新增
tb_card_flow_day、tb_card_flow_switch,tb_carrier增加realname_control_enabled smallint not null default 0;成对 up/down,生产由维护者执行。 - 发版:计量模式
off、快照开关开、停复机总开关关;全部卡开始写快照,其余行为不变。 - 阶段 1 至少跑满一个完整自然日(最好跨过一次各运营商重置日)后进入灰度:名单
device:15276,先停后启全部进程。 - 扩批条件:灰度卡逐日增量 = 按快照复算;无误停误复;跨过一次各运营商清零;冻结卡恢复计量、二次销售不带入旧用量。之后扩批、全量;全量后下线 Redis 日流量缓冲与 02:00 落盘。
- 停复机:管理端设定需要实名管控的通道 → 预演 → 打开总开关并先停后启全部进程。
- 回滚:计量模式改回
off或移出名单并删除对应卡的切换水位,先停后启;停复机总开关改回关闭。快照与水位表保留不影响老路径。
Open Questions
- "有套餐"的口径:本 Change 沿用现有口径(生效中或待生效都算有套餐);若业务要求只认生效中,需另行确认,会改变现有停机行为。
- 套餐在扣减前刚好用完导致的积压,是否在灰度后调整消费者,待灰度监控结果再定。
- 自动续费成功后的可靠复机(
asset-auto-renewal「成功后的可靠复机」,实现为autoRenewalCardReady)仍按"可轮询停因、非风险停机/销户"判断,本 Change 未改:总开关开启后,这条路径跳过的卡会在下一次套餐轮询评估时按新规则复机。是否让该路径也改用新复机条件,需另立 Change 修改asset-auto-renewal规格。