# API 文档

## 元数据
- 需求编号：004-01
- 文档版本：v1.0.0
- 创建时间：2026-02-03
- 创建人：AI Assistant
- 状态：已完成

## API 概述

### 功能描述
Tooling API 连接管理模块提供 Salesforce Tooling API 的连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部等核心功能。

### 基础信息
- **基础路径**：`/salesforce/tooling/connection`
- **协议**：HTTPS
- **数据格式**：JSON
- **字符编码**：UTF-8

### 认证方式
- 使用 JWT Token 进行身份认证
- Token 通过登录接口获取
- 需要在请求头中携带 `Authorization: Bearer {token}`

### 权限控制
- 使用 Spring Security 进行权限控制
- 每个接口都有对应的权限标识
- 权限格式：`tooling:connection:{操作}`

## 接口列表

### 1. 获取连接

#### 接口说明
获取 Tooling API 连接，如果缓存中没有有效连接，则创建新连接。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/tooling/connection/get`
- **权限标识**：`tooling:connection:get`

#### 请求参数
无

#### 响应参数

##### 成功响应（HTTP 200）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 表示成功） |
| msg | String | 提示信息 |
| data | Object | 连接结果对象 |
| data.success | Boolean | 是否成功 |
| data.connectionId | String | 连接 ID |
| data.sessionId | String | Session ID（脱敏处理） |
| data.instanceUrl | String | Salesforce 实例 URL |
| data.connectionTime | String | 连接时间（格式：yyyy-MM-dd HH:mm:ss） |
| data.client | String | 客户端名称 |
| data.debugLevel | String | 调试级别 |

##### 失败响应（HTTP 200，业务错误）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（非 200 表示失败） |
| msg | String | 错误信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "success": true,
    "connectionId": "conn_1234567890",
    "sessionId": "00D...",
    "instanceUrl": "https://xxxxx.my.salesforce.com",
    "connectionTime": "2026-02-03 10:30:00",
    "client": "DataiToolingClient",
    "debugLevel": "DEBUG"
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "获取连接失败: Session 无效或已过期"
}
```

#### 错误码
- `TOOLING_CONN_001`：Session 无效或已过期
- `TOOLING_CONN_002`：连接创建失败
- `TOOLING_CONN_006`：用户未登录

---

### 2. 清除连接缓存

#### 接口说明
清除缓存的 Tooling API 连接。

#### 请求信息
- **请求方式**：DELETE
- **请求路径**：`/salesforce/tooling/connection/clear`
- **权限标识**：`tooling:connection:clear`

#### 请求参数
无

#### 响应参数

##### 成功响应（HTTP 200）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 表示成功） |
| msg | String | 提示信息 |

##### 失败响应（HTTP 200，业务错误）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（非 200 表示失败） |
| msg | String | 错误信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "清除连接缓存成功"
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "清除连接缓存失败: 无权限操作"
}
```

#### 错误码
- `TOOLING_CONN_004`：权限不足

---

### 3. 测试连接

#### 接口说明
测试 Tooling API 连接是否有效。

#### 请求信息
- **请求方式**：GET
- **请求路径**：`/salesforce/tooling/connection/test`
- **权限标识**：`tooling:connection:test`

#### 请求参数
无

#### 响应参数

##### 成功响应（HTTP 200）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 表示成功） |
| msg | String | 提示信息 |
| data | Object | 测试结果对象 |
| data.success | Boolean | 是否成功 |
| data.valid | Boolean | 连接是否有效 |
| data.testTime | String | 测试时间（格式：yyyy-MM-dd HH:mm:ss） |
| data.responseTime | Long | 响应时间（毫秒） |
| data.errorCode | String | 错误码（失败时返回） |
| data.errorMessage | String | 错误消息（失败时返回） |

##### 失败响应（HTTP 200，业务错误）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（非 200 表示失败） |
| msg | String | 错误信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-03 10:35:00",
    "responseTime": 150
  }
}
```

