# Contract: IM 平台 extCreate（外部依赖）

**方向**: 平台后端 → IM 平台（出站调用）
**用途**: 为用户创建 IM 账号，获取 apiKey + userId

## 请求

```
POST {im.base-url}{im.create-path}
```

- 测试环境示例：`POST https://test-im.abtim-my.com/bot/extCreate`
- `create-path` 默认 `/bot/extCreate`

### 请求头

| Header | 值 | 来源 |
|--------|----|----|
| `extToken` | `92a88467-6eca-11f1-9dd5-00163e1eec55`（测试） | 配置 `im.ext-token` |

### 请求体（JSON）

```json
{ "nickName": "+88615287406952", "type": 0 }
```

- `nickName`：昵称，由后端取用户 `userName`，无则取 `phone`（哪个有值用哪个）。
- `type`：固定默认 `0`。
- Content-Type：`application/json`。

### 配置项（application.yml 新增段）

```yaml
# IM 即时沟通配置
im:
  base-url: https://test-im.abtim-my.com   # IM 平台根地址（正式环境另行配置）
  ext-token: 92a88467-6eca-11f1-9dd5-00163e1eec55   # 平台级鉴权令牌
  create-path: /bot/extCreate               # 创建用户接口路径
  timeout-ms: 5000                          # 连接/读取超时(毫秒)
```

## 响应

```json
{
  "code": 200,
  "message": "成功",
  "data": {
    "apiKey": "f7a49f9745114462a3333e5698aac9ae",
    "userId": 2069305587785445400
  }
}
```

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | 200 表示成功；非 200 视为失败 |
| `message` | String | 状态描述 |
| `data.apiKey` | String | IM API 密钥（落库 `im_api_key`，返回 APP） |
| `data.userId` | long | IM 用户ID（落库 `im_user_id`，转 String 返回 APP） |

## 处理规则

- **成功**：`code == 200` 且 `data.apiKey`、`data.userId` 均非空 → 取 data 落库并返回。
- **失败**：`code != 200`、data 缺字段、HTTP 非 2xx、超时、网络异常 → 抛异常，不写库，接口返回失败供 APP 重试。
- **幂等**：调用前先查本地 `info_user`，已有 `imApiKey` 则不调用本接口，直接返回。