datai/datai-scenes/datai-scene-salesforce/docs/api-docs/2026-02-06-003-04-api.md

# API 文档：003-04 异步操作

## 元数据
- **需求编号**: 003-04
- **需求名称**: 异步操作
- **创建时间**: 2026-02-06
- **创建人**: AI Assistant
- **版本号**: v1.0.0
- **状态**: 已完成

---

## API 概述

本文档描述了 Metadata API 异步操作管理模块的 REST API 接口，提供异步操作状态查询、服务端同步轮询、异步操作取消、操作历史记录等功能。

### 基础信息
- **基础路径**: `/salesforce/metadata/async`
- **权限前缀**: `salesforce:metadata:async`
- **内容类型**: `application/json`

---

## 接口列表

### 1. 获取异步操作状态

**功能描述**: 查询指定异步操作的当前状态，立即返回当前状态信息。

**请求方式**: GET

**请求路径**: `/salesforce/metadata/async/status/{asyncId}`

**权限要求**: `salesforce:metadata:async:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 位置 | 说明 |
|--------|------|------|------|------|
| asyncId | String | 是 | Path | 异步操作 ID，Salesforce 返回的 ID，如 `0Afxx0000000001CAA` |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码，200 表示成功 |
| msg | String | 提示信息 |
| data | Object | 异步操作结果 |
| data.id | String | 异步操作 ID |
| data.done | Boolean | 操作是否完成 |
| data.message | String | 操作消息 |
| data.state | String | 操作状态，可选值：Queued、InProgress、Completed、Failed、Canceled |
| data.checkTime | String | 状态检查时间，ISO 8601 格式 |

#### 成功示例

**请求**:
```http
GET /salesforce/metadata/async/status/0Afxx0000000001CAA
```

**响应**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "done": true,
    "message": "部署成功",
    "state": "Completed",
    "checkTime": "2026-02-06T14:30:00"
  }
}
```

#### 失败示例

**请求**:
```http
GET /salesforce/metadata/async/status/invalid-id
```

**响应**:
```json
{
  "code": 500,
  "msg": "获取异步操作状态失败: 无效的异步操作 ID"
}
```

#### 使用场景
- 前端需要立即获取异步操作的当前状态
- 用户主动刷新状态
- 轮询前的初始状态查询

---

### 2. 同步轮询异步操作状态

**功能描述**: 服务端轮询直到异步操作完成（成功、失败或取消），最多轮询 60 次，每 5 秒一次，5 分钟超时。**注意：此接口会阻塞直到操作完成或超时。**

**请求方式**: GET

**请求路径**: `/salesforce/metadata/async/poll/{asyncId}`

**权限要求**: `salesforce:metadata:async:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 位置 | 默认值 | 说明 |
|--------|------|------|------|--------|------|
| asyncId | String | 是 | Path | - | 异步操作 ID |
| interval | Long | 否 | Query | 5000 | 轮询间隔（毫秒），最小 1000 |
| timeout | Long | 否 | Query | 300000 | 超时时间（毫秒），最大 600000 |

#### 响应参数

与"获取异步操作状态"接口相同。

#### 成功示例

**请求**:
```http
GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?interval=5000&timeout=300000
```

**响应**（操作完成）:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000000001CAA",
    "done": true,
    "message": "部署成功",
    "state": "Completed",
    "checkTime": "2026-02-06T14:35:00"
  }
}
```

#### 超时示例

**请求**:
```http
GET /salesforce/metadata/async/poll/0Afxx0000000001CAA?timeout=10000
```

**响应**:
```json
{
  "code": 500,
  "msg": "同步轮询异步操作状态失败: 异步操作轮询超时，已等待 10 秒"
}
```

#### 使用场景
- 前端需要等待异步操作完成后再进行下一步操作
- 部署操作后等待部署完成
- 需要确保操作完成后再返回给用户的场景

---

### 3. 取消异步操作

**功能描述**: 尝试取消指定的异步操作。**注意：已完成的操作无法取消。**

**请求方式**: POST

**请求路径**: `/salesforce/metadata/async/cancel/{asyncId}`

**权限要求**: `salesforce:metadata:async:cancel`

#### 请求参数

| 参数名 | 类型 | 必填 | 位置 | 说明 |
|--------|------|------|------|------|
| asyncId | String | 是 | Path | 异步操作 ID |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码，200 表示成功 |
| msg | String | 提示信息 |
| data | Object | 取消结果 |
| data.asyncId | String | 异步操作 ID |
| data.success | Boolean | 是否成功取消 |
| data.cancelTime | String | 取消操作时间，ISO 8601 格式 |
| data.message | String | 消息说明 |

#### 成功示例

**请求**:
```http
POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA
```

**响应**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "asyncId": "0Afxx0000000001CAA",
    "success": true,
    "cancelTime": "2026-02-06T14:30:00",
    "message": "异步操作已成功取消"
  }
}
```

#### 失败示例

**请求**:
```http
POST /salesforce/metadata/async/cancel/0Afxx0000000001CAA
```

**响应**（操作已完成）:
```json
{
  "code": 500,
  "msg": "取消异步操作失败: 操作可能已完成或无法取消"
}
```

#### 使用场景
- 用户需要取消正在进行的部署操作
- 发现操作配置错误，需要立即停止
- 系统需要自动取消超时的操作

---

### 4. 获取异步操作历史

**功能描述**: 查询最近的异步操作历史记录。

**请求方式**: GET

**请求路径**: `/salesforce/metadata/async/history`

**权限要求**: `salesforce:metadata:async:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 位置 | 默认值 | 说明 |
|--------|------|------|------|--------|------|
| limit | Integer | 否 | Query | 10 | 返回数量限制，最大 100 |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码，200 表示成功 |
| msg | String | 提示信息 |
| data | Array | 异步操作历史列表 |
| data[].id | Long | 记录 ID |
| data[].asyncId | String | 异步操作 ID |
| data[].status | String | 操作状态 |
| data[].done | Boolean | 是否完成 |
| data[].message | String | 操作消息 |
| data[].errorMessage | String | 错误消息 |
| data[].createTime | String | 创建时间 |
| data[].updateTime | String | 更新时间 |
| data[].createBy | String | 创建人 |

