# API 文档 - Apex 连接管理

## 元数据
- 需求编号：002-01
- 需求名称：Apex 连接管理
- 创建时间：2026-02-02
- 创建人：AI Assistant
- 版本：v1.0.0

## API 概述

本 API 文档描述了 Salesforce Apex API 连接管理接口，提供了完整的连接管理功能，包括连接获取、会话头设置、调用选项配置、调试头部配置、字段截断头配置、包版本头配置和连接缓存清除等功能。

### 核心功能
- **连接工厂**：创建和管理 SoapConnection 实例
- **会话头管理**：设置和更新 SessionHeader
- **调用选项**：配置 CallOptions 头部
- **调试头部**：配置 DebuggingHeader 用于调试
- **字段截断头**：配置 AllowFieldTruncationHeader
- **包版本头**：配置 PackageVersionHeader
- **连接缓存**：使用 AbstractConnectionFactory 提供的缓存机制

### 技术特性
- 固定使用 source org 类型
- 继承 AbstractConnectionFactory<SoapConnection>，复用缓存机制
- 使用 Salesforce API 65.0 版本
- 连接超时 60 秒，读取超时 60 秒
- 支持连接压缩

### 安全特性
- 使用 Spring Security 进行权限控制
- 使用 @PreAuthorize 注解进行方法级权限控制
- 使用 @Valid 注解进行参数校验
- 统一的异常处理机制

## 接口列表

### 接口 1：获取连接

#### 功能描述
获取 SoapConnection 连接信息，包括会话 ID、服务器 URL、连接状态等信息。

#### 请求方式
GET

#### 请求路径
`/api/apex/connection`

#### 权限要求
`apex:connection:get`

#### 请求参数
无

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.sessionId | String | 会话 ID（前 20 位） |
| data.serverUrl | String | 服务器 URL |
| data.success | Boolean | 是否成功 |
| data.errorMessage | String | 错误信息（成功时为 null） |

#### 成功示例
```json
{
  "code": 200,
  "msg": "获取连接成功",
  "data": {
    "sessionId": "00Dxx0000001Gw2!AQ0AQH...",
    "serverUrl": "https://datai-dev-ed.my.salesforce.com",
    "success": true,
    "errorMessage": null
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "获取连接失败: 未找到 source org 的会话信息，请先登录"
}
```

---

### 接口 2：设置会话头

#### 功能描述
设置 SoapConnection 的会话头（SessionHeader），用于指定会话 ID。

#### 请求方式
POST

#### 请求路径
`/api/apex/connection/session-header`

#### 权限要求
`apex:connection:session`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | String | 是 | 会话 ID，长度 1-255 字符 |

#### 请求示例
```json
{
  "sessionId": "00Dxx0000001Gw2!AQ0AQH..."
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置会话头成功",
  "data": {
    "success": true
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置会话头失败: 未找到连接"
}
```

---

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

#### 功能描述
设置 SoapConnection 的调用选项（CallOptions），用于指定客户端名称。

#### 请求方式
POST

#### 请求路径
`/api/apex/connection/call-options`

#### 权限要求
`apex:connection:call`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| client | String | 否 | 客户端名称，长度 1-255 字符 |

