# P1-1b：CRM 产品

> **前置**：P1-1a 产品分类；P0 用户 mapping  
> **全局 ID**：[05-id-preservation-policy.md](../05-id-preservation-policy.md)  
> **下游**：客户/报价/合同等引用 `crm_product.id`

---

## 1. 目标

将 sx `crm_product` 写入门户 `crm_product`，并生成：

`docs/data-migration/mappings/crm_product_id_mapping.csv`

**数据来源**：仅从原 CRM（`sx.crm_product`）全量迁入 `del_flag=0` 行；**不**合并地磅 `cargos`、报销产品表。

---

## 2. 源数据规模（live sx，2026-07-12）

| 指标 | 值 |
|------|-----|
| 有效产品行 | 239 |
| 产品分类（已迁） | 5 |
| sx.sql 快照 INSERT | ~240（与 live 差 1 条删除/滞后） |

---

## 3. 执行前检查

```sql
-- 目标：应为空（首次执行）
SELECT COUNT(*) FROM crm_product WHERE tenant_no='shanxia2.0' AND del_flag=0;

-- 分类已就绪
SELECT COUNT(*) FROM crm_product_category WHERE del_flag=0;

-- 源
SELECT COUNT(*) FROM crm_product WHERE del_flag=0;
```

确认文件存在：

- `docs/data-migration/mappings/user_mapping_result.csv`
- `docs/data-migration/mappings/crm_product_category_id_mapping.csv`

---

## 4. 执行步骤

| 步骤 | 操作 | 状态 |
|------|------|------|
| 1 | 备份目标库 `mysqldump shanxia2.0` | 跳过（执行前 0 行） |
| 2 | `migrate_crm_product.py --dry-run` | ✅ 2026-07-12 |
| 3 | 审阅 dry-run（239 行、category_id 抽样） | ✅ |
| 4 | 正式执行 + `--mapping-out` | ✅ 插入 239 行 |
| 5 | SQL + 界面验收 | SQL ✅（脚本）；界面待人工 |
| 6 | 追加 `logs/` 批次记录 | ✅ `logs/2026-07-12-2055-product.md` |

### 4.1 命令

```bash
cd backend

venv/bin/python scripts/migrate_crm_product.py --dry-run \
  --env-file .env.production \
  --user-mapping ../docs/data-migration/mappings/user_mapping_result.csv

venv/bin/python scripts/migrate_crm_product.py \
  --env-file .env.production \
  --user-mapping ../docs/data-migration/mappings/user_mapping_result.csv \
  --mapping-out ../docs/data-migration/mappings/crm_product_id_mapping.csv
```

---

## 5. 字段映射速查

| 源 | 目标 | 说明 |
|----|------|------|
| id | id | **原样保留** `str(source_id)` |
| category_id | category_id | **原样保留** `str(source_id)` |
| product_no | product_no | 直接 |
| name | name | 直接 |
| cost | cost_price | 重命名 |
| status | status | 保持 `on`/`off` |
| is_toxic / is_explosive | 默认 0 | 源表无字段 |
| tenant_id | tenant_no | `shanxia2.0` |
| create_by | create_by | user_mapping；1→admin |

---

## 6. 验收标准

- [x] 目标有效行数 = 源有效行数（239）
- [x] mapping CSV 239 行，`source_id` = `new_id`
- [x] 抽样 `category_id` 落在已迁 5 个分类 id 内
- [ ] 产品列表页正常展示、分类全路径正确（待人工）

---

## 7. 与地磅的关系（说明）

地磅业务表（计划/出入库/地磅单）存的是**货物名称文本**，无 `cargo_id` / `product_id` 外键；门户 2.0 地磅方案 A 继续存名称文本，CRM 产品仅作下拉来源。详见迁移问答与 `docs/db-migration/00-migration-plan.md`。

---

## 8. 二次移植说明

1. 保留历史 `logs/` 与 mapping CSV，新批次只追加
2. 默认 skip 已映射 `source_id`；源数据变更用 `--update`
3. 勿 `--force` 清库；增量只迁 mapping 中不存在的源行