junhong_cmp_fiber/docs/脚本/奇成数据迁移方案.md

奇成数据迁移方案

目标：把奇成（旧 MySQL kyhl 库）的存量卡和设备迁移到新系统（PostgreSQL），输出 SQL 脚本供线上手动执行。 范围：当前态资产 + 当前生效正式套餐 + 未生效待生效正式套餐 + 累计已用流量 + 代理佣金总值。不迁移历史明细、已过期套餐和加油包。

---

一、整体架构

                    业务方提供
                ┌──────────────────────┐
                │ resources/cards.csv  │
                │ resources/devices.csv│
                └──────────┬───────────┘
                           │
                我们维护唯一决策配置
                ┌──────────▼───────────┐
                │ config/mapping.yaml  │
                │ 归属/槽位/套餐映射    │
                └──────────┬───────────┘
                           │
                ┌──────────▼───────────┐
                │   脚本1：资产导入     │  ← 纯离线，不查奇成
                │   migrate_assets.py  │
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │ output/step1_*.sql   │  ← 手动在线上执行
                └──────────┬───────────┘
                           │ (执行完，新库已有这些 iccid)
                           │
                ┌──────────▼───────────┐
                │  脚本2：关联数据导入  │  ← 直连奇成只读查询
                │  migrate_runtime.py  │  ← 直连新库测试环境拿 id
                └──────────┬───────────┘
                           │
                           ▼
                ┌──────────────────────┐
                │ output/step2_*.sql   │  ← 手动在线上执行
                └──────────────────────┘

关键约束

• 两个脚本都不直接写入线上库，只生成 .sql 文件和审核 CSV
• config/mapping.yaml 是归属、设备当前槽位、套餐来源槽位和套餐迁移范围的决策源；奇成只提供历史事实
• 脚本对奇成线上库只 SELECT，DB 连接层强制只读事务（SET TRANSACTION READ ONLY）
• 所有 INSERT 使用 ON CONFLICT DO NOTHING，支持重跑
• errors.csv 非空时不执行 SQL，先修正配置/输入后重跑

---

二、业务方提供的资产清单

2.1 resources/cards.csv 卡资产清单

每张要迁移的卡一行（包含独立卡和设备上的卡）。

列名	必填	说明	示例
iccid	是	ICCID。19 位或 20 位，业务方按奇成原值给（脚本根据 carrier_name 反查 carrier_type 判断长度规则）	89852000263338772439
msisdn	否	手机号 / 接入号（奇成 tbl_card.phone）	454006333877243
carrier_name	是	奇成的运营商名称，必须在 config/carrier.yaml 中能匹配到	移动全国卡
package_name	否	当前生效套餐名（奇成 tbl_card_life.meal_name）。留空表示无套餐	Y星网专享年卡套餐每月300M（12个月）
package_expires_at	否	当前套餐到期时间（奇成 tbl_card_life.expire_date），格式 YYYY-MM-DD HH:MM:SS。无套餐留空	2027-04-28 16:00:00
is_industry	是	是否行业卡。true/false	false
virtual_no	否	卡虚拟号（奇成 tbl_virtual_number.vcode），无则留空	8960066754
target_shop_code	否	目标店铺编码（tb_shop.shop_code）。留空 = 进平台库存；若该卡在设备上则强制留空（跟随设备）	SHOP20260428103424CZZQ

2.2 resources/devices.csv 设备资产清单

每台要迁移的设备一行。

列名	必填	说明	示例
imei	否	设备 IMEI（非蜂窝设备可留空）	860000000000001
virtual_no	是	设备虚拟号/别名（业务方自定义，全局唯一）	DEV-202604-0001
device_name	否	设备名称	张三家充电宝
device_model	否	设备型号	CB-PRO-V2
manufacturer	否	制造商	深圳XX
max_sim_slots	否	插槽数，默认 4	4
sim_iccid_1	否	插槽1的 iccid，必须在 cards.csv 中存在	89852000...
sim_iccid_2	否	插槽2的 iccid	89860623...
sim_iccid_3	否	插槽3的 iccid
sim_iccid_4	否	插槽4的 iccid
current_slot	否	当前使用的插槽位置（1-4），用于 tb_device_sim_binding.is_current。空值按 mapping.yaml 批量规则或覆盖项填充	2
package_source_slot	否	设备套餐来源槽位（1-4）。只迁该槽位卡的奇成正式套餐为设备套餐	2

