# API 文档 - 检查部署和检索状态

## 元数据
- 需求编号：003-07
- 需求名称：检查部署和检索状态
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 版本号：v1.0.0
- 状态：已完成

## API 概述
本模块提供 Salesforce Metadata API 的部署和检索状态检查功能，支持单次状态查询、轮询监控和历史记录查询。所有接口都需要用户已登录并具有相应的权限。

### 核心功能
1. **部署状态检查**：查询指定部署操作的当前状态
2. **检索状态检查**：查询指定检索操作的当前状态
3. **部署状态轮询**：轮询部署状态直到完成或超时
4. **检索状态轮询**：轮询检索状态直到完成或超时
5. **状态查询历史**：查询状态检查的历史记录

### 技术特点
- 支持轻量级调用（`includeDetails=false`）
- 轮询参数可配置（间隔、超时）
- 异步记录审计日志
- 自动同步关联表状态

## 接口列表

### 1. 检查部署状态

#### 接口说明
查询指定部署操作的当前状态，返回部署结果详情。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/deploy/{asyncId}`
- **Content-Type**：application/json

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |

#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| includeDetails | Boolean | 否 | true | 是否包含详细信息（如错误详情） |

#### 请求示例
```http
GET /salesforce/metadata/status/deploy/0Afxx0000004M5sCAE?includeDetails=true
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | DeployResult 对象 |

#### DeployResult 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 异步操作 ID |
| status | String | 部署状态（Queued/InProgress/Succeeded/Failed/Canceled） |
| numberComponentErrors | Integer | 组件错误数 |
| numberComponentsDeployed | Integer | 已部署组件数 |
| numberTestErrors | Integer | 测试错误数 |
| numberTestsCompleted | Integer | 已完成测试数 |
| errorMessage | String | 错误消息（失败时） |

#### 成功响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "numberComponentErrors": 0,
    "numberComponentsDeployed": 5,
    "numberTestErrors": 0,
    "numberTestsCompleted": 10,
    "errorMessage": null
  }
}
```

#### 失败响应示例
```json
{
  "code": 500,
  "msg": "检查部署状态失败: 无效的异步操作 ID",
  "data": null
}
```

---

### 2. 检查检索状态

#### 接口说明
查询指定检索操作的当前状态，返回检索结果详情。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/retrieve/{asyncId}`
- **Content-Type**：application/json

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |

#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| includeDetails | Boolean | 否 | true | 是否包含详细信息（如错误详情） |

#### 请求示例
```http
GET /salesforce/metadata/status/retrieve/0Afxx0000004M5sCAE?includeDetails=true
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | RetrieveResult 对象 |

#### RetrieveResult 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 异步操作 ID |
| status | String | 检索状态（Queued/InProgress/Succeeded/Failed/Canceled） |
| success | Boolean | 是否成功 |
| errorMessage | String | 错误消息（失败时） |
| zipFile | String | ZIP 文件内容（Base64 编码，成功时） |

#### 成功响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "success": true,
    "errorMessage": null,
    "zipFile": "UEsDBBQAAAAIA..."
  }
}
```

#### 失败响应示例
```json
{
  "code": 500,
  "msg": "检查检索状态失败: 异步操作未找到",
  "data": null
}
```

---

### 3. 轮询部署状态

#### 接口说明
轮询部署状态直到完成（Succeeded/Failed/Canceled）或超时。适用于需要等待部署完成的场景。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/deploy/poll/{asyncId}`
- **Content-Type**：application/json

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |

#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| interval | Long | 否 | 2000 | 轮询间隔（毫秒） |
| timeout | Long | 否 | 300000 | 超时时间（毫秒），默认 5 分钟 |

#### 请求示例
```http
GET /salesforce/metadata/status/deploy/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | DeployResult 对象（最终状态） |

#### 成功响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "numberComponentErrors": 0,
    "numberComponentsDeployed": 5,
    "numberTestErrors": 0,
    "numberTestsCompleted": 10,
    "errorMessage": null
  }
}
```

#### 超时响应示例
```json
{
  "code": 500,
  "msg": "部署轮询超时",
  "data": null
}
```

---

### 4. 轮询检索状态

#### 接口说明
轮询检索状态直到完成（Succeeded/Failed/Canceled）或超时。适用于需要等待检索完成的场景。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/retrieve/poll/{asyncId}`
- **Content-Type**：application/json

#### 路径参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| asyncId | String | 是 | 异步操作 ID，Salesforce 返回的 AsyncResult ID |

#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| interval | Long | 否 | 2000 | 轮询间隔（毫秒） |
| timeout | Long | 否 | 300000 | 超时时间（毫秒），默认 5 分钟 |

#### 请求示例
```http
GET /salesforce/metadata/status/retrieve/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | RetrieveResult 对象（最终状态） |

#### 成功响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "0Afxx0000004M5sCAE",
    "status": "Succeeded",
    "success": true,
    "errorMessage": null,
    "zipFile": "UEsDBBQAAAAIA..."
  }
}
```

#### 中断响应示例
```json
{
  "code": 500,
  "msg": "轮询被中断",
  "data": null
}
```

---

### 5. 获取状态查询历史

