update

scripts/migration/README.md

@@ -154,6 +154,8 @@ python3 migrate_assets.py   # → output/step1_*.sql + ownership_resolution.csv
 python3 migrate_runtime.py  # → output/step2_*.sql + package_resolution.csv + errors.csv + warnings.csv
 ```
 
+修改迁移脚本或 `mapping.yaml` 后，必须重新生成并审核对应的 `output/step*.sql`；不得执行修改前生成的旧 SQL 文件。
+
 执行 SQL 前必须先审核:
 
 - `ownership_resolution.csv`:核对每个设备/独立卡的目标店铺、决策来源、当前槽位和旧套餐读取槽位
@@ -391,3 +393,62 @@ real_used_mb = total_bytes_cnt / (1 + flow_add_discount / 100)
 | `warnings.csv` 出现 `usage_without_active_package` | 该卡奇成 `total_bytes_cnt > 0` 但 `tbl_card_life` 中没有 status=1 且 type!=1 的当前生效正式套餐,无法精确反算真用量(按真=虚处理),详见 §6.3 |
 | 线上报 `null value in column "creator"` | `migration_user_id` 是 0,某些约束可能拒绝;改成真实管理员 ID |
 | 线上报目标店铺不存在 | `ownership_rules` 或 `overrides` 的 shop_code 在新库不存在,先建店铺或修正配置 |
+
+## 9. 店铺批量导入
+
+店铺导入仅生成 SQL 和审核产物，**不连接、不写入**目标 PostgreSQL。实际 YAML、CSV、SQL 和输出文件均受 `.gitignore` 保护。
+
+### 9.1 准备本地配置
+
+```bash
+pip install -r requirements.txt
+cp config/shop_bulk_import.yaml.example config/shop_bulk_import.yaml
+```
+
+填写 `shop_bulk_import.yaml`：
+
+- `batch_id`：本次导入的唯一批次标识；同一批审核产物和 SQL 使用该标识。
+- `shop_code_prefix`：店铺编号前缀，生成格式为 `<prefix>-<四位 CSV 数据行序号>`。
+- `default_role_id`：目标库中启用的客户角色 ID。
+- `operator_id`：目标库中启用的超级管理员账号 ID，写入 creator/updater 和审计操作者。
+- `initial_password_rule`：固定为 `adm@{phone_last4}`。
+- `salesperson_account_ids`：CSV“业务员”名称到启用平台账号 ID 的完整映射。
+
+本地配置不得包含数据库 DSN、密码或其他凭据。
+
+### 9.2 生成和审核 SQL
+
+```bash
+# 从项目根目录运行；相对路径按当前工作目录解析。
+python3 scripts/migration/import_shops.py \
+  --csv 'scripts/migration/副本代理商信息汇总表(3).csv' \
+  --config scripts/migration/config/shop_bulk_import.yaml \
+  --output-dir scripts/migration/output
+```
+
+生成器校验 CSV 必备列、必填值、手机号、同批唯一性、父代理唯一解析和稳定店铺编号。成功时输出同一批次标识的：
+
+- `shop_bulk_import_<batch>.sql`：受控 SQL，包含 bcrypt 密码哈希；只保存在受控本地目录，不得提交或复制到日志、文档。
+- `shop_bulk_import_<batch>_results.csv`：源 CSV 行号、店铺编号、层级、上级解析和业务员映射。
+- `shop_bulk_import_<batch>_errors.csv`：输入或映射错误；非空时不得执行 SQL。
+- `shop_bulk_import_<batch>_summary.txt`：输入、计划、父子关系和错误数量。
+
+审核时至少核对计划数、8 条父子关系、每条店铺编号和业务员归属。结果、错误、摘要和控制台输出不包含初始密码明文。
+
+### 9.3 在隔离环境执行
+
+由维护者在明确指定的隔离 PostgreSQL 环境执行，`-1` 和 `ON_ERROR_STOP` 缺一不可：
+
+```bash
+psql -h <HOST> -U <USER> -d <DATABASE> \
+  -1 -v ON_ERROR_STOP=1 \
+  -f output/shop_bulk_import_<batch>.sql
+```
+
+SQL 的开头会先校验默认客户角色、迁移超级管理员、业务员平台账号，以及店铺编号、用户名、手机号冲突；校验或任一写入失败时，`psql -1` 回滚整批。成功后维护者应核对店铺、主账号、账号角色、店铺角色、每店两条钱包、`shop.create` 和 `shop.update_business_owner` 审计事件数量。
+
+### 9.4 生产人工执行与回退
+
+生产执行仅由维护者在完成隔离验证和审核后手工进行；Agent 不连接生产主机、不执行生产 SQL。执行前保存同批 CSV、配置、结果、错误、摘要和 SQL 的受控副本。
+
+执行失败会由单事务自动回滚。执行成功后的回退不由工具自动处理；维护者必须根据审核产物确定受影响店铺后，另行审核删除或禁用方案，禁止将同一 SQL 作为“回退”重复执行。