数据迁移脚本

scripts/migration/resources/README.md

@@ -0,0 +1,49 @@
+# 业务方资料投放目录
+
+业务方按以下规则把数据放到本目录,**重命名去掉 `.example` 后缀**,即可被脚本读取。
+
+> 设计原则:**业务方只填"是哪张卡"和"在哪台设备上",归属、运营商、套餐等元数据全部由
+> 脚本从奇成自动获取,通过 `config/mapping.yaml` 决定如何落到新系统。**
+
+## cards.csv 卡资产清单
+
+每张要迁移的卡一行。**必须同时提供 iccid_19 和 iccid_20**(因为奇成历史数据
+长度不可信,业务方提供两列作为权威值)。
+
+| 列名 | 必填 | 说明 |
+|------|------|------|
+| `iccid_19` | 是 | ICCID 前 19 位(所有卡都有,作为跨文件稳定 ID;必须 19 位纯数字) |
+| `iccid_20` | 视运营商 | 完整 20 位 ICCID;CMCC/CUCC/CBN(20 位运营商) **必填**,CTCC(19 位)**必须留空**;非空时前 19 位必须等于 `iccid_19` |
+| `is_industry` | 否 | 是否行业卡,留空 = `false`(普通卡) |
+
+运营商类型从奇成 `tbl_card.category` 自动推断,在查完奇成后会做一致性校验:
+- CTCC 卡填了 `iccid_20` → `errors.csv: carrier_length_conflict` 阻断
+- 非 CTCC 卡 `iccid_20` 留空 → 同上阻断
+- `iccid_19` 在奇成 `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` 兜底;两者都为空则该行报错 |
+| `sim_iccid_1` ~ `sim_iccid_4` | 否 | 各插槽 ICCID,引用 `cards.csv` 的卡。可填 19 或 20 位,内部统一按前 19 位回查 `cards.iccid_19`(至少要有 1 个) |
+
+**店铺归属规则**:用 `sim_iccid_1`(主卡)的 agent_id 走 `mapping.agents`
+推导,与卡归属同口径。
+
+**其他字段自动取默认值**:`device_name` / `device_model` / `manufacturer` 留空,
+`max_sim_slots=4`,`current_slot=1`(以 `sim_iccid_1` 为当前生效卡)。
+
+## 一致性约束
+
+- `devices.csv` 任何 `sim_iccid_*` 引用的 ICCID **必须**在 `cards.csv` 中存在
+- 同一 ICCID 不允许在 `cards.csv` 中重复出现
+- `imei` 和 `virtual_no` 至少要有一个(用作设备唯一标识)
+- 同一 ICCID 不能同时被多个设备/插槽引用