更新一版

scripts/migration/resources/README.md

@@ -2,8 +2,13 @@
 
 业务方按以下规则把数据放到本目录,**重命名去掉 `.example` 后缀**,即可被脚本读取。
 
-> 设计原则:**业务方只填"是哪张卡"和"在哪台设备上",归属、运营商、套餐等元数据全部由
-> 脚本从奇成自动获取,通过 `config/mapping.yaml` 决定如何落到新系统。**
+> 设计原则:**业务方只填"是哪张卡"、"在哪台设备上"和少量行级槽位覆盖**。
+> 归属、批量默认槽位、套餐迁移范围由 `config/mapping.yaml` 决定;运营商、套餐、号码等历史事实从奇成只读查询。
+
+`cards.csv` 必填。`devices.csv` 可选:
+
+- 只有卡迁移:只放 `cards.csv`,不要放 `devices.csv`。
+- 卡 + 设备迁移:同时放 `cards.csv` 和 `devices.csv`,设备槽位引用的卡必须出现在 `cards.csv`。
 
 ## cards.csv 卡资产清单
 
@@ -24,13 +29,14 @@
 - 非 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,
-卡进平台库存。
+**店铺归属不在 CSV 里填**。独立卡由 `mapping.yaml.ownership_rules.standalone_card`
+和 `overrides.cards` 决定。多店铺批次使用 `standalone_card.mode: legacy_agent`,
+再按奇成 `agent_id` 填 `mapping.yaml.agents[].target_shop_code`。设备上的卡跟随设备归属,
+不单独生成分配记录。
 
-## devices.csv 设备资产清单
+## devices.csv 设备资产清单(可选)
 
-每台要迁移的设备一行。
+每台要迁移的设备一行。没有设备时不要创建这个文件,脚本会把所有卡按独立卡处理。
 
 | 列名 | 必填 | 说明 |
 |------|------|------|
@@ -41,12 +47,22 @@
 | `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 个) |
+| `current_slot` | 否 | 当前槽位,范围 1-4。写入 `tb_device_sim_binding.is_current`;空值用批量规则或覆盖项 |
+| `package_source_slot` | 否 | 设备旧套餐读取槽位,范围 1-4。新系统套餐仍归属设备;该字段只决定从奇成哪张绑定卡读取正式套餐生命周期 |
 
-**店铺归属规则**:用 `sim_iccid_1`(主卡)的 agent_id 走 `mapping.agents`
-推导,与卡归属同口径。
+**槽位优先级**:
+1. `devices.csv` 行级 `current_slot` / `package_source_slot`
+2. `mapping.yaml.overrides.devices` 中同设备号覆盖项
+3. `mapping.yaml.ownership_rules.device` 批量默认槽位
+
+若 `current_slot` 或 `package_source_slot` 对应的 `sim_iccid_N` 为空,脚本会写入
+`errors.csv` 并阻断该设备相关 SQL。非 `package_source_slot` 的设备绑定卡只生成
+基础卡和绑定 SQL,不会再读取它的奇成套餐,避免同一设备重复迁入多份主套餐。
 
 **其他字段自动取默认值**:`manufacturer` 留空,`max_sim_slots` 按已填写卡槽推导,
-`current_slot=1`(以 `sim_iccid_1` 为当前生效卡)。
+设备归属由 `mapping.yaml.ownership_rules.device` 和 `overrides.devices` 决定。设备使用
+`device.mode: legacy_agent` 时,脚本会按 `package_source_slot` 对应绑定卡的奇成 `agent_id`
+查 `mapping.yaml.agents[].target_shop_code`。
 
 ## 一致性约束