#### 失败示例
```json
{
  "code": 200,
  "msg": "测试连接成功",
  "data": {
    "success": true,
    "valid": false,
    "testTime": "2026-02-03 10:35:00",
    "responseTime": 50,
    "errorCode": "TOOLING_CONN_001",
    "errorMessage": "Session 无效或已过期"
  }
}
```

#### 错误码
- `TOOLING_CONN_001`：Session 无效或已过期
- `TOOLING_CONN_003`：网络超时

---

### 4. 设置调用选项

#### 接口说明
设置 Tooling API 连接的调用选项。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/salesforce/tooling/connection/call-options`
- **权限标识**：`tooling:connection:callOptions`
- **Content-Type**：`application/json`

#### 请求参数

##### Body 参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| client | String | 否 | 客户端名称，用于标识调用来源 |

#### 请求示例
```json
{
  "client": "DataiToolingClient"
}
```

#### 响应参数

##### 成功响应（HTTP 200）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 表示成功） |
| msg | String | 提示信息 |
| data | Object | 设置结果对象 |
| data.success | Boolean | 是否成功 |
| data.client | String | 设置的客户端名称 |

##### 失败响应（HTTP 200，业务错误）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（非 200 表示失败） |
| msg | String | 错误信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置调用选项成功",
  "data": {
    "success": true,
    "client": "DataiToolingClient"
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置调用选项失败: 连接无效"
}
```

#### 错误码
- `TOOLING_CONN_001`：Session 无效或已过期
- `TOOLING_CONN_007`：设置调用选项失败

---

### 5. 设置调试头部

#### 接口说明
设置 Tooling API 连接的调试头部。

#### 请求信息
- **请求方式**：POST
- **请求路径**：`/salesforce/tooling/connection/debugging-header`
- **权限标识**：`tooling:connection:debuggingHeader`
- **Content-Type**：`application/json`

#### 请求参数

##### Body 参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| debugLevel | String | 否 | 调试级别，可选值：NONE、DEBUG、DB、DETAIL、PROFILING |

#### 调试级别说明
| 级别 | 说明 |
|------|------|
| NONE | 不记录调试信息 |
| DEBUG | 记录基本调试信息 |
| DB | 记录数据库操作信息 |
| DETAIL | 记录详细信息 |
| PROFILING | 记录性能分析信息 |

#### 请求示例
```json
{
  "debugLevel": "DEBUG"
}
```

#### 响应参数

##### 成功响应（HTTP 200）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 表示成功） |
| msg | String | 提示信息 |
| data | Object | 设置结果对象 |
| data.success | Boolean | 是否成功 |
| data.debugLevel | String | 设置的调试级别 |

