# 测试环境导入生产数据验证流量计量技术方案 | 项目 | 内容 | |---|---| | 日期 | 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 万级数据): 1. 从生产只读导出(dbhub / 只读连接),生成 CSV。 2. 写只读表:全部 ICCID 与设备 IMEI。 3. 确认开关已部署(以 Gitea Actions 部署成功为准)且只读表行数与导出一致。 4. 按通道映射写卡、资产标识、设备、绑定、套餐;同 ICCID / IMEI 已存在则跳过并记录。 5. 全部导入的卡置"待建起点"(`traffic_baseline_pending = true`)。 6. 触发轮询重新加载(重启 Worker 或调用轮询初始化),使导入的卡进入调度。 导入脚本放在 `cmd/zz_tmp_*`,不提交;只允许连接 `junhong_cmp_test`。 ### 5.3 建起点 每张卡在测试环境第一次通过队列写入时只建起点:把当时运营商读数对应的本月累计全部记为已结算,不扣费。之后按增量扣到导入的套餐上。因此测试环境算出的是"导入之后"的应扣,导入之前的差距由第 7 节用 flowcollector 读数补充。 ## 6. 轮询 - **完全按测试环境现有的轮询配置与代码逻辑运行**,不为导入的卡、设备单独配置,也不改业务流程:查卡状态、查实名、查流量、查套餐照常执行;流量照常进采集队列、写日快照、建起点、按增量扣套餐;套餐照常激活、到期、重置;停复机判断照常执行并记录。 - 唯一不同:导入资产的网关调用只放行查询类(查卡状态、查实名、查流量、查设备信息、查设备槽位、同步设备状态),停机、复机等其他调用在网关出口拦截(第 4 节)。被拦截的停复机记为失败并按退避重试,本地卡状态不变;这些失败记录是预期的,也正好说明"按新逻辑该停/该复"的卡有哪些。 - 查卡状态、查实名放行后,测试环境的网络状态、实名状态跟随真实情况。 - 轮询频率不作为本方案的约束。 ## 7. 差距报表 按套餐(设备套餐按设备合并)输出: | 列 | 来源 | |---|---| | 卡 / 设备、套餐、生效与到期时间、真总量、虚总量 | 导入数据 | | 导入时已用量 | 导入时刻生产套餐已用量(两边共同起点) | | 测试环境新增扣减 | 测试环境套餐已用量 − 导入时已用量(建起点之后按新逻辑扣) | | 导入前差距上限 | 本月运营商读数(重置日按通道配置换算)对生效后的上限,来自 flowcollector | | 生产同期新增扣减 | 生产套餐已用量(同一时间点只读查询)− 导入时已用量 | | 差额、是否已到停机线 | 计算 | 汇总:卡住卡数、总差额(GB)、按新逻辑已到停机线但生产未停的套餐数。 ## 8. 清理 按 `docs/测试环境生产卡只读模式清理顺序.md` 执行:先处理测试环境里的生产卡 → 关开关并重新部署 → 新迁移删表 → 可选清理代码。导入的卡、设备、套餐与采集数据在第一步删除。 ## 9. 已确认事项 已确认(2026-10-29): 1. 导入全量:卡、设备、绑定,以及卡套餐与设备套餐(含开始、结束时间)。 2. 套餐只保存真实已用量(导入时刻生产当前值),虚流量已用量不存储、由真实已用量 × 展示倍率现算。差距报表因此按"导入后测试环境新增扣减 vs 生产同期新增扣减"对比,两边起点一致。 3. 卡和设备全部挂测试代理 9「测试采购部」。之前单独导入的两张卡(测试卡 12244、12245,目前未挂店铺)一并挂过去。 4. 生产卡的 MSISDN、虚拟号等按原值导入,不脱敏。