注意

• cards.csv 必须先到位，devices.csv 的 sim_iccid_* 才能被校验
• 业务方分别准备这两份是合理的，奇成 tbl_card_relate（主卡+副卡1+副卡2）的关系业务方应已掌握
• 槽位解析优先级：devices.csv 行级配置 > mapping.yaml.overrides.devices > mapping.yaml.ownership_rules.device 批量默认值
• current_slot 或 package_source_slot 对应槽位无卡时写入 errors.csv 并阻断该设备相关 SQL

---

三、ICCID 19/20 位的处理规则（关键）

新系统设计：tb_iot_card.iccid_19 和 iccid_20 两个字段。

运营商类型	标准 ICCID 长度	iccid_19	iccid_20
CTCC（电信）	19 位	= iccid 全值	NULL
CMCC（移动）	20 位	= iccid 前 19 位	= iccid 全值
CUCC（联通）	20 位	= iccid 前 19 位	= iccid 全值
CBN（广电）	20 位	= iccid 前 19 位	= iccid 全值

脚本判定流程：

1. 读 carrier_name → 查 config/carrier.yaml 得到 carrier_type
2. 根据 carrier_type 决定标准长度（CTCC=19, 其他=20）
3. 校验 csv 中 iccid 实际长度：
   - 长度匹配 → 正常拆分
   - 长度=20 但 carrier_type=CTCC → 警告（电信卡居然是 20 位？写入 errors.csv 让业务方确认）
   - 长度=19 但 carrier_type≠CTCC → 警告（缺校验位？写入 errors.csv）
   - 长度 ∉ {19, 20} → 拒绝（奇成里有 18/21/22 位的脏数据，必须剔除）
4. 写 tb_iot_card 时同时填 iccid / iccid_19 / iccid_20

异常的 iccid 不进入 SQL 输出，统一写到 output/errors.csv，业务方人工修复后重跑。

---

四、我们维护的映射配置

迁移前必须在新系统建好店铺、运营商、套餐系列、套餐，然后填好 config/mapping.yaml。该文件是本次迁移的唯一决策源。

4.1 归属、槽位和套餐规则

ownership_rules:
  default_target_shop_code: KWTX
  device:
    mode: default_shop
    current_slot: 2
    package_source_slot: 2
  standalone_card:
    mode: default_shop

package_rules:
  migrate_statuses: [active, pending]

overrides:
  devices:
    - virtual_no: "862639073940258"
      target_shop_code: OTHER
      current_slot: 1
      package_source_slot: 1
  cards:
    - iccid: "89861590172420360956"
      target_shop_code: OTHER

归属规则：独立卡按 overrides.cards 或 ownership_rules.standalone_card 决定；设备按 overrides.devices 或 ownership_rules.device 决定；设备上的卡跟随设备。奇成 agent_id 不再作为默认归属来源。

4.2 config/mapping.yaml 中的 carriers

# 奇成的运营商名称（业务方在 cards.csv 中填的）→ 新系统 carrier_id + type
carriers:
  - legacy_name: "移动全国卡"
    target_carrier_id: 1580
    target_carrier_type: CMCC
    target_carrier_name: "移动15-BE20030985258"
  - legacy_name: "电信行业卡"
    target_carrier_id: 1583
    target_carrier_type: CTCC
    target_carrier_name: "电信10-qiangukeji"
  # ... 业务方提供的所有运营商都要列出

4.3 config/mapping.yaml 中的 series

# 奇成套餐系列名 → 新系统 series_id
# （根据业务方提供的 package_name，反查 tbl_set_meal → meal_series_id → tbl_set_meal_series.name）
series:
  - legacy_series_name: "SXKJ专享"
    target_series_id: 5
  - legacy_series_name: "移动全国卡月卡"
    target_series_id: 6

4.4 config/mapping.yaml 中的 packages

# 奇成套餐名 → 新系统 package_id（cards.csv 的 package_name 直接对照这里）
packages:
  - legacy_package_name: "Y星网专享年卡套餐每月300M（12个月）"
    target_package_id: 123
  - legacy_package_name: "移动全国卡100G（30天）"
    target_package_id: 124

