# Metadata 连接管理 API 文档

## 元数据
- 需求编号：003
- 创建时间：2026-02-03
- 创建人：AI Assistant
- 版本：v1.0.0

## API 概述
本模块提供 Salesforce Metadata API 源 Org 的连接管理功能，包括查看连接状态、测试连接、刷新连接和关闭连接。所有接口均需要认证权限。

## 接口列表

### 1. 获取连接状态
- **功能描述**：获取当前 Metadata API 连接的状态信息，包括是否已连接、Session ID 是否有效、Server URL 等。
- **请求方式**：GET
- **请求路径**：`/api/metadata/connection/status`
- **权限要求**：`metadata:connection:status`
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功） |
  | msg | String | 提示信息 |
  | data | Object | 连接状态对象 |
  | data.connected | Boolean | 是否已连接 |
  | data.serverUrl | String | Metadata Server URL |
  | data.username | String | 当前用户名 |
  | data.apiVersion | String | API 版本 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "connected": true,
      "serverUrl": "https://datai-dev-ed.my.salesforce.com/services/Soap/m/65.0/00D5j00000C...",
      "username": "admin@datai.com",
      "apiVersion": "65.0"
    }
  }
  ```

### 2. 测试连接
- **功能描述**：尝试建立 Metadata API 连接并执行一次简单的元数据描述操作（describeMetadata），以验证连接的有效性。
- **请求方式**：POST
- **请求路径**：`/api/metadata/connection/test`
- **权限要求**：`metadata:connection:test`
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码 |
  | msg | String | 提示信息 |
  | data | Boolean | 测试结果（true 成功，false 失败） |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": true
  }
  ```

### 3. 刷新连接
- **功能描述**：强制刷新当前的 Metadata API 连接，重新从 SessionManager 获取 Session ID 并建立新连接。
- **请求方式**：POST
- **请求路径**：`/api/metadata/connection/refresh`
- **权限要求**：`metadata:connection:refresh`
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码 |
  | msg | String | 提示信息 |
  | data | Boolean | 刷新结果 |

### 4. 关闭连接
- **功能描述**：关闭当前的 Metadata API 连接，释放资源。
- **请求方式**：POST
- **请求路径**：`/api/metadata/connection/close`
- **权限要求**：`metadata:connection:close`
- **请求参数**：无
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码 |
  | msg | String | 提示信息 |
  | data | Boolean | 关闭结果 |

## 错误码
| 错误码 | 说明 | 解决方案 |
|--------|------|----------|
| 500 | 系统内部错误 | 检查服务器日志 |
| 401 | 未认证 | 请先登录系统 |
| 403 | 无权限 | 请联系管理员分配权限 |
| 10001 | Salesforce 认证失败 | Session 已过期，请重新登录 Salesforce |
| 10002 | Salesforce 操作失败 | 检查网络连接或参数配置 |

## 相关文档
- [需求文档](../requirements/2026-01-28-003-MetadataAPI源org实现.md)
- [设计文档](../design/2026-02-02-003-01-连接管理-设计.md)