# API 文档

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

## API 概述
本文档描述 Tooling API 开发工具功能的 REST API 接口，提供 Salesforce 开发工具集的查询功能，包括代码覆盖率查询、测试队列管理、日志获取和成员查询等。

**基础路径**：`/api/tooling/devtools`

**认证方式**：JWT Token（通过 Header 传递）

## 接口列表

### 1. 查询代码覆盖率

**功能描述**：查询 Apex 类/触发器的代码覆盖率信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/code-coverage`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| classOrTriggerName | String | 否 | 类或触发器名称（模糊查询）|
| classOrTriggerId | String | 否 | 类或触发器 ID |
| namespace | String | 否 | 命名空间前缀 |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败）|
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | 代码覆盖率列表 |
| data.rows[].apexClassOrTriggerId | String | 类或触发器 ID |
| data.rows[].apexClassOrTriggerName | String | 类或触发器名称 |
| data.rows[].coverage | Double | 覆盖率百分比 |
| data.rows[].numLinesCovered | Integer | 已覆盖行数 |
| data.rows[].numLinesUncovered | Integer | 未覆盖行数 |

- **成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 2,
    "rows": [
      {
        "apexClassOrTriggerId": "01p5g00000XxXxXxXx",
        "apexClassOrTriggerName": "AccountTrigger",
        "coverage": 85.5,
        "numLinesCovered": 120,
        "numLinesUncovered": 20
      },
      {
        "apexClassOrTriggerId": "01p5g00000YyYyYyYy",
        "apexClassOrTriggerName": "ContactController",
        "coverage": 92.0,
        "numLinesCovered": 230,
        "numLinesUncovered": 20
      }
    ]
  }
}
```

- **错误码**：
  - TOOLING_DEVTOOLS_001：查询条件不能为空
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_003：查询代码覆盖率失败

---

### 2. 查询测试队列项

**功能描述**：查询测试队列项（ApexTestQueueItem）信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/test-queue-items`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| status | String | 否 | 状态（Queued/Processing/Completed/Failed/Aborted）|
| apexClassId | String | 否 | Apex 类 ID |
| parentJobId | String | 否 | 父作业 ID |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败）|
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | 测试队列项列表 |
| data.rows[].apexClassId | String | Apex 类 ID |
| data.rows[].apexClassName | String | Apex 类名称 |
| data.rows[].status | String | 状态 |
| data.rows[].extendedStatus | String | 扩展状态 |
| data.rows[].methodNames | String | 方法名列表 |
| data.rows[].createdDate | String | 创建时间 |
| data.rows[].parentJobId | String | 父作业 ID |

- **成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "rows": [
      {
        "apexClassId": "01p5g00000XxXxXxXx",
        "apexClassName": "AccountControllerTest",
        "status": "Completed",
        "extendedStatus": "Success",
        "methodNames": "testCreateAccount,testUpdateAccount",
        "createdDate": "2026-02-05T10:30:00.000Z",
        "parentJobId": "7075g00000YyYyYyYy"
      }
    ]
  }
}
```

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_004：查询测试队列项失败

---

### 3. 查询 Apex 日志

**功能描述**：查询 Apex 日志信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/apex-logs`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| application | String | 否 | 应用名称 |
| location | String | 否 | 位置 |
| operation | String | 否 | 操作 |
| status | String | 否 | 状态 |
| startTime | String | 否 | 开始时间（ISO 8601 格式）|
| endTime | String | 否 | 结束时间（ISO 8601 格式）|
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败）|
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | Apex 日志列表 |
| data.rows[].id | String | 日志 ID |
| data.rows[].application | String | 应用名称 |
| data.rows[].durationMilliseconds | Integer | 持续时间（毫秒）|
| data.rows[].location | String | 位置 |
| data.rows[].logLength | Integer | 日志长度 |
| data.rows[].operation | String | 操作 |
| data.rows[].startTime | String | 开始时间 |
| data.rows[].status | String | 状态 |

- **成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "rows": [
      {
        "id": "07L5g00000XxXxXxXx",
        "application": "Data Loader",
        "durationMilliseconds": 1250,
        "location": "System",
        "logLength": 10240,
        "operation": "executeAnonymous",
        "startTime": "2026-02-05T10:30:00.000Z",
        "status": "Success"
      }
    ]
  }
}
```

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_005：查询 Apex 日志失败

---

### 4. 查询 Apex 类成员

**功能描述**：查询 Apex 类成员（ApexClassMember）信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/apex-class-member`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| contentEntityId | String | 否 | 内容实体 ID |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败）|
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | 成员列表 |
| data.rows[].id | String | 成员 ID |
| data.rows[].body | String | 成员内容 |
| data.rows[].bodyCrc | Long | 内容 CRC 校验值 |
| data.rows[].contentEntityId | String | 内容实体 ID |
| data.rows[].contentType | String | 内容类型 |
| data.rows[].symbolTable | String | 符号表 |

- **成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "rows": [
      {
        "id": "4005g00000XxXxXxXx",
        "body": "public class AccountController { ... }",
        "bodyCrc": 1234567890,
        "contentEntityId": "01p5g00000XxXxXxXx",
        "contentType": "ApexClass",
        "symbolTable": "{...}"
      }
    ]
  }
}
```

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_006：查询 Apex 类成员失败