注：奇成的 tbl_set_meal 套餐表非常大，不需要全部映射，只映射本次迁移涉及的套餐（脚本预扫描 cards.csv 收集 package_name 集合，缺失的列出来让我们补）。

4.5 店铺编码

# 如果业务方愿意填 shop_code，本文件可以省略
# 如果业务方只想填别名，这里维护 alias → shop_code 映射
aliases:
  shop_a: "SHOP20260428103424CZZQ"
  shop_b: "SHOP20260429150917OQKA"

---

五、脚本1：资产导入（migrate_assets.py）

5.1 输入

• resources/cards.csv
• resources/devices.csv
• config/*.yaml

5.2 处理流程

1. 加载所有 yaml 映射 → 构建 (legacy_name → target_id) 字典
2. 读 cards.csv：
   a. 行级校验：iccid 格式、carrier_name 是否在映射中、is_industry 合法
   b. 19/20 位拆分（见第三节）
   c. shop_code → shop_id（查新系统测试库 / 我们维护的映射）
   d. 异常行写 errors.csv
3. 读 devices.csv：
   a. 校验 sim_iccid_* 必须在 cards.csv 中存在
   b. 校验设备上的卡其 cards.csv.target_shop_code 必须为空
   c. virtual_no 重复性校验（同设备文件内 + 跨 cards.csv 的 virtual_no）
4. 生成 SQL（见 5.3）

5.3 输出文件

按表分块，便于逐表 review 和按需重跑：

output/
  step1_01_iot_cards.sql        # INSERT INTO tb_iot_card ...
  step1_02_devices.sql          # INSERT INTO tb_device ...
  step1_03_asset_identifiers.sql # INSERT INTO tb_asset_identifier ...
  step1_04_asset_wallets.sql    # INSERT INTO tb_asset_wallet ...
  step1_05_sim_bindings.sql     # INSERT INTO tb_device_sim_binding ...
  step1_06_shop_allocations.sql # INSERT INTO tb_asset_allocation_record（如有 shop_id）
  errors.csv                    # 异常行清单
  summary.txt                   # 统计：处理 X 张卡、Y 台设备、Z 条异常

5.4 SQL 生成规则

关于 ID 生成

新系统的 PK 是 bigint 自增。脚本生成 SQL 时使用 CTE 模式，让 PostgreSQL 自己分配 id：

-- 示例：插入一张卡，并用 RETURNING 拿到 id，立刻写关联表
WITH inserted_card AS (
  INSERT INTO tb_iot_card (
    iccid, iccid_19, iccid_20, carrier_id, carrier_type, carrier_name,
    card_category, batch_no, status, activation_status, real_name_status,
    network_status, stop_reason, realname_policy, is_standalone,
    msisdn, virtual_no, shop_id, creator, updater, created_at, updated_at
  ) VALUES (
    '89852000263338772439', '8985200026333877243', '89852000263338772439',
    1580, 'CMCC', '移动15-BE20030985258',
    'normal', 'MIGRATION-20260525', 1, 0, 0,
    0, '无套餐', 'after_order', true,
    '454006333877243', '8960066754', NULL, 0, 0, NOW(), NOW()
  )
  ON CONFLICT (iccid) WHERE deleted_at IS NULL DO NOTHING
  RETURNING id
)
-- 同步写 asset_identifier
, ins_ai_iccid AS (
  INSERT INTO tb_asset_identifier (identifier, asset_type, asset_id)
  SELECT '89852000263338772439', 'iot_card', id FROM inserted_card
  ON CONFLICT (identifier) DO NOTHING
)
, ins_ai_vno AS (
  INSERT INTO tb_asset_identifier (identifier, asset_type, asset_id)
  SELECT '8960066754', 'iot_card', id FROM inserted_card
  WHERE '8960066754' <> ''
  ON CONFLICT (identifier) DO NOTHING
)
-- 同步建钱包
INSERT INTO tb_asset_wallet (
  resource_type, resource_id, balance, frozen_balance,
  currency, status, version, shop_id_tag, created_at, updated_at
)
SELECT 'iot_card', id, 0, 0, 'CNY', 1, 0, COALESCE(0, 0), NOW(), NOW()
FROM inserted_card
ON CONFLICT (resource_type, resource_id) WHERE deleted_at IS NULL DO NOTHING;

每张卡一个 CTE 块，脚本生成几万个块。优势：原子性 + 幂等 + 不用预先分配 id 段。

关于设备-卡绑定

绑定 SQL 需要先拿到 device.id 和 card.id，用相同的 CTE 模式：

WITH d AS (
  SELECT id FROM tb_device WHERE virtual_no = 'DEV-202604-0001' LIMIT 1
), c1 AS (
  SELECT id FROM tb_iot_card WHERE iccid = '89852000263338772439' AND deleted_at IS NULL LIMIT 1
)
INSERT INTO tb_device_sim_binding (device_id, iot_card_id, slot_position, bind_status, is_current, bind_time, created_at, updated_at)
SELECT d.id, c1.id, 1, 1, true, NOW(), NOW(), NOW()
FROM d CROSS JOIN c1
ON CONFLICT (device_id, slot_position) WHERE bind_status = 1 AND deleted_at IS NULL DO NOTHING;
-- 触发器自动更新 tb_iot_card.is_standalone = false

关于分配记录（shop_id != NULL 的情况）

-- 在 iot_card 写入 shop_id 的同时，补一条分配记录
WITH c AS (
  SELECT id FROM tb_iot_card WHERE iccid = '...' AND deleted_at IS NULL
)
INSERT INTO tb_asset_allocation_record (
  allocation_no, allocation_type, asset_type, asset_id, asset_identifier,
  from_owner_type, to_owner_type, to_owner_id, operator_id, created_at
)
SELECT 'MIG-' || TO_CHAR(NOW(), 'YYYYMMDDHH24MISS') || '-' || c.id,
       'allocate', 'iot_card', c.id, '...',
       'platform', 'shop', <shop_id>, 0, NOW()
FROM c;

---

六、脚本2：关联数据导入（migrate_runtime.py）

6.1 前提

• 脚本1已经执行，新库已有这批 iccid 的卡
• 业务方已确认每张卡当前对应的套餐 ID（在脚本1阶段维护好 package_mapping.yaml）

6.2 输入

• resources/cards.csv（同脚本1）
• config/*.yaml（同脚本1，额外加 config/migration.yaml 配置 migration_user_id、伪订单前缀等）
• 奇成只读 DSN（连接配置）
• 新系统测试环境只读 DSN（仅用于拿 iccid → id 的映射，验证脚本逻辑；线上 id 在 step2 SQL 里用 SELECT 子查询动态取，不硬编码）

6.3 处理流程

1. 读 cards.csv 得到 iccid 列表
2. 连奇成（只读事务）批量查：
   - `tbl_card_life` 当前生效正式套餐和 `tbl_next_month_card_life` 次月待生效套餐，保留 legacy 套餐 ID、套餐名、类型、状态、开始时间、到期时间和稳定排序键
   - `tbl_card.total_bytes_cnt` → 反算新系统真用量 MB
   - `tbl_agent_commission_account` / `tbl_agent` → 仅用于代理钱包初始化
3. 对每个独立卡或设备套餐来源槽位：
   a. 套餐映射：`legacy_meal_id` → `target_package_id`（来自 `mapping.yaml.packages`）
   b. active 套餐写 `tb_package_usage.status=1`，pending 套餐写 `status=0` 并按稳定顺序写 `priority`
   c. 生成伪订单 SQL（order_no = `MIG-<ICCID>-<priority>`）
   d. 生成 `tb_package_usage` SQL（关联伪订单 + 计算 snapshot 字段）
   e. 生成 `UPDATE tb_iot_card SET data_usage_mb = ...`（真用量 MB）
4. 对每个 shop（按代理映射出来的）：
   a. 生成 INSERT/UPDATE tb_agent_wallet（总值）
   b. 生成一条 tb_agent_wallet_transaction（type=initial_migration, amount=总值, remark=源奇成代理ID）
5. 输出 SQL

6.4 输出文件

output/
  step2_01_migration_orders.sql       # 伪订单
  step2_02_package_usages.sql         # 套餐使用记录
  step2_03_card_data_usage_update.sql # 卡累计流量 UPDATE
  step2_04_agent_wallet_init.sql      # 代理钱包总值
  step2_05_agent_wallet_transactions.sql # 迁移流水
  step2_06_asset_series_update.sql     # 资产套餐系列回填
  package_resolution.csv               # 套餐迁移审核文件
  errors.csv                           # 套餐映射缺失、多 active、槽位缺失等阻断错误
  warnings.csv                         # 用量反算和代理钱包警告
  summary.txt

6.5 伪订单 + 套餐使用记录的 SQL 形态

-- 伪订单（一条 SQL 同时插订单和 package_usage）
WITH new_order AS (
  INSERT INTO tb_order (
    order_no, order_type, buyer_type, buyer_id, iot_card_id,
    total_amount, payment_method, payment_status, paid_at,
    source, generation, creator, updater, created_at, updated_at
  )
  SELECT 'MIG-89852000263338772439-1',
         'single_card', 'personal', 0, c.id,
         0, 'offline', 2, NOW(),
         'migration', 1, 0, 0, NOW(), NOW()
  FROM tb_iot_card c WHERE c.iccid = '89852000263338772439' AND c.deleted_at IS NULL
  ON CONFLICT (order_no) DO NOTHING
  RETURNING id, order_no, iot_card_id
)
INSERT INTO tb_package_usage (
  order_id, order_no, package_id, usage_type, iot_card_id,
  data_limit_mb, virtual_total_mb_snapshot, display_gain_ratio_snapshot,
  enable_virtual_data_snapshot, status, priority,
  activated_at, expires_at,
  package_name, package_price_config_status, package_is_gift,
  data_reset_cycle, next_reset_at, generation,
  creator, updater, created_at, updated_at
)
SELECT no.id, no.order_no, p.id, 'single_card', no.iot_card_id,
       p.real_data_mb,
       CASE WHEN p.enable_virtual_data THEN p.virtual_data_mb ELSE p.real_data_mb END,
       p.virtual_ratio, p.enable_virtual_data,
       1, 1,
       NULL,                       -- activated_at 奇成多数为 NULL
       '2027-04-28 16:00:00'::timestamp,  -- 从奇成 tbl_card_life.expire_date 拿
       p.package_name, p.price_config_status, p.is_gift,
       p.data_reset_cycle, NULL,
       1, 0, 0, NOW(), NOW()
FROM new_order no
JOIN tb_package p ON p.id = 123 AND p.deleted_at IS NULL  -- package_id 来自映射
ON CONFLICT DO NOTHING;

---

七、运行流程

7.1 准备阶段（在我们的开发/测试机上）

# 1. 业务方提供
cp 业务方发的*.csv  scripts/migration/resources/

# 2. 我们/业务方在新系统线上建好店铺/运营商/套餐系列/套餐
#    （另行手动完成，本脚本不负责）

# 3. 我们维护映射 yaml
vim scripts/migration/config/*.yaml

# 4. 跑脚本1（离线，只读 csv + yaml）
cd scripts/migration
python migrate_assets.py
# 看 output/errors.csv，找业务方修复后重跑

# 5. 拿 step1 SQL 在测试环境跑一遍，确认无报错
psql -h 测试库 -f output/step1_01_iot_cards.sql
psql -h 测试库 -f output/step1_02_devices.sql
... (按编号顺序)

# 6. 跑脚本2（直连奇成 + 测试环境读 id）
python migrate_runtime.py
# 测试环境跑一遍 step2 SQL，验证最终态

# 7. 验证 OK，把所有 .sql 文件交给运维

7.2 线上执行（用户手动）

按编号顺序执行：

# 第一波：资产
psql -h 线上库 -1 -f step1_01_iot_cards.sql
psql -h 线上库 -1 -f step1_02_devices.sql
psql -h 线上库 -1 -f step1_03_asset_identifiers.sql
psql -h 线上库 -1 -f step1_04_asset_wallets.sql
psql -h 线上库 -1 -f step1_05_sim_bindings.sql
psql -h 线上库 -1 -f step1_06_shop_allocations.sql

# 第二波：关联数据
psql -h 线上库 -1 -f step2_01_migration_orders.sql
psql -h 线上库 -1 -f step2_02_package_usages.sql
psql -h 线上库 -1 -f step2_03_card_data_usage_update.sql
psql -h 线上库 -1 -f step2_04_agent_wallet_init.sql
psql -h 线上库 -1 -f step2_05_agent_wallet_transactions.sql

-1 单事务执行，失败自动回滚整文件。

---

八、目录结构（最终交付）

scripts/migration/
  README.md                   # 操作手册
  requirements.txt            # python 依赖（pymysql, psycopg2, pyyaml, pandas）
  migrate_assets.py           # 脚本1
  migrate_runtime.py          # 脚本2
  lib/
    legacy_query.py           # 奇成只读查询封装
    csv_loader.py             # csv 读取与校验
    mapping_loader.py         # yaml 映射加载
    iccid_utils.py            # 19/20 位拆分（移植 pkg/utils/iccid.go）
    sql_builder.py            # SQL 生成（CTE 模板）
  resources/
    cards.csv                 # 业务方提供
    devices.csv               # 业务方提供
  config/
    carrier_mapping.yaml
    series_mapping.yaml
    package_mapping.yaml
    shop_mapping.yaml
    migration.yaml            # 全局配置（伪订单前缀、migration_user_id 等）
    legacy_dsn.yaml           # 奇成连接（.gitignore）
    main_test_dsn.yaml        # 新系统测试库连接（.gitignore）
  output/
    step1_*.sql
    step2_*.sql
    errors.csv
    warnings.csv
    summary.txt

---

九、风险与未决事项

#	风险	应对
1	业务方填的 carrier_name / package_name 与奇成不一致 → 映射失败	脚本预扫描，把所有未匹配项写到 unmatched.csv 让业务方修正
2	奇成的 iccid 有 18/21/22 位脏数据	脚本第三节规则剔除，进 errors.csv
3	同一 iccid 被业务方填多次	脚本去重 + 警告
4	设备 current_slot 或 package_source_slot 指向空槽位	写入 errors.csv，阻断该设备资产或套餐 SQL
5	同一资产存在多个 active 正式套餐	写入 errors.csv，阻断该资产套餐 SQL，人工裁决后修正
6	套餐 ID 映射不全	package_resolution.csv 记录，errors.csv 阻断对应套餐 SQL
7	tb_iot_card.is_standalone 由触发器维护	脚本写入时设 true，触发器会因为后续 binding 自动转 false
8	代理→shop 映射不明确	需要业务方提供 agent_id → shop_code 映射表，作为 config/agent_shop_mapping.yaml
9	线上库 sequence 与测试库不同	用 CTE + RETURNING 模式，不硬编码 id
10	重复执行	ON CONFLICT DO NOTHING 保证幂等

---

十、待决事项的最终答案

10.1 代理→店铺映射（业务方提供）

新增 config/agent_shop_mapping.yaml，由业务方维护：

# 奇成 agent_id → 新系统 shop_code 映射
mappings:
  - legacy_agent_id: "5846ACF63BD94ED2A26072BA5411B197"
    legacy_agent_name: "SX20250721101058"
    target_shop_code: "SHOP20260428103424CZZQ"
  # ...

脚本2 通过这份映射把奇成佣金归属到新系统的 shop_id 上。映射不全的奇成代理，其佣金进 warnings.csv 让业务方补全。

10.2 伪订单字段填法（全部复用现有常量，不动状态机）

tb_order.buyer_id 是 NOT NULL bigint，平台自营/赠送场景代码里就是填 0：

• internal/service/order/service.go:251（赠送场景）
• internal/service/order/service.go:271（平台自营）

迁移伪订单字段最终值：

字段	值	说明
order_no	MIG-<ICCID>-<priority>	前缀就是迁移数据的唯一识别标记
source	'admin'（复用现有）	不新增 migration 取值
buyer_type	'personal'	与 buyer_id=0 配对
buyer_id	0	与赠送/平台自营一致
payment_method	'offline'（复用现有 model/order.go:99）	已有常量，只是字符串快照，不触发状态机
payment_status	2（已支付）	避免被支付回调扫到
paid_at	NOW()	已支付时间
total_amount / actual_paid_amount	0	避免汇总统计错乱
commission_status	2（已完成）	避免被佣金调度器扫描
commission_result	2（无佣金）	不进入佣金链路
operator_account_type	'platform'	操作者为平台
operator_account_name	'数据迁移'	备注

识别迁移订单：WHERE order_no LIKE 'MIG-%'（不依赖 source 字段）

10.3 shop_id_tag：平台库存填 0，有店铺填 shop_id

tb_asset_wallet.shop_id_tag 是 NOT NULL bigint，代码里平台库存场景就是填 0：

• internal/service/exchange/service.go:297-300
• internal/service/client_order/service.go:723：shopTag := 0; if card.ShopID != nil { shopTag = *card.ShopID }

迁移直接套这个逻辑。同理 enterprise_id_tag 可空，统一填 NULL（迁移阶段没有企业归属）。

10.4 代理佣金字段映射

新系统 tb_agent_wallet 设计是双钱包：每个店铺有两条记录，wallet_type 区分：

• wallet_type='main'：主钱包（充值消费的钱）
• wallet_type='commission'：分佣钱包（佣金）

映射关系：

新系统字段	奇成字段	说明
main.balance	tbl_agent.balance_money × 100	充值余额（奇成是元，新系统是分）
commission.balance	tbl_agent_commission_account.can_draw_amount × 100	当前可提现佣金
commission.frozen_balance	tbl_agent_commission_account.applying_draw_amount × 100	申请中的佣金

total_commision_amount（累计总佣金）和 total_draw_amount（已提现累计）是历史明细汇总值，新系统的 tb_agent_wallet 没有对应字段；如果业务方需要这些历史数据展示，可以写到迁移流水的 metadata JSONB 里作为参考，但不影响余额计算。

每个 shop 生成 2 条 tb_agent_wallet（main + commission）+ 2 条 tb_agent_wallet_transaction，全部复用现有常量：

字段	值	说明
transaction_type	'recharge'（复用）	表示"初始化余额"
transaction_subtype	NULL	字段允许 NULL，原本为 deduct 细分预留
reference_type	'topup'（复用 pkg/constants/wallet.go:115）	与 recharge 配对
reference_id	NULL	不关联具体业务，避免误关联
amount	奇成余额 × 100（元→分）
balance_before	0	迁移前为 0
balance_after	同 amount
status	1（成功）
remark	"奇成数据迁移初始化，源 agent_id=<id>, agent_name=<name>"	文本识别
metadata	{"source":"qicheng","legacy_agent_id":"...","legacy_field":"can_draw_amount"}	JSON 结构化识别

识别迁移流水：WHERE remark LIKE '%奇成迁移%' OR metadata->>'source' = 'qicheng'

---

十一、不破坏状态机的总体策略

核心原则：本次迁移不新增任何常量，全部复用现有取值。识别迁移数据靠 order_no 前缀 + remark / metadata 字段，而不是污染枚举字段。

避免触发后续状态机的关键设置已散落在 10.2/10.4，汇总如下：

• 伪订单：payment_status=2(已支付) + commission_status=2(已完成) + commission_result=2(无佣金) → 不被支付回调、佣金调度器扫到
• 钱包流水：reference_id=NULL → 不与真实业务关联，不被对账任务扫到
• 金额：迁移订单 total_amount=0、actual_paid_amount=0 → 即使被汇总统计扫到也不污染收入数据

遗留风险：

• 后台订单列表若按 source='admin' 过滤，会看到迁移订单；建议提前做一个常用过滤条件（order_no NOT LIKE 'MIG-%'），或者前端订单列表加个"排除迁移数据"开关
• payment_method='offline' 在后台报表里会归类到"线下支付"统计中；如果运营对此敏感，需在报表 SQL 中加 order_no NOT LIKE 'MIG-%' 过滤

---

十二、实施顺序（审查通过后）

1. 业务方启动准备：明确 cards.csv / devices.csv / agent_shop_mapping.yaml 的格式，开始整理
2. 我们这边：
   • 写脚本1（migrate_assets.py + lib + 模板）
   • 在测试库验证脚本1
   • 写脚本2（migrate_runtime.py）
   • 在测试库验证脚本2
   • 写 README.md 操作手册（含"如何在报表中排除迁移数据"提示）
3. 业务方提供数据 → 全流程联调一次 → 交付给运维上线