# 工作机 APP 通话录音上传对接说明

## 1. 前端对接流程（必读）

按下述时机调用，**`uuid` 与上传接口无关**；上传只返回录音 **`url`**。

| 时机 | 前端做什么 |
|------|----------|
| **开始拨号 / 开始录音** | 生成当次通话的 `uuid`（建议 32 位无连字符，去掉 `-`），本地保存，整通通话过程不变 |
| **拨号中** | 本地录音（APP 自实现） |
| **挂断后** | ① 调用 **上传接口** `POST /app/aiSipCall/uploadRecord`（`multipart` 字段 `file`），取返回的 `url` |
| **挂断后（紧接上步）** | ② 调用 **回调接口** `POST /app/aiSipCall/appCardCallBack`：`uuid` = 开始录音时生成的值；`recordPath` = 上传返回的 `url` |

```text
开始录音 → 生成 uuid（本地保存）
     ↓
挂断     → 上传录音 uploadRecord → 得 url
     ↓
回调     → appCardCallBack（带 uuid + recordPath=url + callTime 等）
```

**未接通 / 无录音**：可不调上传，回调时 `recordPath` 不传，`uuid` 仍应传（幂等）。

---

## 2. 服务与鉴权

| 项 | 说明 |
|------|------|
| 服务 | `fs-worker-app`，默认端口 **8008** |
| Header | `Authorization: Bearer {token}`（或兼容 `APPToken`） |
| SaaS | 建议同时传 `tenantCode`（与登录一致） |

---

## 3. 上传接口（挂断后调用）

```
POST http://{host}:8008/app/aiSipCall/uploadRecord
Content-Type: multipart/form-data
```

| 参数 | 必填 | 说明 |
|------|------|------|
| `file` | 是 | 录音文件 |

支持格式：`mp3`、`wav`、`m4a`、`aac`、`amr`、`wma`

成功响应：

```json
{
  "code": 200,
  "msg": "操作成功",
  "url": "https://your-obs-domain.com/worker-record/20260616/abc123.mp3"
}
```

将 `url` 原样作为回调的 `recordPath`。

---

## 4. 回调接口（上传后调用）

```
POST http://{host}:8008/app/aiSipCall/appCardCallBack
Content-Type: application/json
```

| 字段 | 必填 | 说明 |
|------|------|------|
| `uuid` | 建议 | **开始录音时已生成**，本次通话全程使用同一个 |
| `recordPath` | 否 | 上传接口返回的 `url` |
| `roboticId` / `calleeId` / `callModel` / `callTime` | 见业务 | 与现有回调一致 |

示例：

```json
{
  "roboticId": 294,
  "calleeId": 10001,
  "callModel": 4,
  "callTime": 120,
  "uuid": "a1b2c3d4e5f6789012345678abcdef01",
  "recordPath": "https://your-obs-domain.com/worker-record/20260616/abc123.mp3"
}
```

重复回调同一 `uuid` 时，服务端幂等返回「回调已处理」，视为成功。

---

## 5. 相关接口

| 接口 | 路径 |
|------|------|
| 登录 | `POST /worker/user/login` |
| 上传录音（挂断后） | `POST /app/aiSipCall/uploadRecord` |
| 通话回调（上传后） | `POST /app/aiSipCall/appCardCallBack` |
| 外呼前校验 | `POST /app/aiSipCall/validateAppCall` |
| WebSocket 任务推送 | 见 `docs/worker-ws-task-push.md` |