# API 文档

## 元数据
- 需求编号：003
- 子需求编号：003-01
- 子需求名称：连接管理
- 创建时间：2026-02-05
- 创建人：AI Assistant
- 版本号：v1.0.0
- 接口基地址：`/api/metadata/connection`

## API 概述
Metadata API 连接管理接口提供对 Salesforce Metadata API 连接的管理能力，包括连接状态的获取、连接测试、连接刷新、连接关闭、调用选项设置、连接历史记录查询和连接缓存清除等功能。

### 核心功能
1. **连接状态管理**：获取当前 Metadata API 连接的状态信息
2. **连接测试**：测试 Metadata API 连接是否可用
3. **连接刷新**：刷新 Metadata API 连接，重新创建连接实例
4. **连接关闭**：关闭 Metadata API 连接，释放资源
5. **调用选项设置**：设置 Metadata API 的调用选项（如客户端名称）
6. **连接历史记录**：查询 Metadata API 连接的历史记录
7. **连接缓存管理**：清除 Metadata API 连接缓存

### 认证方式
所有接口都需要通过认证，使用 Spring Security 进行权限控制。请求头中需要包含有效的 JWT Token。

### 权限要求
每个接口都有特定的权限要求，使用 `@PreAuthorize` 注解进行控制。

## 接口列表

### 1. 获取连接状态

**功能描述**：获取当前 Metadata API 连接的状态信息，包括连接是否有效、最后测试时间、响应时间等。

**请求方式**：GET

**请求路径**：`/api/metadata/connection/status`

**权限要求**：`metadata:connection:status`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| 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.errorMessage | String | 错误信息（如果有） |

**成功示例**：
```json
{
  "code": 200,
  "msg": "获取连接状态成功",
  "data": {
    "success": true,
    "valid": true,
    "testTime": "2026-02-05 14:30:00",
    "responseTime": 150,
    "errorMessage": null
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "获取连接状态失败: 用户未登录或会话已过期",
  "data": null
}
```

**错误码**：
- 200：成功
- 500：服务器内部错误
- 401：未授权
- 403：权限不足

---

### 2. 测试连接

**功能描述**：测试 Metadata API 连接是否可用，会实际调用 Salesforce API 进行验证。

**请求方式**：POST

**请求路径**：`/api/metadata/connection/test`

**权限要求**：`metadata:connection:test`

**请求参数**：无

**响应参数**：

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

**成功示例**：
```json
{
  "code": 200,
  "msg": "连接测试成功",
  "data": null
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "连接测试失败: 无法连接到 Salesforce 服务器",
  "data": null
}
```

**错误码**：
- 200：连接测试成功
- 500：连接测试失败

**调用场景**：
- 系统启动时自动测试连接
- 用户手动测试连接状态
- 定时任务检查连接健康状态

---

### 3. 刷新连接

**功能描述**：刷新 Metadata API 连接，关闭现有连接并重新创建。适用于会话过期或需要重新建立连接的场景。

**请求方式**：POST

**请求路径**：`/api/metadata/connection/refresh`

**权限要求**：`metadata:connection:refresh`

**请求参数**：无

**响应参数**：

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

**成功示例**：
```json
{
  "code": 200,
  "msg": "刷新连接成功",
  "data": null
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "刷新连接失败: 会话已过期",
  "data": null
}
```

**错误码**：
- 200：刷新连接成功
- 500：刷新连接失败

**调用场景**：
- 会话过期后重新建立连接
- 连接出现异常时恢复连接
- 切换 org 类型后重新连接

---

### 4. 关闭连接

**功能描述**：关闭 Metadata API 连接，释放相关资源。关闭后需要调用刷新接口重新建立连接。

**请求方式**：POST

**请求路径**：`/api/metadata/connection/close`

**权限要求**：`metadata:connection:close`

**请求参数**：无

**响应参数**：

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

**成功示例**：
```json
{
  "code": 200,
  "msg": "关闭连接成功",
  "data": null
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "关闭连接失败: 连接不存在",
  "data": null
}
```

**错误码**：
- 200：关闭连接成功
- 500：关闭连接失败

**调用场景**：
- 系统关闭时释放资源
- 切换用户时关闭旧连接
- 长时间不使用时释放连接

---

### 5. 设置调用选项

**功能描述**：设置 Metadata API 的调用选项，如客户端名称等。这些选项会影响 API 调用的行为。

**请求方式**：POST

**请求路径**：`/api/metadata/connection/call-options`

**权限要求**：`metadata:connection:callOptions`

**请求参数**：

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

**请求示例**：
```json
{
  "client": "DataiMetadataClient"
}
```

**响应参数**：

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

**成功示例**：
```json
{
  "code": 200,
  "msg": "设置调用选项成功",
  "data": null
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "设置调用选项失败: 客户端名称不能为空",
  "data": null
}
```

**错误码**：
- 200：设置调用选项成功
- 400：请求参数错误
- 500：设置调用选项失败

**调用场景**：
- 初始化连接时设置客户端标识
- 多客户端环境下区分调用来源
- 监控和日志记录时标识客户端

---

### 6. 获取连接历史记录

**功能描述**：获取 Metadata API 连接的历史记录，包括连接创建、测试、刷新、关闭等操作的记录。

**请求方式**：GET

**请求路径**：`/api/metadata/connection/history`