##### 失败响应（HTTP 200，业务错误）
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（非 200 表示失败） |
| msg | String | 错误信息 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置调试头部成功",
  "data": {
    "success": true,
    "debugLevel": "DEBUG"
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置调试头部失败: 无效的调试级别"
}
```

#### 错误码
- `TOOLING_CONN_001`：Session 无效或已过期
- `TOOLING_CONN_008`：设置调试头部失败

---

## 错误码

### 错误码列表

| 错误码 | 错误消息 | 说明 |
|--------|----------|------|
| TOOLING_CONN_001 | Session 无效或已过期 | 当前用户的 Session 已过期或无效，需要重新登录 |
| TOOLING_CONN_002 | 连接创建失败 | 创建 ToolingConnection 时发生错误 |
| TOOLING_CONN_003 | 网络超时 | 与 Salesforce API 通信超时 |
| TOOLING_CONN_004 | 权限不足 | 当前用户没有执行该操作的权限 |
| TOOLING_CONN_005 | API 版本不支持 | 请求的 API 版本不被支持 |
| TOOLING_CONN_006 | 用户未登录 | 用户未登录或登录状态已失效 |
| TOOLING_CONN_007 | 设置调用选项失败 | 设置 CallOptions 时发生错误 |
| TOOLING_CONN_008 | 设置调试头部失败 | 设置 DebuggingHeader 时发生错误 |

### 错误码使用场景

#### TOOLING_CONN_001 - Session 无效或已过期
- **触发场景**：
  - 用户 Session 已过期
  - Session ID 被篡改
  - Salesforce 端 Session 被注销
- **处理建议**：
  - 提示用户重新登录
  - 自动刷新 Session（如果支持）

#### TOOLING_CONN_002 - 连接创建失败
- **触发场景**：
  - Instance URL 无效
  - Session ID 无效
  - 网络异常
- **处理建议**：
  - 检查 Salesforce 配置
  - 检查网络连接
  - 查看详细错误日志

#### TOOLING_CONN_003 - 网络超时
- **触发场景**：
  - 网络延迟过高
  - Salesforce 服务响应慢
  - 请求数据量过大
- **处理建议**：
  - 检查网络连接
  - 增加超时时间配置
  - 分批处理大数据量请求

#### TOOLING_CONN_004 - 权限不足
- **触发场景**：
  - 用户没有对应接口的权限
  - 权限配置未同步到数据库
- **处理建议**：
  - 联系管理员分配权限
  - 检查权限配置是否正确

#### TOOLING_CONN_005 - API 版本不支持
- **触发场景**：
  - 请求的 API 版本过低或过高
- **处理建议**：
  - 使用支持的 API 版本
  - 查看 Salesforce API 版本文档

#### TOOLING_CONN_006 - 用户未登录
- **触发场景**：
  - 用户未登录
  - Token 已过期
  - Token 被篡改
- **处理建议**：
  - 提示用户登录
  - 刷新 Token

#### TOOLING_CONN_007 - 设置调用选项失败
- **触发场景**：
  - 连接无效
  - 参数格式错误
- **处理建议**：
  - 先获取有效连接
  - 检查参数格式

#### TOOLING_CONN_008 - 设置调试头部失败
- **触发场景**：
  - 连接无效
  - 调试级别无效
- **处理建议**：
  - 先获取有效连接
  - 使用有效的调试级别

## 使用示例

### 场景 1：获取连接并测试

```java
// 步骤 1：获取连接
GET /salesforce/tooling/connection/get

// 步骤 2：测试连接
GET /salesforce/tooling/connection/test
```

### 场景 2：设置调试选项后执行操作

```java
// 步骤 1：设置调试级别
POST /salesforce/tooling/connection/debugging-header
{
  "debugLevel": "DEBUG"
}

// 步骤 2：设置客户端名称
POST /salesforce/tooling/connection/call-options
{
  "client": "MyApplication"
}

// 步骤 3：执行 Tooling API 操作
// ... 其他 Tooling API 调用

// 步骤 4：清除调试设置（可选）
POST /salesforce/tooling/connection/debugging-header
{
  "debugLevel": "NONE"
}
```

### 场景 3：连接异常时重新获取

```java
// 步骤 1：测试连接
GET /salesforce/tooling/connection/test

// 如果返回 valid=false
// 步骤 2：清除缓存
DELETE /salesforce/tooling/connection/clear

// 步骤 3：重新获取连接
GET /salesforce/tooling/connection/get
```

## 注意事项

### 1. 连接缓存
- 连接会缓存在内存中，避免重复创建
- 应用重启后缓存会丢失
- Session 过期时会自动重新创建连接

### 2. 线程安全
- 连接缓存使用 ConcurrentHashMap，线程安全
- 多个线程可以同时获取连接
- 但每个线程应该使用自己的连接实例

### 3. 性能建议
- 在应用启动时预获取连接
- 定期测试连接有效性
- 避免频繁清除缓存

### 4. 安全建议
- Session ID 在日志中会被脱敏处理
- 不要在客户端暴露 Session ID
- 使用 HTTPS 协议传输数据

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-01-连接管理.md)
- [设计文档](../design/2026-02-03-004-01-连接管理-设计.md)
- [决策记录](../decisions/2026-02-03-004-01-ADR-连接管理技术选型.md)
- [变更日志](../changelog/2026-02-03-004-01-changelog.md)
- [复盘文档](../retros/2026-02-03-004-01-retro.md)