junhong_cmp_fiber/scripts/legacy_device_export

老系统设备迁移快照导出脚本

这个工具只负责从老系统 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 只是随导出结果透传，可不填。

支持的常见表头：

imei
862639076004532

如果业务给的是设备号字段，也可以写成：

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 个卡槽

使用方式

export LEGACY_MYSQL_DSN='user:password@tcp(host:3306)/kyhl'

go run ./scripts/legacy_device_export \
  -input ./devices.csv \
  -out ./legacy_device_export_output

也可以通过参数指定库名：

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 明细，可加：

-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 避免首轮重复扣量。
• 这个脚本不会修改老系统或新系统数据。