---

### 5. 查询 Apex 触发器成员

**功能描述**：查询 Apex 触发器成员（ApexTriggerMember）信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/apex-trigger-member`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| contentEntityId | String | 否 | 内容实体 ID |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：同"查询 Apex 类成员"

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_007：查询 Apex 触发器成员失败

---

### 6. 查询 Visualforce 页面成员

**功能描述**：查询 Visualforce 页面成员（ApexPageMember）信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/apex-page-member`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| contentEntityId | String | 否 | 内容实体 ID |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：同"查询 Apex 类成员"

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_008：查询 Visualforce 页面成员失败

---

### 7. 查询组件成员

**功能描述**：查询组件成员（ApexComponentMember）信息

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/apex-component-member`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| orgType | String | 是 | ORG 类型（source/target）|
| contentEntityId | String | 否 | 内容实体 ID |
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：同"查询 Apex 类成员"

- **错误码**：
  - TOOLING_DEVTOOLS_002：获取 Tooling 连接失败
  - TOOLING_DEVTOOLS_009：查询组件成员失败

---

### 8. 查询操作日志

**功能描述**：查询开发工具操作日志

- **请求方式**：GET
- **请求路径**：`/api/tooling/devtools/operation-logs`
- **请求参数**：

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| operationType | String | 否 | 操作类型（QUERY_CODE_COVERAGE/QUERY_TEST_QUEUE/QUERY_APEX_LOG/QUERY_MEMBER）|
| metadataType | String | 否 | 元数据类型 |
| status | String | 否 | 状态（SUCCESS/FAILED）|
| startTime | String | 否 | 开始时间（ISO 8601 格式）|
| endTime | String | 否 | 结束时间（ISO 8601 格式）|
| pageNum | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页大小，默认 10 |

- **响应参数**：

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败）|
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | 操作日志列表 |
| data.rows[].id | Long | 日志 ID |
| data.rows[].operationType | String | 操作类型 |
| data.rows[].metadataType | String | 元数据类型 |
| data.rows[].metadataId | String | 元数据 ID |
| data.rows[].metadataName | String | 元数据名称 |
| data.rows[].queryCondition | String | 查询条件 |
| data.rows[].resultCount | Integer | 结果数量 |
| data.rows[].status | String | 状态 |
| data.rows[].errorCode | String | 错误码 |
| data.rows[].errorMessage | String | 错误消息 |
| data.rows[].operationTime | String | 操作时间 |
| data.rows[].userId | Long | 用户 ID |

- **成功示例**：
```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 1,
    "rows": [
      {
        "id": 1,
        "operationType": "QUERY_CODE_COVERAGE",
        "metadataType": "ApexCodeCoverage",
        "metadataId": null,
        "metadataName": "AccountTrigger",
        "queryCondition": "ApexClassOrTrigger.Name LIKE '%AccountTrigger%'",
        "resultCount": 2,
        "status": "SUCCESS",
        "errorCode": null,
        "errorMessage": null,
        "operationTime": "2026-02-05T10:30:00.000",
        "userId": 1
      }
    ]
  }
}
```

- **错误码**：
  - TOOLING_DEVTOOLS_010：查询操作日志失败

---

## 错误码

| 错误码 | 说明 |
|--------|------|
| TOOLING_DEVTOOLS_001 | 查询条件不能为空 |
| TOOLING_DEVTOOLS_002 | 获取 Tooling 连接失败 |
| TOOLING_DEVTOOLS_003 | 查询代码覆盖率失败 |
| TOOLING_DEVTOOLS_004 | 查询测试队列项失败 |
| TOOLING_DEVTOOLS_005 | 查询 Apex 日志失败 |
| TOOLING_DEVTOOLS_006 | 查询 Apex 类成员失败 |
| TOOLING_DEVTOOLS_007 | 查询 Apex 触发器成员失败 |
| TOOLING_DEVTOOLS_008 | 查询 Visualforce 页面成员失败 |
| TOOLING_DEVTOOLS_009 | 查询组件成员失败 |
| TOOLING_DEVTOOLS_010 | 查询操作日志失败 |
| TOOLING_DEVTOOLS_011 | 记录操作日志失败 |

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-03-开发工具功能.md)
- [设计文档](../design/2026-02-03-004-03-开发工具功能-设计.md)
- [决策文档](../decisions/2026-02-03-004-03-ADR-开发工具功能技术选型.md)
- [SQL 脚本](../sql/2026-02-03-004-03-开发工具操作日志.sql)
- [提示词文档](../prompts/2026-02-05-004-03-prompt-开发工具功能.md)
- [变更日志](../changelog/2026-02-05-004-03-changelog.md)
- [复盘文档](../retros/2026-02-05-004-03-retro.md)
- [会话记录](../sessions/2026-02-03-004-03-session.md)