# API 文档

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

## API 概述
Tooling API 访问和安全功能提供了一系列接口，用于查询 Salesforce 的访问控制相关枚举类型，包括访问方法、访问资源类型、API 访问级别、API 类型、激活平台连接器类型、激活平台创建类型。同时提供操作日志记录功能，用于记录访问和安全操作的详细信息。

## 接口列表

### 1. 查询访问方法

**功能描述**：查询 Salesforce 访问方法（AccessMethod）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/access-methods`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | 访问方法列表 |
| data.list[].name | String | 访问方法名称 |
| data.list[].description | String | 访问方法描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询访问方法成功",
  "data": {
    "total": 3,
    "list": [
      {
        "name": "OAuth",
        "description": "OAuth 2.0 认证"
      },
      {
        "name": "SAML",
        "description": "SAML 单点登录"
      },
      {
        "name": "Password",
        "description": "密码认证"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询访问方法失败: 连接超时"
}
```

**权限要求**：`tooling:access:query`

---

### 2. 查询访问资源类型

**功能描述**：查询 Salesforce 访问资源类型（AccessResourceType）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/access-resource-types`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | 访问资源类型列表 |
| data.list[].name | String | 资源类型名称 |
| data.list[].description | String | 资源类型描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询访问资源类型成功",
  "data": {
    "total": 5,
    "list": [
      {
        "name": "Account",
        "description": "客户"
      },
      {
        "name": "Contact",
        "description": "联系人"
      },
      {
        "name": "Opportunity",
        "description": "商机"
      },
      {
        "name": "Lead",
        "description": "潜在客户"
      },
      {
        "name": "Case",
        "description": "案例"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询访问资源类型失败: 认证失败"
}
```

**权限要求**：`tooling:access:query`

---

### 3. 查询 API 访问级别

**功能描述**：查询 Salesforce API 访问级别（APIAccessLevel）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/api-access-levels`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | API 访问级别列表 |
| data.list[].name | String | 访问级别名称 |
| data.list[].description | String | 访问级别描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询 API 访问级别成功",
  "data": {
    "total": 3,
    "list": [
      {
        "name": "Read",
        "description": "只读访问"
      },
      {
        "name": "Write",
        "description": "读写访问"
      },
      {
        "name": "Admin",
        "description": "管理员访问"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询 API 访问级别失败: 连接超时"
}
```

**权限要求**：`tooling:access:query`

---

### 4. 查询 API 类型

**功能描述**：查询 Salesforce API 类型（APIType）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/api-types`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | API 类型列表 |
| data.list[].name | String | API 类型名称 |
| data.list[].description | String | API 类型描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询 API 类型成功",
  "data": {
    "total": 4,
    "list": [
      {
        "name": "REST",
        "description": "REST API"
      },
      {
        "name": "SOAP",
        "description": "SOAP API"
      },
      {
        "name": "Bulk",
        "description": "Bulk API"
      },
      {
        "name": "Streaming",
        "description": "Streaming API"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询 API 类型失败: 认证失败"
}
```

**权限要求**：`tooling:access:query`

---

### 5. 查询激活平台连接器类型

**功能描述**：查询 Salesforce 激活平台连接器类型（ActivationPlatformConnectorType）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/activation-platform-connector-types`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | 激活平台连接器类型列表 |
| data.list[].name | String | 连接器类型名称 |
| data.list[].description | String | 连接器类型描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询激活平台连接器类型成功",
  "data": {
    "total": 3,
    "list": [
      {
        "name": "REST",
        "description": "REST 连接器"
      },
      {
        "name": "SOAP",
        "description": "SOAP 连接器"
      },
      {
        "name": "OData",
        "description": "OData 连接器"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询激活平台连接器类型失败: 连接超时"
}
```

**权限要求**：`tooling:access:query`

---

### 6. 查询激活平台创建类型

**功能描述**：查询 Salesforce 激活平台创建类型（ActivationPlatformCreationType）列表

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/activation-platform-creation-types`

**请求参数**：无

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | 激活平台创建类型列表 |
| data.list[].name | String | 创建类型名称 |
| data.list[].description | String | 创建类型描述 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询激活平台创建类型成功",
  "data": {
    "total": 2,
    "list": [
      {
        "name": "Manual",
        "description": "手动创建"
      },
      {
        "name": "Auto",
        "description": "自动创建"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询激活平台创建类型失败: 认证失败"
}
```