#### 接口说明
查询状态检查的历史记录，支持按操作类型筛选。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/metadata/status/history`
- **Content-Type**：application/json

#### 查询参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| operationType | String | 否 | - | 操作类型（DEPLOY/RETRIEVE），不填则查询所有 |
| limit | Integer | 否 | 50 | 返回数量限制 |

#### 请求示例
```http
GET /salesforce/metadata/status/history?operationType=DEPLOY&limit=50
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 状态检查历史列表 |

#### StatusCheckHistoryVo 对象
| 参数名 | 类型 | 说明 |
|--------|------|------|
| checkId | String | 检查记录 ID |
| asyncId | String | 异步操作 ID |
| operationType | String | 操作类型（DEPLOY/RETRIEVE） |
| status | String | 状态 |
| checkTime | String | 检查时间（ISO 8601 格式） |
| errorMessage | String | 错误消息 |

#### 成功响应示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "checkId": "CHK202502060001",
      "asyncId": "0Afxx0000004M5sCAE",
      "operationType": "DEPLOY",
      "status": "Succeeded",
      "checkTime": "2026-02-06T10:30:00Z",
      "errorMessage": null
    },
    {
      "checkId": "CHK202502060002",
      "asyncId": "0Afxx0000004M5sCAF",
      "operationType": "RETRIEVE",
      "status": "Failed",
      "checkTime": "2026-02-06T10:25:00Z",
      "errorMessage": "Invalid metadata type"
    }
  ]
}
```

---

## 错误码

### 状态检查错误码
| 错误码 | 说明 | 场景 |
|--------|------|------|
| STATUS_001 | 会话已过期 | Salesforce 会话过期 |
| STATUS_002 | 未授权访问 | 用户没有权限访问 |
| STATUS_003 | 无效的异步操作 ID | asyncId 格式不正确 |
| STATUS_004 | 异步操作未找到 | 指定的 asyncId 不存在 |
| STATUS_005 | 检查状态失败 | API 调用失败 |
| STATUS_006 | 轮询超时 | 轮询时间超过 timeout 参数 |
| STATUS_007 | 轮询被中断 | 线程被中断 |
| STATUS_008 | 远程调用失败 | 网络异常或 Salesforce 服务不可用 |
| STATUS_009 | 查询历史失败 | 数据库查询失败 |

### HTTP 状态码
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 数据字典

### 部署状态（Deploy Status）
| 状态值 | 说明 |
|--------|------|
| Queued | 已排队，等待执行 |
| InProgress | 进行中 |
| Succeeded | 成功完成 |
| Failed | 失败 |
| Canceled | 已取消 |

### 检索状态（Retrieve Status）
| 状态值 | 说明 |
|--------|------|
| Queued | 已排队，等待执行 |
| InProgress | 进行中 |
| Succeeded | 成功完成 |
| Failed | 失败 |
| Canceled | 已取消 |

### 操作类型（Operation Type）
| 类型值 | 说明 |
|--------|------|
| DEPLOY | 部署操作 |
| RETRIEVE | 检索操作 |

## 使用示例

### 场景 1：检查部署状态
```java
// 前端调用示例
fetch('/salesforce/metadata/status/deploy/0Afxx0000004M5sCAE?includeDetails=true')
  .then(response => response.json())
  .then(data => {
    if (data.code === 200) {
      console.log('部署状态:', data.data.status);
    } else {
      console.error('查询失败:', data.msg);
    }
  });
```

### 场景 2：轮询检索状态直到完成
```java
// 前端调用示例
fetch('/salesforce/metadata/status/retrieve/poll/0Afxx0000004M5sCAE?interval=2000&timeout=300000')
  .then(response => response.json())
  .then(data => {
    if (data.code === 200) {
      console.log('检索完成，状态:', data.data.status);
      if (data.data.success) {
        // 处理 ZIP 文件
        console.log('ZIP 文件:', data.data.zipFile);
      }
    } else {
      console.error('轮询失败:', data.msg);
    }
  });
```

### 场景 3：查询部署历史
```java
// 前端调用示例
fetch('/salesforce/metadata/status/history?operationType=DEPLOY&limit=10')
  .then(response => response.json())
  .then(data => {
    if (data.code === 200) {
      data.data.forEach(record => {
        console.log('检查记录:', record.checkId, record.status);
      });
    }
  });
```

## 注意事项

### 1. 轮询超时处理
- 轮询接口可能会长时间阻塞（默认最长 5 分钟）
- 建议在前端设置更长的超时时间或异步处理
- 如果超时，可以再次调用轮询接口继续等待

### 2. 轻量级调用
- 如果不需要详细的错误信息，建议设置 `includeDetails=false`
- 轻量级调用可以减少网络传输和 Salesforce API 调用开销

### 3. 审计日志
- 每次状态检查都会异步记录到数据库
- 审计日志不影响主流程性能
- 可以通过历史查询接口查看审计日志

### 4. 关联表状态同步
- 状态检查会自动更新部署日志表和检索记录表的状态
- 无需手动更新这些表

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
- [决策记录](../decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md)
- [变更日志](../changelog/2026-02-06-003-07-changelog.md)
- [复盘文档](../retros/2026-02-06-003-07-retro.md)
- [会话记录](../sessions/2026-02-03-003-07-session.md)
- [部署操作 API 文档](./2026-02-06-003-03-api.md)
- [检索操作 API 文档](./2026-02-06-003-06-api.md)