- 新增 tb_gateway_readonly_card(卡 ICCID / 设备 IMEI)与开关 JUNHONG_GATEWAY_READONLY_ENABLED, 替换环境变量名单 JUNHONG_GATEWAY_READONLY_ICCIDS - 只读资产只放行查卡状态、查实名、查流量、查设备信息、查设备槽位、同步设备状态; 停机、复机、限速、实名认证链接与设备写操作在网关出口本地拦截;查表失败按拦截;不缓存 - 测试环境部署开启只读模式;新增技术方案与清理顺序文档 Change: add-gateway-readonly-prod-import Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.8 KiB
测试环境导入生产数据验证流量计量技术方案
| 项目 | 内容 |
|---|---|
| 日期 | 2026-10-29 |
| 状态 | 方案已确认(2026-10-29),代码未修改 |
| 范围 | 测试环境 |
| 关联 | docs/卡流量采集写入与扣减技术方案.md、Change add-card-traffic-queue-and-observed-deduction、docs/测试环境生产卡只读模式清理顺序.md |
1. 背景与目标
生产(迁移版本 240,仍是卡表基线算法)大量卡"卡住":卡表基线 last_gateway_reading_mb 高于运营商读数,读数被当成下降拒绝,套餐长期扣 0。2026-10-29 核对:
- 生产有生效套餐、开启轮询、本月用量为 0、基线大于 0 的卡:1632 张(独立卡 1233 张)。
- 其中 916 张在 flowcollector 10-26 起的读数里持续上涨、一直未扣,合计约 1635 GB。
- 单卡导入测试环境已验证新算法可解冻并按增量扣费(测试卡 12244、12245),但单卡无法说明全量差距。
目标:把生产的卡、设备与套餐数据导入测试环境,用新计量逻辑(采集队列、日快照、建起点、按采集时刻扣减)跑真实读数,算出全量差距;全过程不得对真实卡、设备发起任何写操作(停复机、限速、实名认证、设备指令)。
不做:订单、钱包、分佣、退款、审批、个人客户、通知等业务流程的验证;生产发布与回滚。
2. 数据规模(2026-10-29)
| 项 | 生产 | 测试 |
|---|---|---|
| 卡 | 98,567(开启轮询 90,073,独立卡 59,900) | 33 |
| 设备 | 20,144(有效绑定 38,667) | 6 |
| 生效中套餐 | 22,426(其中设备套餐 10,799) | — |
| 待生效 / 生效中 / 已用完套餐 | 29,175 | 128(全部状态) |
| 使用中的运营商通道 | 34 | 13 |
| 迁移版本 | 240 | 268 |
3. 方案总览
① 建只读表 + 开关上线(测试环境)
② 生产数据 → 只读表(全部 ICCID 与设备 IMEI)
③ 确认部署生效、只读表已写入
④ 导入卡、设备、绑定、套餐(测试库),全部卡打"待建起点"
⑤ 轮询按新逻辑采集 → 采集记录、日快照、套餐扣减
⑥ 差距报表:新逻辑应扣 vs 生产已扣
⑦ 验证结束后按清理文档撤除
必须先 ①②③ 再 ④:导入的卡在测试环境一开始没有套餐或状态不一致,会立即触发停复机判断,此时只读保护必须已生效。
4. 只读表与开关
4.1 表 tb_gateway_readonly_card
| 字段 | 说明 |
|---|---|
id |
主键 |
identifier |
网关请求里的卡号 cardNo:卡为 ICCID,设备指令为设备 IMEI;大写;唯一索引 |
identifier_type |
iccid / imei |
source |
来源,如 prod_import_20261029 |
remark |
备注 |
created_at |
写入时间 |
- 新的成对迁移建表;不写入数据(数据是测试环境专用,由导入脚本写入)。
- 不使用数据库外键。
4.2 开关 JUNHONG_GATEWAY_READONLY_ENABLED
只读表里的卡与设备只允许查询类调用,其余一律不允许:
| 允许 | 接口 |
|---|---|
| 查卡状态 | /flow-card/status |
| 查实名 | /flow-card/realName |
| 查流量 | /flow-card/flow |
| 查设备信息 | /device/info |
| 查设备槽位 | /device/slot-info |
| 同步设备状态 | /device/sync-info |
true:网关客户端每次调用前,接口不在上表时,按请求卡号(cardNo)查表,命中则本地拦截、不发请求,返回明确失败(不是结果未知),记日志gateway.readonly_card.blocked。上表接口不查表、直接放行。- 被拦截的包括但不限于:停机
/flow-card/cardStop、复机/flow-card/cardStart、限速/flow-card/speedLimit、实名认证链接/flow-card/RealNameVerification,以及设备切卡、恢复出厂、重启、WiFi 配置、模式切换。 - 查表失败(含超时、表不存在)按拦截处理:宁可调用失败,不放过真卡。
- 不做内存缓存:非查询类调用本身不频繁,按唯一索引查表约 1 ms;表一写入立即生效,没有刷新空窗。
- 未配置或为
false:不查表。生产不配置。 - 替换现有
JUNHONG_GATEWAY_READONLY_ICCIDS;名单内现有两张卡(89861590172420410612、89861590172420420169)迁入表中。
4.3 拦截覆盖面
所有网关调用都经过 internal/gateway/client.go 的 doRequest / doRequestWithoutPayloadLog,在这里判断即可覆盖所有入口:自动停复机(轮询、流量扣减、通道阈值、套餐激活与到期、订单、退款)、人工停复机按钮、限速档位、实名认证链接、设备各类接口等。业务代码不做任何改动。
5. 数据导入
5.1 范围(2026-10-29 已确认:全量)
| 数据 | 导入内容 |
|---|---|
| 运营商通道 | 不导入;按 carrier_code 映射到测试库已有通道,测试库缺的通道按生产配置补建(含重置日) |
| 卡 | 生产全部卡(98,567):ICCID、ICCID19/20、MSISDN、虚拟号、通道、卡类别、实名状态、网络状态、实名策略、轮询开关;店铺统一挂测试代理 9「测试采购部」 |
| 资产标识 | 每张卡的 ICCID、虚拟号写入 tb_asset_identifier |
| 设备与绑定 | 生产全部设备(20,144):设备号、IMEI、SN、槽位与有效绑定关系;店铺统一挂测试代理 9「测试采购部」 |
| 套餐使用记录 | 卡套餐与设备套餐中待生效、生效中、已用完的记录(约 29,175 条),保留生产的开始(生效)时间、结束(到期)时间、真总量、虚总量、重置周期与下次重置时间、优先级与主套餐 / 加油包关系;只保存真实已用量(data_usage_mb,导入时刻的生产当前值;待生效套餐本来为 0)。虚流量已用量不存储,由真实已用量 × 展示倍率 display_gain_ratio_snapshot 现算(上限为真总量);虚总量、展示倍率、是否启用虚流量是套餐条款快照(停机线 = 启用虚流量时的虚总量,否则真总量),照原样复制;订单号用 PROD-<原订单号> 标记,订单 ID 用不存在的占位值;package_id 指向一个测试占位套餐 |
| 不导入 | 订单、钱包、分佣、退款、个人客户、审批、历史日用量与审计 |
5.2 方式
用导入脚本直接写测试库(后台导卡接口一次只能导卡,不能导设备与套餐,也不适合 10 万级数据):
- 从生产只读导出(dbhub / 只读连接),生成 CSV。
- 写只读表:全部 ICCID 与设备 IMEI。
- 确认开关已部署(以 Gitea Actions 部署成功为准)且只读表行数与导出一致。
- 按通道映射写卡、资产标识、设备、绑定、套餐;同 ICCID / IMEI 已存在则跳过并记录。
- 全部导入的卡置"待建起点"(
traffic_baseline_pending = true)。 - 触发轮询重新加载(重启 Worker 或调用轮询初始化),使导入的卡进入调度。
导入脚本放在 cmd/zz_tmp_*,不提交;只允许连接 junhong_cmp_test。
5.3 建起点
每张卡在测试环境第一次通过队列写入时只建起点:把当时运营商读数对应的本月累计全部记为已结算,不扣费。之后按增量扣到导入的套餐上。因此测试环境算出的是"导入之后"的应扣,导入之前的差距由第 7 节用 flowcollector 读数补充。
6. 轮询
- 完全按测试环境现有的轮询配置与代码逻辑运行,不为导入的卡、设备单独配置,也不改业务流程:查卡状态、查实名、查流量、查套餐照常执行;流量照常进采集队列、写日快照、建起点、按增量扣套餐;套餐照常激活、到期、重置;停复机判断照常执行并记录。
- 唯一不同:导入资产的网关调用只放行查询类(查卡状态、查实名、查流量、查设备信息、查设备槽位、同步设备状态),停机、复机等其他调用在网关出口拦截(第 4 节)。被拦截的停复机记为失败并按退避重试,本地卡状态不变;这些失败记录是预期的,也正好说明"按新逻辑该停/该复"的卡有哪些。
- 查卡状态、查实名放行后,测试环境的网络状态、实名状态跟随真实情况。
- 轮询频率不作为本方案的约束。
7. 差距报表
按套餐(设备套餐按设备合并)输出:
| 列 | 来源 |
|---|---|
| 卡 / 设备、套餐、生效与到期时间、真总量、虚总量 | 导入数据 |
| 导入时已用量 | 导入时刻生产套餐已用量(两边共同起点) |
| 测试环境新增扣减 | 测试环境套餐已用量 − 导入时已用量(建起点之后按新逻辑扣) |
| 导入前差距上限 | 本月运营商读数(重置日按通道配置换算)对生效后的上限,来自 flowcollector |
| 生产同期新增扣减 | 生产套餐已用量(同一时间点只读查询)− 导入时已用量 |
| 差额、是否已到停机线 | 计算 |
汇总:卡住卡数、总差额(GB)、按新逻辑已到停机线但生产未停的套餐数。
8. 清理
按 docs/测试环境生产卡只读模式清理顺序.md 执行:先处理测试环境里的生产卡 → 关开关并重新部署 → 新迁移删表 → 可选清理代码。导入的卡、设备、套餐与采集数据在第一步删除。
9. 已确认事项
已确认(2026-10-29):
- 导入全量:卡、设备、绑定,以及卡套餐与设备套餐(含开始、结束时间)。
- 套餐只保存真实已用量(导入时刻生产当前值),虚流量已用量不存储、由真实已用量 × 展示倍率现算。差距报表因此按"导入后测试环境新增扣减 vs 生产同期新增扣减"对比,两边起点一致。
- 卡和设备全部挂测试代理 9「测试采购部」。之前单独导入的两张卡(测试卡 12244、12245,目前未挂店铺)一并挂过去。
- 生产卡的 MSISDN、虚拟号等按原值导入,不脱敏。