**权限要求**：`metadata:connection:history`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Array | 连接历史记录列表 |
| data[].id | Long | 记录 ID |
| data[].orgType | String | ORG 类型（source/target） |
| data[].status | String | 连接状态（connected/failed/closed） |
| data[].testTime | String | 测试时间（格式：yyyy-MM-dd HH:mm:ss） |
| data[].responseTime | Long | 响应时间（毫秒） |
| data[].errorMessage | String | 错误信息（如果有） |
| data[].createTime | String | 记录创建时间 |
| data[].updateTime | String | 记录更新时间 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "获取连接历史成功",
  "data": [
    {
      "id": 1,
      "orgType": "source",
      "status": "connected",
      "testTime": "2026-02-05 14:30:00",
      "responseTime": 150,
      "errorMessage": null,
      "createTime": "2026-02-05 14:30:00",
      "updateTime": "2026-02-05 14:30:00"
    },
    {
      "id": 2,
      "orgType": "source",
      "status": "failed",
      "testTime": "2026-02-05 14:25:00",
      "responseTime": 0,
      "errorMessage": "会话已过期",
      "createTime": "2026-02-05 14:25:00",
      "updateTime": "2026-02-05 14:25:00"
    }
  ]
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "获取连接历史失败: 数据库连接错误",
  "data": null
}
```

**错误码**：
- 200：获取连接历史成功
- 500：获取连接历史失败

**调用场景**：
- 监控连接健康状态
- 排查连接问题
- 分析连接使用模式

---

### 7. 清除连接缓存

**功能描述**：清除 Metadata API 连接缓存，强制下次请求时重新创建连接。适用于连接状态异常或需要强制刷新连接的场景。

**请求方式**：DELETE

**请求路径**：`/api/metadata/connection/cache`

**权限要求**：`metadata:connection:clear`

**请求参数**：无

**响应参数**：

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

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

**失败示例**：
```json
{
  "code": 500,
  "msg": "清除连接缓存失败: 缓存不存在",
  "data": null
}
```

**错误码**：
- 200：清除连接缓存成功
- 500：清除连接缓存失败

**调用场景**：
- 连接状态异常时强制刷新
- 切换 org 配置后清除旧缓存
- 调试和测试时重置连接状态

---

## 错误码

### 系统错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 200 | 操作成功 | 无需处理 |
| 400 | 请求参数错误 | 检查请求参数是否符合要求 |
| 401 | 未授权 | 检查 JWT Token 是否有效 |
| 403 | 权限不足 | 检查用户是否有该接口的权限 |
| 404 | 资源不存在 | 检查请求路径是否正确 |
| 500 | 服务器内部错误 | 查看服务器日志，联系管理员 |

### 业务错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| METADATA_CONNECTION_ERROR | Metadata API 连接错误 | 检查网络连接和 Salesforce 服务状态 |
| METADATA_AUTH_ERROR | Metadata API 认证错误 | 检查 Session 是否过期，尝试重新登录 |
| METADATA_OPERATION_ERROR | Metadata API 操作错误 | 检查操作参数是否正确 |
| SESSION_EXPIRED | 会话已过期 | 重新登录获取新的 Session |
| INVALID_SESSION | 无效的会话 | 检查 Session ID 是否正确 |
| CONNECTION_FAILED | 连接失败 | 检查网络连接和服务器地址 |

## 调用示例

### 完整调用流程

```java
// 1. 获取连接状态
GET /api/metadata/connection/status
Response: {
  "code": 200,
  "msg": "获取连接状态成功",
  "data": {
    "valid": true,
    "testTime": "2026-02-05 14:30:00"
  }
}

// 2. 如果连接无效，刷新连接
POST /api/metadata/connection/refresh
Response: {
  "code": 200,
  "msg": "刷新连接成功"
}

// 3. 测试连接
POST /api/metadata/connection/test
Response: {
  "code": 200,
  "msg": "连接测试成功"
}

// 4. 设置调用选项
POST /api/metadata/connection/call-options
Request Body: {
  "client": "DataiMetadataClient"
}
Response: {
  "code": 200,
  "msg": "设置调用选项成功"
}

// 5. 执行业务操作（如部署元数据）
// ...

// 6. 关闭连接
POST /api/metadata/connection/close
Response: {
  "code": 200,
  "msg": "关闭连接成功"
}
```

## 性能指标

### 响应时间
- 获取连接状态：< 100ms
- 测试连接：< 2s（取决于网络状况）
- 刷新连接：< 3s（取决于网络状况）
- 关闭连接：< 100ms
- 设置调用选项：< 100ms
- 获取连接历史：< 500ms
- 清除连接缓存：< 100ms

### 并发限制
- 单个用户同时只能有一个活跃的 Metadata API 连接
- 连接缓存按 orgType 进行隔离
- 建议在高并发场景下使用连接池（后续版本支持）

## 注意事项

1. **会话管理**：所有接口都依赖有效的 Salesforce 会话，请确保在调用前先完成认证
2. **连接缓存**：连接会被缓存以提高性能，如需强制刷新请使用清除缓存接口
3. **错误处理**：建议对所有接口的错误情况进行处理，特别是认证错误和连接错误
4. **资源释放**：长时间不使用连接时，建议调用关闭连接接口释放资源
5. **历史记录**：连接历史记录会持久化到数据库，可用于监控和审计

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