#### 成功示例

**请求**:
```http
GET /salesforce/metadata/async/history?limit=5
```

**响应**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": 1,
      "asyncId": "0Afxx0000000001CAA",
      "status": "Completed",
      "done": true,
      "message": "部署成功",
      "errorMessage": null,
      "createTime": "2026-02-06T14:00:00",
      "updateTime": "2026-02-06T14:30:00",
      "createBy": "admin"
    },
    {
      "id": 2,
      "asyncId": "0Afxx0000000002CAA",
      "status": "Failed",
      "done": true,
      "message": "部署失败",
      "errorMessage": "Invalid metadata",
      "createTime": "2026-02-06T13:00:00",
      "updateTime": "2026-02-06T13:05:00",
      "createBy": "admin"
    }
  ]
}
```

#### 使用场景
- 查看最近的异步操作记录
- 审计和监控异步操作
- 排查问题

---

### 5. 根据 asyncId 查询异步操作记录

**功能描述**: 根据 Salesforce 返回的异步操作 ID 查询本地记录。

**请求方式**: GET

**请求路径**: `/salesforce/metadata/async/record/{asyncId}`

**权限要求**: `salesforce:metadata:async:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 位置 | 说明 |
|--------|------|------|------|------|
| asyncId | String | 是 | Path | 异步操作 ID |

#### 响应参数

与"获取异步操作历史"接口中的单条记录格式相同。

#### 成功示例

**请求**:
```http
GET /salesforce/metadata/async/record/0Afxx0000000001CAA
```

**响应**:
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "asyncId": "0Afxx0000000001CAA",
    "status": "Completed",
    "done": true,
    "message": "部署成功",
    "errorMessage": null,
    "createTime": "2026-02-06T14:00:00",
    "updateTime": "2026-02-06T14:30:00",
    "createBy": "admin"
  }
}
```

#### 失败示例

**请求**:
```http
GET /salesforce/metadata/async/record/invalid-id
```

**响应**:
```json
{
  "code": 500,
  "msg": "未找到异步操作记录: invalid-id"
}
```

#### 使用场景
- 根据 asyncId 查询特定操作的详细记录
- 查看操作的历史状态变化

---

## 错误码

### 业务错误码

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 操作成功 | 请求处理成功 |
| 500 | 操作失败 | 通用错误，具体信息见 msg 字段 |

### 异常类型

| 异常类型 | 触发条件 | HTTP 状态码 |
|----------|----------|-------------|
| SalesforceAuthException | 会话过期、未授权 | 401 |
| SalesforceOperationException | 无效的操作 ID、操作失败 | 500 |
| IllegalArgumentException | 参数校验失败 | 400 |

### 常见错误场景

| 场景 | 错误信息 | 解决方案 |
|------|----------|----------|
| 会话过期 | "Salesforce 会话已过期，请重新连接" | 重新连接 Salesforce |
| 无效的操作 ID | "无效的异步操作 ID" | 检查 asyncId 是否正确 |
| 操作已完成 | "取消异步操作失败，操作可能已完成或无法取消" | 无法取消已完成的操作 |
| 轮询超时 | "异步操作轮询超时，已等待 X 秒" | 增加超时时间或检查操作状态 |
| 轮询被中断 | "异步操作轮询被中断" | 重新发起轮询请求 |

---

## 状态说明

### 异步操作状态

| 状态 | 说明 | 是否可取消 |
|------|------|------------|
| Queued | 已排队，等待执行 | 是 |
| InProgress | 正在进行中 | 是 |
| Completed | 已完成 | 否 |
| Failed | 失败 | 否 |
| Canceled | 已取消 | 否 |

### 状态流转

```
Queued → InProgress → Completed
   ↓         ↓           ↓
Canceled   Failed      (结束)
```

---

## 使用建议

### 1. 状态查询 vs 轮询

- **状态查询**: 适用于需要立即获取当前状态的场景，不阻塞
- **轮询**: 适用于需要等待操作完成的场景，会阻塞直到完成或超时

### 2. 超时设置

- 默认超时 5 分钟（300 秒）适用于大多数部署操作
- 对于大型部署，可以适当增加超时时间
- 不建议设置过长的超时时间，以免占用过多服务器资源

### 3. 错误处理

- 对于会话过期错误，应提示用户重新连接
- 对于无效的操作 ID，应检查 ID 是否正确
- 对于超时错误，可以再次发起轮询或查询状态

### 4. 权限控制

- 查询操作需要 `salesforce:metadata:async:query` 权限
- 取消操作需要 `salesforce:metadata:async:cancel` 权限
- 建议将取消权限授予更高级别的用户

---

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-003-04-异步操作.md)
- [设计文档](../design/2026-02-03-003-04-异步操作-设计.md)
- [决策记录](../decisions/2026-02-03-003-04-ADR-异步操作轮询策略.md)
- [复盘文档](../retros/2026-02-06-003-04-retro.md)
- [变更日志](../changelog/2026-02-06-003-04-changelog.md)
- [会话记录](../sessions/2026-02-06-003-04-session.md)