修复一些问题,主要是生效套餐

scripts/legacy_device_export/README.md

@@ -0,0 +1,90 @@
+# 老系统设备迁移快照导出脚本
+
+这个工具只负责从老系统 `legacy_mysql` 导出设备迁移所需的业务快照，不写入新系统数据库，也不生成新系统导入 SQL。
+
+## 导出范围
+
+- 设备号/IMEI：从你提供的输入 CSV 读取；不提供 ICCID 时，脚本会按老库 `tbl_card.vcode`/`tbl_card.imei` 反查主卡，并通过 `tbl_card_relate` 展开关联副卡。
+- 卡当前快照：从 `tbl_card` 读取当前卡状态、老套餐字段、当前已用量等。
+- 套餐快照：从 `tbl_card_life` 和 `tbl_next_month_card_life` 读取当前/次月套餐事实。
+- 卡钱包快照：从 `tbl_card_wallet` 读取余额和自动续费字段。
+- 佣金账户快照：按卡所属老代理，从 `tbl_agent_commission_account` 读取账户累计金额。
+- 日流量记录：不导出，只保留当前已用量和剩余量建议值。
+
+## 输入 CSV
+
+脚本会自动识别常见表头。最省事的输入只需要设备号/IMEI，不需要提供 SN 和 ICCID。SN 只是随导出结果透传，可不填。
+
+支持的常见表头：
+
+```csv
+imei
+862639076004532
+```
+
+如果业务给的是设备号字段，也可以写成：
+
+```csv
+device_virtual_no
+862639076004532
+```
+
+如果业务后续能直接给 ICCID，脚本也仍然支持单卡或多卡槽 ICCID 输入。
+
+可识别字段包括：
+
+- 设备号：`device_virtual_no`、`device_no`、`virtual_no`、`mchno`、`设备号`、`设备虚拟号`、`机器码`
+- IMEI：`imei`、`device_imei`、`mchno`、`设备imei`、`机器码`
+- SN：`sn`、`设备sn`
+- 单卡：`iccid`、`卡号`、`主卡`、`main_iccid`
+- 多卡槽：`iccid1`、`iccid_1`、`slot1_iccid`、`card1`、`sim1`、`卡1`，最多识别到 4 个卡槽
+
+## 使用方式
+
+```bash
+export LEGACY_MYSQL_DSN='user:password@tcp(host:3306)/kyhl'
+
+go run ./scripts/legacy_device_export \
+  -input ./devices.csv \
+  -out ./legacy_device_export_output
+```
+
+也可以通过参数指定库名：
+
+```bash
+go run ./scripts/legacy_device_export \
+  -dsn 'user:password@tcp(host:3306)/kyhl' \
+  -schema kyhl \
+  -input ./devices.csv \
+  -out ./legacy_device_export_output
+```
+
+默认不会导出佣金明细。如需按输入 ICCID 额外导出 `tbl_agent_commission_detail` 明细，可加：
+
+```bash
+-include-commission-details
+```
+
+## 输出文件
+
+- `input_assets.csv`：标准化后的输入设备/卡关系。
+- `unresolved_inputs.csv`：无法通过输入 ICCID 或设备号/IMEI 解析出老库 ICCID 的行。
+- `card_snapshot.csv`：老卡本体快照和当前已用量，并给出 `tb_iot_card.data_usage_mb`、`current_month_usage_mb`、`last_gateway_reading_mb` 的导入建议值；状态/类型/运营商分类会同时输出中文 `*_name` 列，也会保留老卡 `expire_time`。
+- `package_usage_snapshot.csv`：老套餐快照，以及按当前已用量分摊出来的 `allocated_used_mb`、`remaining_mb` 建议值；老套餐状态、新系统建议状态会同时输出中文 `*_name` 列。时间字段同时输出老库原始 `start_at`/`expires_at` 和迁移参考 `effective_start_at`/`effective_expires_at`，具体来源看 `date_source_note`。
+- `wallet_snapshot.csv`：老卡钱包余额和自动续费信息，自动续费状态会同时输出中文 `*_name` 列。
+- `commission_account_snapshot.csv`：老代理佣金账户快照，预留 `suggested_new_shop_id` 供后续导入时映射新系统店铺。
+- `missing_cards.csv`：输入 ICCID 在老库 `tbl_card` 中未命中的清单。
+- `summary.txt`：本次导出摘要。
+- `field_dictionary.csv`：所有输出字段的中文说明。
+- `enum_dictionary.csv`：状态码、类型码、来源表等枚举值说明。
+- `README_zh.md`：随本次导出生成的阅读入口和口径提醒。
+- `commission_detail_snapshot.csv`：仅在传入 `-include-commission-details` 时生成。
+
+## 注意事项
+
+- `package_usage_snapshot.csv` 的已用量分摊是迁移建议值，后续生成新系统导入 SQL 前仍需要结合新系统套餐系列、套餐和供应商映射复核。
+- 输入 CSV 可以不提供 SN 和 ICCID；不提供 ICCID 时会先按老库 `tbl_card.vcode`，再兼容 `tbl_card.imei` 反查 ICCID，并通过 `tbl_card_relate` 展开关联卡。
+- CSV 表头保留英文是为了后续脚本稳定读取；人工查看时优先看同表的 `*_name` 中文列、`field_dictionary.csv` 和 `enum_dictionary.csv`。
+- 老库部分 `tbl_card_life.start_date` 为空，但 `expire_date` 和 `create_time` 有值；脚本会保留原始空值，并在 `effective_start_at` 用 `create_time` 兜底，避免误以为没有导出。
+- 新系统轮询流量会根据网关当前读数和 `last_gateway_reading_mb` 计算增量，后续导入脚本应优先使用 `card_snapshot.csv` 中的 `suggested_tb_iot_card_last_gateway_reading_mb` 避免首轮重复扣量。
+- 这个脚本不会修改老系统或新系统数据。