1f634eb465
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 8m3s
44 lines
3.2 KiB
Markdown
44 lines
3.2 KiB
Markdown
## Why
|
||
|
||
当前奇成迁移脚本把奇成 `agent_id`、默认 `sim_iccid_1`、单一当前套餐查询结果当成迁移决策来源，导致批量设备店铺归属、设备主卡、套餐系列和套餐队列迁移不可控。随着单批上万到几万张卡迁移成为常态，脚本需要改为由 `mapping.yaml` 的批量规则驱动，奇成只提供历史事实，生成可审核的中间产物后再输出 SQL。
|
||
|
||
功能 ID：`feature-qicheng-migration-control`
|
||
|
||
## What Changes
|
||
|
||
- **重构迁移决策来源**：`mapping.yaml` 成为资产归属、设备当前槽位、套餐来源槽位、套餐迁移范围的唯一决策入口；奇成只用于读取运营商、套餐生命周期、流量和佣金等历史事实。
|
||
- **新增批量归属规则**：支持默认店铺、按设备/独立卡分支配置、按槽位配置和少量资产级覆盖，避免万级迁移逐卡配置。
|
||
- **拆分单卡迁移与设备迁移分支**：独立卡生成 `single_card` 套餐使用记录；设备绑定卡按设备维度生成 `device` 套餐使用记录，设备内卡不重复生成主套餐。
|
||
- **支持当前生效 + 未生效待生效套餐迁移**：完整读取奇成正式套餐生命周期，当前生效套餐写为 `status=1`，后续待生效套餐写为 `status=0` 并按优先级排队。
|
||
- **新增审核产物**：生成 `package_resolution.csv`、`ownership_resolution.csv` 和摘要文件，明确每个资产/套餐的决策、映射、跳过原因和缺失项。
|
||
- **增强阻断规则**：关键映射缺失、目标店铺不存在、目标套餐无效、设备主卡槽位缺失等必须进入错误清单并阻断对应资产，不再静默进入平台库存或漏写系列。
|
||
- **更新脚本文档**：同步更新 `scripts/migration/README.md`、`resources/README.md` 和奇成迁移方案文档，说明新配置模型、执行顺序和人工审核点。
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `qicheng-migration-control`：定义奇成迁移脚本的批量归属决策、设备/单卡分支、套餐队列迁移、审核产物和阻断规则。
|
||
|
||
### Modified Capabilities
|
||
|
||
无。
|
||
|
||
## Impact
|
||
|
||
**脚本与配置**：
|
||
- `scripts/migration/config/mapping.yaml.example`：新增批量归属、槽位、套餐迁移范围和覆盖配置示例。
|
||
- `scripts/migration/lib/mapping_loader.py`：加载并校验新的配置结构，保留旧配置兼容或提供明确升级错误。
|
||
- `scripts/migration/lib/csv_loader.py`：支持设备 `current_slot`、`package_source_slot` 或由批量规则填充默认槽位。
|
||
- `scripts/migration/lib/legacy_query.py`：新增读取完整正式套餐生命周期的查询。
|
||
- `scripts/migration/lib/sql_builder.py`：拆分单卡/设备套餐生成逻辑，生成审核 CSV 和阻断错误。
|
||
- `scripts/migration/scan_legacy.py`、`migrate_assets.py`、`migrate_runtime.py`：按新规则消费配置并输出 SQL。
|
||
|
||
**数据库与业务系统**：
|
||
- 不新增业务表，不修改 API，不引入外部依赖。
|
||
- 继续输出人工执行 SQL，保持只读访问奇成、幂等插入和线上手动执行模式。
|
||
|
||
**验证**：
|
||
- 不新增自动化测试或 `_test.go`。
|
||
- 通过样例 CSV、生成的 `errors.csv` / `warnings.csv` / 审核 CSV、SQL 内容核对和测试库手动 SQL 查询验证。
|