# API 文档

## 元数据
- 需求编号：014-4
- 创建时间：2026-01-27
- 创建人：SSOT 架构师
- 状态：已完成

## API 概述

本 API 提供了元数据容器与原子性部署功能，基于 Salesforce Tooling API 的 MetadataContainer 机制，支持元数据容器生命周期管理、容器成员管理、异步部署请求和状态轮询与结果解析。

### 核心功能
1. **元数据容器生命周期管理**：创建容器、删除容器、查询容器、获取容器详情
2. **容器成员管理**：添加成员到容器，支持多种元数据类型
3. **异步部署请求**：创建部署请求，支持 CheckOnly 模式和测试执行
4. **状态轮询与结果解析**：查询部署状态、轮询部署状态、获取部署详情、解析编译错误、解析测试结果

### 技术栈
- Spring Boot 3.5.7
- 若依框架
- Salesforce WSC 0.0.1

### 基础路径
- 元数据容器管理：`/tooling/metadata-container`
- 部署管理：`/tooling/deployment`

### 统一响应格式
所有 API 接口均返回统一的响应格式：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

| 字段名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 返回数据 |

## 接口列表

### 1. 创建容器接口

#### 功能描述
创建一个新的元数据容器，用于存放待部署的元数据成员。

#### 请求方式
POST

#### 请求路径
`/tooling/metadata-container/create`

#### 请求权限
`tooling:container:create`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 是 | 容器名称，长度 1-255 字符 |

#### 请求示例
```json
{
  "name": "MyContainer"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 容器 ID |
| name | String | 容器名称 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "a0B5g000006l7VFEAY",
    "name": "MyContainer",
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：容器名称冲突
- 501：创建容器失败

---

### 2. 删除容器接口

#### 功能描述
删除指定的元数据容器及其所有成员。

#### 请求方式
DELETE

#### 请求路径
`/tooling/metadata-container/delete/{id}`

#### 请求权限
`tooling:container:delete`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 容器 ID（路径参数） |

#### 请求示例
```
DELETE /tooling/metadata-container/delete/a0B5g000006l7VFEAY
```

#### 响应参数
无

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功"
}
```

#### 错误码
- 500：删除容器失败
- 501：容器不存在

---

### 3. 获取容器详情接口

#### 功能描述
获取指定容器的详细信息。

#### 请求方式
GET

#### 请求路径
`/tooling/metadata-container/get/{id}`

#### 请求权限
`tooling:container:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | String | 是 | 容器 ID（路径参数） |

#### 请求示例
```
GET /tooling/metadata-container/get/a0B5g000006l7VFEAY
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 容器 ID |
| name | String | 容器名称 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "a0B5g000006l7VFEAY",
    "name": "MyContainer",
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：查询容器失败
- 501：容器不存在

---

### 4. 查询容器列表接口

#### 功能描述
查询符合条件的容器列表。

#### 请求方式
GET

#### 请求路径
`/tooling/metadata-container/list`