#### 请求示例
```json
{
  "client": "DataiSalesforceApex/1.0.0"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

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

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

---

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

#### 功能描述
设置 SoapConnection 的调试头部（DebuggingHeader），用于调试和日志记录。

#### 请求方式
POST

#### 请求路径
`/api/apex/connection/debugging-header`

#### 权限要求
`apex:connection:debug`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| logCategories | Array | 否 | 日志分类数组 |
| logCategories[].category | String | 否 | 日志分类（如：DB、VALIDATION、WORKFLOW、CALLOUT、APEX_CODE） |
| logCategories[].level | String | 否 | 日志级别（如：FINE、FINER、FINEST、DEBUG、INFO、WARN、ERROR） |
| logType | String | 否 | 日志类型（如：PROFILING、DEBUGONLY） |

#### 请求示例
```json
{
  "logCategories": [
    {
      "category": "DB",
      "level": "FINE"
    },
    {
      "category": "APEX_CODE",
      "level": "DEBUG"
    }
  ],
  "logType": "PROFILING"
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

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

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置调试头部失败: 未找到连接"
}
```

---

### 接口 5：设置字段截断头

#### 功能描述
设置 SoapConnection 的字段截断头（AllowFieldTruncationHeader），用于控制字段截断行为。

#### 请求方式
POST

#### 请求路径
`/api/apex/connection/field-truncation-header`

#### 权限要求
`apex:connection:truncate`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| allowFieldTruncation | Boolean | 否 | 是否允许字段截断（true：允许，false：不允许） |

#### 请求示例
```json
{
  "allowFieldTruncation": true
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置字段截断头成功",
  "data": {
    "success": true
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置字段截断头失败: 未找到连接"
}
```

---

### 接口 6：设置包版本头

#### 功能描述
设置 SoapConnection 的包版本头（PackageVersionHeader），用于指定包版本信息。

#### 请求方式
POST

#### 请求路径
`/api/apex/connection/package-version-header`

#### 权限要求
`apex:connection:version`

#### 请求参数
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| packageVersions | Array | 否 | 包版本数组 |
| packageVersions[].namespace | String | 否 | 包命名空间 |
| packageVersions[].majorNumber | Integer | 否 | 主版本号 |
| packageVersions[].minorNumber | Integer | 否 | 次版本号 |
| packageVersions[].namespacePrefix | String | 否 | 命名空间前缀 |

#### 请求示例
```json
{
  "packageVersions": [
    {
      "namespace": "MyPackage",
      "majorNumber": 1,
      "minorNumber": 0,
      "namespacePrefix": "mypkg"
    }
  ]
}
```

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

#### 成功示例
```json
{
  "code": 200,
  "msg": "设置包版本头成功",
  "data": {
    "success": true
  }
}
```

#### 失败示例
```json
{
  "code": 500,
  "msg": "设置包版本头失败: 未找到连接"
}
```

---

### 接口 7：清除连接缓存

#### 功能描述
清除 Apex 连接缓存，强制重新创建连接。

#### 请求方式
DELETE

#### 请求路径
`/api/apex/connection/cache`

#### 权限要求
`apex:connection:clear`

#### 请求参数
无

#### 响应参数
| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.success | Boolean | 是否成功 |

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

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

## 错误码

### 通用错误码

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 200 | 操作成功 | 请求处理成功 |
| 400 | 请求参数错误 | 请求参数格式错误或缺少必填参数 |
| 401 | 未授权 | 用户未登录或登录已过期 |
| 403 | 无权限 | 用户没有访问该接口的权限 |
| 500 | 服务器内部错误 | 服务器处理请求时发生错误 |

### 业务错误码

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 501 | 未找到 source org 的会话信息 | 请先登录 source org |
| 502 | 未找到连接 | 连接不存在或已失效 |
| 503 | 创建连接失败 | 创建连接时发生错误 |
| 504 | 设置会话头失败 | 设置会话头时发生错误 |
| 505 | 设置调用选项失败 | 设置调用选项时发生错误 |
| 506 | 设置调试头部失败 | 设置调试头部时发生错误 |
| 507 | 设置字段截断头失败 | 设置字段截断头时发生错误 |
| 508 | 设置包版本头失败 | 设置包版本头时发生错误 |
| 509 | 清除连接缓存失败 | 清除连接缓存时发生错误 |

### 参数校验错误码

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| 601 | 会话ID不能为空 | 设置会话头时，会话 ID 参数为空 |

## 相关文档

### 需求文档
- [Apex 连接管理需求](../requirements/sub/2026-01-28-002-01-连接管理.md)

### 设计文档
- [Apex 连接管理设计](../design/2026-02-02-002-01-连接管理-设计.md)

### 决策记录
- [Apex 连接管理技术选型](../decisions/2026-02-02-002-01-ADR-Apex连接管理技术选型.md)

### 复盘文档
- [Apex 连接管理复盘](../retros/2026-02-02-002-01-retro.md)

## 附录

### Swagger 文档访问
启动应用后，可以通过以下 URL 访问 Swagger UI：
- Swagger UI: `http://localhost:8080/swagger-ui.html`
- API JSON: `http://localhost:8080/v3/api-docs`

### Postman 集合
可以使用 Postman 导入以下集合进行 API 测试：
```json
{
  "info": {
    "name": "Apex Connection Management",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "item": [
    {
      "name": "获取连接",
      "request": {
        "method": "GET",
        "header": [],
        "url": {
          "raw": "{{baseUrl}}/api/apex/connection",
          "host": ["{{baseUrl}}"],
          "path": ["api", "apex", "connection"]
        }
      }
    },
    {
      "name": "设置会话头",
      "request": {
        "method": "POST",
        "header": [],
        "body": {
          "mode": "raw",
          "raw": "{\n  \"sessionId\": \"00Dxx0000001Gw2!AQ0AQH...\"\n}"
        },
        "url": {
          "raw": "{{baseUrl}}/api/apex/connection/session-header",
          "host": ["{{baseUrl}}"],
          "path": ["api", "apex", "connection", "session-header"]
        }
      }
    }
  ]
}
```

### 权限配置
在使用这些 API 接口之前，需要在系统中配置相应的权限：
- `apex:connection:get` - 获取连接权限
- `apex:connection:session` - 设置会话头权限
- `apex:connection:call` - 设置调用选项权限
- `apex:connection:debug` - 设置调试头部权限
- `apex:connection:truncate` - 设置字段截断头权限
- `apex:connection:version` - 设置包版本头权限
- `apex:connection:clear` - 清除连接缓存权限

### 认证说明
所有 API 接口都需要进行身份认证，请在请求头中添加以下认证信息：
```
Authorization: Bearer {token}
```

其中 `{token}` 为登录后获取的 JWT 令牌。