junhong_cmp_fiber/scripts/migration/resources/README.md

业务方资料投放目录

业务方按以下规则把数据放到本目录,重命名去掉 .example 后缀,即可被脚本读取。

设计原则:业务方只填"是哪张卡"和"在哪台设备上",归属、运营商、套餐等元数据全部由 脚本从奇成自动获取,通过 config/mapping.yaml 决定如何落到新系统。

cards.csv 卡资产清单

每张要迁移的卡一行。iccid_19 / iccid_20 至少填一个。只有 20 位完整 ICCID 时可只填 iccid_20,脚本会自动派生前 19 位写入 iccid_19 字段。 只填 iccid_20 的卡,脚本查询奇成主表时只按 20 位精确匹配;只有同时显式填写 iccid_19 和 iccid_20 时,才允许 20 位未命中后退回 19 位查询。

列名	必填	说明
iccid_19	条件必填	ICCID 前 19 位(必须 19 位;允许奇成历史字母位)。iccid_20 已填时可留空
iccid_20	视运营商	完整 20 位 ICCID;CMCC/CUCC/CBN(20 位运营商) 必填,CTCC(19 位)必须留空;非空时前 19 位必须等于 iccid_19
is_industry	否	是否行业卡,留空 = false(普通卡)

具体运营商从奇成 tbl_card.account_id/account_name 扫描后写入 mapping.yaml.carriers; tbl_card.category 只是奇成大类,仅辅助人工填写 target_carrier_type。填完映射后会做一致性校验:

• CTCC 卡填了 iccid_20 → errors.csv: carrier_length_conflict 阻断
• 非 CTCC 卡 iccid_20 留空 → 同上阻断
• 同一完整 ICCID 在奇成 tbl_card 命中多条记录 → errors.csv: legacy_duplicate 阻断,请业务方人工确认

店铺归属不在 CSV 里填,由 mapping.yaml.agents[].target_shop_code 通过奇成 tbl_card.agent_id 自动推导。如果该卡在奇成没有 agent_id 或代理映射未填 shop_code, 卡进平台库存。

devices.csv 设备资产清单

每台要迁移的设备一行。

列名	必填	说明
imei	否	设备 IMEI(非蜂窝设备可留空)
virtual_no	否	设备虚拟号/设备号。留空时用 imei 兜底;两者都为空则该行报错
device_name	否	设备名称,写入 tb_device.device_name
device_model	否	设备型号,写入 tb_device.device_model
device_type	否	设备类型,写入 tb_device.device_type
max_sim_slots	否	最大卡槽数,范围 1-4。不填时按非空 sim_iccid_* 的最大槽位推导
sim_iccid_1 ~ sim_iccid_4	否	各插槽 ICCID,引用 cards.csv 的卡。可填 19 或 20 位;20 位精确匹配完整 ICCID,19 位仅在该前缀唯一对应一张卡时允许(至少要有 1 个)

店铺归属规则:用 sim_iccid_1(主卡)的 agent_id 走 mapping.agents 推导,与卡归属同口径。

其他字段自动取默认值:manufacturer 留空,max_sim_slots 按已填写卡槽推导, current_slot=1(以 sim_iccid_1 为当前生效卡)。

一致性约束

• devices.csv 任何 sim_iccid_* 引用的 ICCID 必须在 cards.csv 中存在
• 同一 ICCID 不允许在 cards.csv 中重复出现
• 19 位前缀对应多张 20 位卡时,devices.csv 必须填写完整 20 位 ICCID
• imei 和 virtual_no 至少要有一个(用作设备唯一标识)
• 同一 ICCID 不能同时被多个设备/插槽引用