#### 请求权限
`tooling:container:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 否 | 容器名称（模糊查询） |

#### 请求示例
```
GET /tooling/metadata-container/list?name=MyContainer
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 容器 ID |
| name | String | 容器名称 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": [
    {
      "id": "a0B5g000006l7VFEAY",
      "name": "MyContainer",
      "createdDate": "2026-01-27T10:00:00.000Z",
      "lastModifiedDate": "2026-01-27T10:00:00.000Z"
    }
  ]
}
```

#### 错误码
- 500：查询容器列表失败

---

### 5. 添加成员接口

#### 功能描述
向指定容器添加一个元数据成员。

#### 请求方式
POST

#### 请求路径
`/tooling/deployment/member/add`

#### 请求权限
`tooling:deployment:addMember`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| containerId | String | 是 | 容器 ID |
| metadataType | String | 是 | 元数据类型（ApexClass、ApexTrigger、ApexPage 等） |
| contentEntityId | String | 否 | 内容实体 ID（可选） |
| body | String | 是 | 代码内容 |

#### 请求示例
```json
{
  "containerId": "a0B5g000006l7VFEAY",
  "metadataType": "ApexClass",
  "body": "public class MyClass {\n    public void myMethod() {\n        System.debug('Hello World');\n    }\n}"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 成员 ID |
| containerId | String | 容器 ID |
| metadataType | String | 元数据类型 |
| contentEntityId | String | 内容实体 ID |
| body | String | 代码内容 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "a0C5g000006l7VFEAY",
    "containerId": "a0B5g000006l7VFEAY",
    "metadataType": "ApexClass",
    "contentEntityId": null,
    "body": "public class MyClass {\n    public void myMethod() {\n        System.debug('Hello World');\n    }\n}",
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：添加成员失败
- 501：容器不存在

---

### 6. 部署容器接口

#### 功能描述
触发指定容器的部署，支持 CheckOnly 模式和测试执行。

#### 请求方式
POST

#### 请求路径
`/tooling/deployment/deploy`

#### 请求权限
`tooling:deployment:deploy`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| containerId | String | 是 | 容器 ID |
| isCheckOnly | Boolean | 是 | 是否仅检查（true：仅检查不部署，false：实际部署） |
| isRunTests | Boolean | 是 | 是否运行测试（true：运行测试，false：不运行测试） |

#### 请求示例
```json
{
  "containerId": "a0B5g000006l7VFEAY",
  "isCheckOnly": false,
  "isRunTests": true
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 请求 ID |
| state | String | 部署状态（Queued、InProgress、Completed、Failed） |
| metadataContainerId | String | 容器 ID |
| isCheckOnly | Boolean | 是否仅检查 |
| isRunTests | Boolean | 是否运行测试 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": "1DR5g000006l7VFEAY",
    "state": "Queued",
    "metadataContainerId": "a0B5g000006l7VFEAY",
    "isCheckOnly": false,
    "isRunTests": true,
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：部署失败
- 501：容器不存在
- 502：容器为空（没有成员）
- 503：并发部署限制

---

### 7. 查询部署状态接口

#### 功能描述
查询指定部署请求的状态。

#### 请求方式
POST

#### 请求路径
`/tooling/deployment/status/check`

#### 请求权限
`tooling:deployment:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| requestId | String | 是 | 请求 ID |

#### 请求示例
```json
{
  "requestId": "1DR5g000006l7VFEAY"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| requestId | String | 请求 ID |
| state | String | 部署状态（Queued、InProgress、Completed、Failed） |
| metadataContainerId | String | 容器 ID |
| isCheckOnly | Boolean | 是否仅检查 |
| isRunTests | Boolean | 是否运行测试 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "requestId": "1DR5g000006l7VFEAY",
    "state": "Completed",
    "metadataContainerId": "a0B5g000006l7VFEAY",
    "isCheckOnly": false,
    "isRunTests": true,
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：查询状态失败
- 501：请求不存在

---

### 8. 轮询部署状态接口

#### 功能描述
轮询指定部署请求的状态，直到完成或超时。

#### 请求方式
POST

#### 请求路径
`/tooling/deployment/status/poll`

#### 请求权限
`tooling:deployment:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| requestId | String | 是 | 请求 ID |
| maxRetries | Integer | 否 | 最大重试次数（默认 60） |
| intervalMillis | Long | 否 | 轮询间隔（毫秒，默认 1000） |

#### 请求示例
```
POST /tooling/deployment/status/poll?requestId=1DR5g000006l7VFEAY&maxRetries=60&intervalMillis=1000
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| requestId | String | 请求 ID |
| state | String | 部署状态（Queued、InProgress、Completed、Failed） |
| metadataContainerId | String | 容器 ID |
| isCheckOnly | Boolean | 是否仅检查 |
| isRunTests | Boolean | 是否运行测试 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "requestId": "1DR5g000006l7VFEAY",
    "state": "Completed",
    "metadataContainerId": "a0B5g000006l7VFEAY",
    "isCheckOnly": false,
    "isRunTests": true,
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z"
  }
}
```

#### 错误码
- 500：轮询状态失败
- 501：请求不存在
- 502：轮询超时

---

### 9. 获取部署详情接口

#### 功能描述
获取指定部署请求的详细信息，包括编译错误和测试结果。

#### 请求方式
POST

#### 请求路径
`/tooling/deployment/details/get`

#### 请求权限
`tooling:deployment:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| requestId | String | 是 | 请求 ID |

#### 请求示例
```json
{
  "requestId": "1DR5g000006l7VFEAY"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| requestId | String | 请求 ID |
| state | String | 部署状态（Queued、InProgress、Completed、Failed） |
| metadataContainerId | String | 容器 ID |
| isCheckOnly | Boolean | 是否仅检查 |
| isRunTests | Boolean | 是否运行测试 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |
| componentFailures | Array | 编译错误列表 |
| runTestResult | Object | 测试结果 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "requestId": "1DR5g000006l7VFEAY",
    "state": "Completed",
    "metadataContainerId": "a0B5g000006l7VFEAY",
    "isCheckOnly": false,
    "isRunTests": true,
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z",
    "componentFailures": [],
    "runTestResult": {
      "numFailures": 0,
      "numTestsRun": 1,
      "totalTime": 123
    }
  }
}
```

#### 错误码
- 500：获取详情失败
- 501：请求不存在

---

### 10. 获取部署结果接口

#### 功能描述
获取指定部署请求的部署结果，包括编译错误和测试结果。

#### 请求方式
GET

#### 请求路径
`/tooling/deployment/result/{requestId}`

#### 请求权限
`tooling:deployment:query`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| requestId | String | 是 | 请求 ID（路径参数） |

#### 请求示例
```
GET /tooling/deployment/result/1DR5g000006l7VFEAY
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| requestId | String | 请求 ID |
| state | String | 部署状态（Queued、InProgress、Completed、Failed） |
| metadataContainerId | String | 容器 ID |
| isCheckOnly | Boolean | 是否仅检查 |
| isRunTests | Boolean | 是否运行测试 |
| createdDate | String | 创建时间 |
| lastModifiedDate | String | 最后修改时间 |
| componentFailures | Array | 编译错误列表 |
| runTestResult | Object | 测试结果 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "requestId": "1DR5g000006l7VFEAY",
    "state": "Completed",
    "metadataContainerId": "a0B5g000006l7VFEAY",
    "isCheckOnly": false,
    "isRunTests": true,
    "createdDate": "2026-01-27T10:00:00.000Z",
    "lastModifiedDate": "2026-01-27T10:00:00.000Z",
    "componentFailures": [],
    "runTestResult": {
      "numFailures": 0,
      "numTestsRun": 1,
      "totalTime": 123
    }
  }
}
```

#### 错误码
- 500：获取结果失败
- 501：请求不存在

---

## 错误码

### 通用错误码
| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 500 | 操作失败 |
| 501 | 资源不存在 |

### 元数据容器错误码
| 错误码 | 说明 |
|--------|------|
| 500 | 创建容器失败 |
| 501 | 容器不存在 |
| 502 | 容器名称冲突 |

### 部署错误码
| 错误码 | 说明 |
|--------|------|
| 500 | 部署失败 |
| 501 | 请求不存在 |
| 502 | 容器为空（没有成员） |
| 503 | 并发部署限制 |
| 504 | 轮询超时 |

---

## 相关文档
- [需求文档](../requirements/REQ-014-4.md)
- [设计文档](../design/2026-01-27-014-4-元数据容器与原子性部署-设计.md)
- [决策记录](../decisions/adr/2026-01-27-014-4-ADR-元数据容器与原子性部署技术选型.md)
- [提示词](../prompts/2026-01-27-014-4-prompt-元数据容器与原子性部署.md)