# 商机更新对接接口

## 接口信息

- 请求方式：`PUT`
- 请求路径：`/api/opportunities/integration/update`
- 请求头：
  - `Content-Type: application/json`
  - `X-Internal-Secret: <内部接口密钥>`

## 接口说明

- 通过 `opportunityCode` 定位商机
- 按传入字段做部分更新，未传字段不修改
- 不支持更新商机的最终客户

## 请求参数

### 必填

| 字段                | 类型     | 说明   |
| ----------------- | ------ | ---- |
| `opportunityCode` | string | 商机编号 |

### 可选

| 字段                   | 类型      | 说明                                     |
| -------------------- | ------- | -------------------------------------- |
| `opportunityName`    | string  | 商机名称                                   |
| `projectLocation`    | string  | 项目地                                    |
| `operatorName`       | string  | 运作方                                    |
| `amount`             | number  | 商机金额，必须大于 0                            |
| `expectedCloseDate`  | string  | 预计结单日期，格式 `YYYY-MM-DD`                 |
| `confidencePct`      | string  | 把握度，建议传 `A`、`B`、`C`                    |
| `stage`              | string  | 项目阶段，建议传 CRM 当前字典码值                    |
| `opportunityType`    | string  | 建设类型                                   |
| `productType`        | string  | 产品类型                                   |
| `source`             | string  | 商机来源                                   |
| `salesExpansionId`   | number  | 销售拓展 ID，必须大于 0                         |
| `channelExpansionId` | number  | 渠道拓展 ID，必须大于 0                         |
| `preSalesId`         | number  | 售前 ID，必须大于 0                           |
| `preSalesName`       | string  | 售前姓名                                   |
| `competitorName`     | string  | 竞品名称                                   |
| `archived`           | boolean | 是否归档                                   |
| `pushedToOms`        | boolean | 是否已推送 OMS                              |
| `omsPushTime`        | string  | 推送 OMS 时间，建议 ISO 8601 格式               |
| `status`             | string  | 商机状态，支持 `active`、`closed`、`won`、`lost` |
| `description`        | string  | 备注                                     |

## 关键规则

- 除 `opportunityCode` 外，至少还要传一个更新字段

## 请求示例

```json
{
  "opportunityCode": "OPP-20260401-001",
  "stage": "won",
  "status": "won",
  "confidencePct": "A",
  "amount": 2800000,
  "expectedCloseDate": "2026-04-30",
  "description": "外部系统回写成交结果"
}
```

## 返回示例

### 成功

```json
{
  "code": "0",
  "msg": "success",
  "data": 123
}
```

### 失败

```json
{
  "code": "-1",
  "msg": "商机不存在",
  "data": null
}
```

## 常见错误

- `内部接口鉴权失败`
- `商机不存在`
- `opportunityCode 不能为空`
- `至少传入一个需要更新的字段`
- `项目阶段无效: xxx`
- `项目把握度仅支持A、B、C`

## curl 示例

```bash
curl -X PUT 'http://localhost:8080/api/opportunities/integration/update' \
  -H 'Content-Type: application/json' \
  -H 'X-Internal-Secret: f0eb247f84db4e328fb27ce8ff6e7be96e73a53a7e9c4793395ad10d999e0d77' \
  -d '{
    "opportunityCode": "OPP-20260401-001",
    "stage": "won",
    "status": "won",
    "confidencePct": "A",
    "amount": 2800000,
    "expectedCloseDate": "2026-04-30",
    "description": "外部系统回写成交结果"
  }'
```