# API 文档

## 元数据
- 需求编号：004
- 子需求编号：004-01
- 创建时间：2026-01-28
- 创建人：AI Assistant
- 状态：已完成

## API 概述
本 API 文档描述了 Salesforce Tooling API 的连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项和设置调试头部等核心接口。所有接口均需要用户登录认证，使用若依框架的权限控制机制。

## 接口列表

### 接口 1：获取连接

- **功能描述**：获取 ToolingConnection 连接，用于后续的 Tooling API 调用
- **请求方式**：GET
- **请求路径**：`/tooling/connection`
- **权限要求**：需要登录认证（@PreAuthorize("@ss.hasLogin()")）
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | Object | 响应数据 |
  | data.connected | Boolean | 是否已连接 |
  | data.connectionType | String | 连接类型（TOOLING） |
  | data.orgType | String | ORG 类型（source） |
  | data.message | String | 消息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "connected": true,
      "connectionType": "TOOLING",
      "orgType": "source",
      "message": "连接获取成功"
    }
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "获取连接失败: 用户未登录或 Session 已过期"
  }
  ```

### 接口 2：清除缓存

- **功能描述**：清除 ToolingConnection 连接缓存，下次获取连接时将重新创建
- **请求方式**：DELETE
- **请求路径**：`/tooling/connection/cache`
- **权限要求**：需要登录认证（@PreAuthorize("@ss.hasLogin()")）
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "清除缓存成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "清除缓存失败: 服务器内部错误"
  }
  ```

### 接口 3：测试连接

- **功能描述**：测试 ToolingConnection 连接是否有效，通过调用 getUserInfo 验证连接
- **请求方式**：GET
- **请求路径**：`/tooling/connection/test`
- **权限要求**：需要登录认证（@PreAuthorize("@ss.hasLogin()")）
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | Object | 响应数据 |
  | data.connected | Boolean | 是否已连接 |
  | data.connectionType | String | 连接类型（TOOLING） |
  | data.orgType | String | ORG 类型（source） |
  | data.message | String | 消息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "connected": true,
      "connectionType": "TOOLING",
      "orgType": "source",
      "message": "连接测试成功"
    }
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "测试连接失败: TOOLING_CONN_001 - 连接测试失败"
  }
  ```

### 接口 4：设置调用选项

- **功能描述**：设置 CallOptions 头部，用于指定客户端名称等信息
- **请求方式**：POST
- **请求路径**：`/tooling/connection/call-options`
- **权限要求**：需要登录认证（@PreAuthorize("@ss.hasLogin()")）
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | client | String | 是 | 客户端名称，长度 1-255 字符 |
- **请求示例**：
  ```json
  {
    "client": "DataiToolingClient"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "设置调用选项成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "设置调用选项失败: TOOLING_CONN_002 - 设置调用选项失败"
  }
  ```

### 接口 5：设置调试头部

- **功能描述**：设置 DebuggingHeader 头部，用于启用调试日志
- **请求方式**：POST
- **请求路径**：`/tooling/connection/debugging-header`
- **权限要求**：需要登录认证（@PreAuthorize("@ss.hasLogin()")）
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | debugLevel | String | 是 | 调试级别，可选值：None, Debugonly, Db, Profiling, Callout, Detail, Fine, Finer, Finest |
- **请求示例**：
  ```json
  {
    "debugLevel": "Debugonly"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "设置调试头部成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "设置调试头部失败: TOOLING_CONN_003 - 设置调试头部失败"
  }
  ```

## 错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 操作成功 | - |
| 401 | 未登录或登录已过期 | 请重新登录 |
| 403 | 无权限访问 | 请检查用户权限 |
| 500 | 服务器内部错误 | 请联系管理员或稍后重试 |
| TOOLING_CONN_001 | 连接测试失败 | 请检查 Salesforce 连接配置或重新登录 |
| TOOLING_CONN_002 | 设置调用选项失败 | 请检查客户端名称是否有效 |
| TOOLING_CONN_003 | 设置调试头部失败 | 请检查调试级别是否有效 |
| TOOLING_CONN_004 | Session 无效或已过期 | 请重新登录 |
| TOOLING_CONN_005 | 连接创建失败 | 请检查 Salesforce 连接配置或重新登录 |

## 认证方式

所有接口均使用若依框架的认证机制，需要在请求头中携带有效的 Token：

```http
Authorization: Bearer {token}
```

Token 通过登录接口获取，有效期为 2 小时。

## 相关文档
- [需求文档](../requirements/2026-01-28-004-ToolingAPI源org实现.md)
- [子需求文档 - 连接管理](../requirements/sub/2026-01-28-004-01-连接管理.md)
- [设计文档](../design/2026-01-28-004-01-连接管理-设计.md)
- [决策记录](../decisions/2026-01-28-004-01-ADR-连接管理技术选型.md)
- [提示词](../prompts/2026-01-28-004-01-prompt-连接管理.md)
- [变更日志](../changelog/2026-01-28-004-01-changelog.md)
- [复盘文档](../retros/2026-01-28-004-retro.md)
- [会话记录](../sessions/2026-01-28-004-session.md)