**权限要求**：`tooling:access:query`

---

### 7. 查询操作日志

**功能描述**：分页查询访问和安全操作日志

**请求方式**：GET

**请求路径**：`/salesforce/tooling/access-security/logs`

**请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |
| operationType | String | 否 | 操作类型（ACCESS_METHOD_QUERY/ACCESS_RESOURCE_TYPE_QUERY/API_ACCESS_LEVEL_QUERY/API_TYPE_QUERY/CONNECTOR_TYPE_QUERY/CREATION_TYPE_QUERY） |
| status | String | 否 | 状态（SUCCESS/FAILURE） |
| beginTime | String | 否 | 开始时间（yyyy-MM-dd HH:mm:ss） |
| endTime | String | 否 | 结束时间（yyyy-MM-dd HH:mm:ss） |

**响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Integer | 总数 |
| data.list | Array | 操作日志列表 |
| data.list[].id | Long | 日志 ID |
| data.list[].operationType | String | 操作类型 |
| data.list[].operationDesc | String | 操作描述 |
| data.list[].connectionId | Long | 连接 ID |
| data.list[].orgId | String | 组织 ID |
| data.list[].userId | Long | 用户 ID |
| data.list[].methodName | String | 方法名称 |
| data.list[].resourceType | String | 资源类型 |
| data.list[].apiAccessLevel | String | API 访问级别 |
| data.list[].apiType | String | API 类型 |
| data.list[].connectorType | String | 连接器类型 |
| data.list[].creationType | String | 创建类型 |
| data.list[].requestParams | String | 请求参数（JSON 格式） |
| data.list[].responseData | String | 响应数据（JSON 格式） |
| data.list[].status | String | 状态（SUCCESS/FAILURE） |
| data.list[].errorMsg | String | 错误信息 |
| data.list[].createTime | String | 创建时间 |
| data.list[].updateTime | String | 更新时间 |

**成功示例**：
```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "total": 15,
    "list": [
      {
        "id": 1,
        "operationType": "ACCESS_METHOD_QUERY",
        "operationDesc": "查询访问方法",
        "connectionId": 1,
        "orgId": "00Dxx0000000001",
        "userId": 1,
        "methodName": null,
        "resourceType": null,
        "apiAccessLevel": null,
        "apiType": null,
        "connectorType": null,
        "creationType": null,
        "requestParams": "{}",
        "responseData": "{\"total\":3,\"list\":[...]}",
        "status": "SUCCESS",
        "errorMsg": null,
        "createTime": "2026-02-06 10:30:00",
        "updateTime": "2026-02-06 10:30:00"
      }
    ]
  }
}
```

**失败示例**：
```json
{
  "code": 500,
  "msg": "查询失败: 数据库连接异常"
}
```

**权限要求**：`tooling:access:query`

---

## 错误码

| 错误码 | 错误信息 | 说明 |
|--------|----------|------|
| TOOLING_ACCESS_001 | 访问方法查询失败 | 查询访问方法时发生错误 |
| TOOLING_ACCESS_002 | 访问资源类型查询失败 | 查询访问资源类型时发生错误 |
| TOOLING_ACCESS_003 | API 访问级别查询失败 | 查询 API 访问级别时发生错误 |
| TOOLING_ACCESS_004 | 激活平台类型查询失败 | 查询激活平台类型时发生错误 |

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-06-访问和安全.md)
- [设计文档](../design/2026-02-03-004-06-访问和安全-设计.md)
- [决策文档](../decisions/2026-02-03-004-06-ADR-访问和安全技术选型.md)
- [SQL 脚本](../sql/2026-02-03-004-06-访问和安全操作日志.sql)
- [提示词文档](../prompts/2026-02-06-004-06-prompt-访问和安全.md)
- [变更日志](../changelog/2026-02-06-004-06-changelog.md)
- [复盘文档](../retros/2026-02-06-004-06-retro.md)