Files
junhong_cmp_fiber/docs/测试环境导入生产数据验证流量计量技术方案.md
邹进 5cf67b98de
All checks were successful
构建并部署到测试环境(无 SSH) / build-and-deploy (push) Successful in 9m36s
feat: 网关只读资产改为数据表,只读资产只允许查询类调用
- 新增 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>
2026-10-29 17:55:52 +09:00

151 lines
9.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 测试环境导入生产数据验证流量计量技术方案
| 项目 | 内容 |
|---|---|
| 日期 | 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、虚拟号等按原值导入,不脱敏。