# CRM 线索转经销商 API 契约

## 基础信息

- **服务**: hzhub-system (8083)
- **API**: `POST /lead/convert`
- **Gateway路由**: `/crm/**` → StripPrefix=1 → `/lead/convert`

---

## 接口定义

### 线索转经销商

**API**: `POST /lead/convert`

**请求参数** (CrmLeadConvertBo):

```json
{
  "leadId": 1001,               // 必填，线索ID
  "dealerName": "XX贸易有限公司", // 必填，经销商名称
  "dealerCode": "DL20260001",   // 必填，经销商编码
  "customerCode": "C001",       // 可选，ERP客户编码
  "signedAt": "2026-05-20",     // 可选，签约时间
  "level": "C"                  // 可选，经销商等级（默认C）
}
```

**响应**: `R<Void>`

```json
{
  "code": 200,
  "msg": "转化成功"
}
```

---

## 业务逻辑

1. 查询线索信息（`crm_lead`）
2. 校验线索状态（必须不是"已转化"）
3. 创建经销商记录（`crm_dealer`）：
   - 从线索复制基础信息（companyName→dealerName, contactName, mobile, province, city）
   - 设置 sourceLeadId = leadId
   - 设置 ownerUserId = lead.ownerUserId
4. 迁移跟进记录（可选）：
   - 将 `crm_lead_follow` 数据复制到 `crm_dealer_follow`（如果有此表）
5. 创建初始商机（`crm_opportunity`）：
   - opportunityName = "初始商机"
   - dealerId = 新经销商ID
   - stage = "初步接触"
6. 更新线索状态：
   - leadStatus = "converted"
   - convertedDealerId = 新经销商ID
7. 返回成功消息

---

## 数据字典

### crm_dealer_level（经销商等级）

| 字典值 | 字典标签 |
|---|---|
| A | A级经销商 |
| B | B级经销商 |
| C | C级经销商 |

### crm_lifecycle（生命周期）

| 字典值 | 字典标签 |
|---|---|
| active | 活跃期 |
| stable | 稳定期 |
| decline | 衰退期 |
| churn | 流失期 |

---

## 前端类型定义

```typescript
export interface CrmLeadConvertBo {
  leadId: number;               // 必填
  dealerName: string;           // 必填
  dealerCode: string;           // 必填
  customerCode?: string;        // 可选
  signedAt?: string;            // 可选，格式 YYYY-MM-DD
  level?: string;               // 可选，默认 C
}
```

---

## 注意事项

1. **数据校验**: 线索ID必须存在且状态未转化
2. **唯一性**: dealerCode在同一租户内唯一
3. **事务性**: 整个转化过程使用事务（@Transactional）
4. **ERP关联**: 如果提供customerCode，在经销商详情中可查看ERP数据