# API 文档

## 元数据
- 需求编号：014-1
- 创建时间：2026-01-27
- 创建人：SSOT 架构师
- 版本号：v1.0.0

## API 概述
本 API 提供了 Apex 类与触发器的基础管理功能，包括创建、查询、更新、删除操作。API 基于 Salesforce Tooling API 实现，支持对 Apex 类和触发器的完整 CRUD 操作。

## 接口列表

### Apex 类管理接口

#### 接口 1：创建 Apex 类

- **功能描述**：创建新的 Apex 类，包括类名和类体
- **请求方式**：POST
- **请求路径**：`/tooling/apex-class`
- **权限要求**：`tooling:apex-class:create`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | name | String | 是 | Apex 类名称，长度 1-255 字符 |
  | body | String | 是 | Apex 类代码，不能为空 |
- **请求示例**：
  ```json
  {
    "name": "MyApexClass",
    "body": "public class MyApexClass {\n  public void hello() {\n    System.debug('Hello World');\n  }\n}"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | String | 创建的 Apex 类 ID |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "创建成功",
    "data": "01pB0000008xw0IAA"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "创建 Apex 类失败：类名已存在"
  }
  ```

#### 接口 2：查询 Apex 类详情

- **功能描述**：根据类名查询 Apex 类详情
- **请求方式**：GET
- **请求路径**：`/tooling/apex-class/{name}`
- **权限要求**：`tooling:apex-class:query`
- **路径参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | name | String | 是 | Apex 类名称 |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | ApexClassVo | Apex 类详情对象 |
- **ApexClassVo 对象**：
  | 字段名 | 类型 | 说明 |
  |--------|------|------|
  | id | String | Apex 类 ID |
  | name | String | Apex 类名称 |
  | status | String | 状态 |
  | linesOfCode | Integer | 代码行数 |
  | createdDate | String | 创建日期 |
  | lastModifiedDate | String | 最后修改日期 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "id": "01pB0000008xw0IAA",
      "name": "MyApexClass",
      "status": "Active",
      "linesOfCode": 5,
      "createdDate": "2026-01-27T10:00:00.000Z",
      "lastModifiedDate": "2026-01-27T10:00:00.000Z"
    }
  }
  ```

#### 接口 3：分页查询 Apex 类列表

- **功能描述**：分页查询 Apex 类列表，支持按状态筛选
- **请求方式**：GET
- **请求路径**：`/tooling/apex-class`
- **权限要求**：`tooling:apex-class:list`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 默认值 | 说明 |
  |--------|------|------|---------|------|
  | status | String | 否 | - | 状态筛选条件 |
  | pageNum | Integer | 否 | 1 | 页码 |
  | pageSize | Integer | 否 | 10 | 每页数量 |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | List<ApexClassVo> | Apex 类列表 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": [
      {
        "id": "01pB0000008xw0IAA",
        "name": "MyApexClass",
        "status": "Active",
        "linesOfCode": 5,
        "createdDate": "2026-01-27T10:00:00.000Z",
        "lastModifiedDate": "2026-01-27T10:00:00.000Z"
      }
    ]
  }
  ```

#### 接口 4：更新 Apex 类

- **功能描述**：更新 Apex 类的类体
- **请求方式**：PUT
- **请求路径**：`/tooling/apex-class`
- **权限要求**：`tooling:apex-class:update`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | id | String | 是 | Apex 类 ID |
  | body | String | 是 | Apex 类代码，不能为空 |
- **请求示例**：
  ```json
  {
    "id": "01pB0000008xw0IAA",
    "body": "public class MyApexClass {\n  public void hello() {\n    System.debug('Hello World Updated');\n  }\n}"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "更新成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "更新 Apex 类失败：类不存在"
  }
  ```

#### 接口 5：删除 Apex 类

- **功能描述**：根据 ID 删除 Apex 类
- **请求方式**：DELETE
- **请求路径**：`/tooling/apex-class/{id}`
- **权限要求**：`tooling:apex-class:delete`
- **路径参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | id | String | 是 | Apex 类 ID |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "删除成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "删除 Apex 类失败：类不存在"
  }
  ```

### Apex 触发器管理接口

#### 接口 6：创建 Apex 触发器

- **功能描述**：创建新的 Apex 触发器，包括触发器名称、触发器代码和关联对象
- **请求方式**：POST
- **请求路径**：`/tooling/apex-trigger`
- **权限要求**：`tooling:apex-trigger:create`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | name | String | 是 | Apex 触发器名称，长度 1-255 字符 |
  | body | String | 是 | Apex 触发器代码，不能为空 |
  | tableEnumOrId | String | 是 | 关联对象 ID 或枚举值 |
- **请求示例**：
  ```json
  {
    "name": "MyTrigger",
    "body": "trigger MyTrigger on Account (before insert) {\n  System.debug('Account created');\n}",
    "tableEnumOrId": "Account"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | String | 创建的 Apex 触发器 ID |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "创建成功",
    "data": "01qB0000008xw0IAA"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "创建 Apex 触发器失败：触发器名称已存在"
  }
  ```

#### 接口 7：查询 Apex 触发器详情

- **功能描述**：根据触发器名称查询 Apex 触发器详情
- **请求方式**：GET
- **请求路径**：`/tooling/apex-trigger/{name}`
- **权限要求**：`tooling:apex-trigger:query`
- **路径参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | name | String | 是 | Apex 触发器名称 |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | ApexTriggerVo | Apex 触发器详情对象 |
- **ApexTriggerVo 对象**：
  | 字段名 | 类型 | 说明 |
  |--------|------|------|
  | id | String | Apex 触发器 ID |
  | name | String | Apex 触发器名称 |
  | status | String | 状态 |
  | objectName | String | 关联对象名称 |
  | createdDate | String | 创建日期 |
  | lastModifiedDate | String | 最后修改日期 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {
      "id": "01qB0000008xw0IAA",
      "name": "MyTrigger",
      "status": "Active",
      "objectName": "Account",
      "createdDate": "2026-01-27T10:00:00.000Z",
      "lastModifiedDate": "2026-01-27T10:00:00.000Z"
    }
  }
  ```

#### 接口 8：分页查询 Apex 触发器列表

- **功能描述**：分页查询 Apex 触发器列表，支持按状态筛选
- **请求方式**：GET
- **请求路径**：`/tooling/apex-trigger`
- **权限要求**：`tooling:apex-trigger:list`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 默认值 | 说明 |
  |--------|------|------|---------|------|
  | status | String | 否 | - | 状态筛选条件 |
  | pageNum | Integer | 否 | 1 | 页码 |
  | pageSize | Integer | 否 | 10 | 每页数量 |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
  | data | List<ApexTriggerVo> | Apex 触发器列表 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": [
      {
        "id": "01qB0000008xw0IAA",
        "name": "MyTrigger",
        "status": "Active",
        "objectName": "Account",
        "createdDate": "2026-01-27T10:00:00.000Z",
        "lastModifiedDate": "2026-01-27T10:00:00.000Z"
      }
    ]
  }
  ```

#### 接口 9：更新 Apex 触发器

- **功能描述**：更新 Apex 触发器的触发器代码
- **请求方式**：PUT
- **请求路径**：`/tooling/apex-trigger`
- **权限要求**：`tooling:apex-trigger:update`
- **请求参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | id | String | 是 | Apex 触发器 ID |
  | body | String | 是 | Apex 触发器代码，不能为空 |
- **请求示例**：
  ```json
  {
    "id": "01qB0000008xw0IAA",
    "body": "trigger MyTrigger on Account (before insert, before update) {\n  System.debug('Account created or updated');\n}"
  }
  ```
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "更新成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "更新 Apex 触发器失败：触发器不存在"
  }
  ```

#### 接口 10：删除 Apex 触发器

- **功能描述**：根据 ID 删除 Apex 触发器
- **请求方式**：DELETE
- **请求路径**：`/tooling/apex-trigger/{id}`
- **权限要求**：`tooling:apex-trigger:delete`
- **路径参数**：
  | 参数名 | 类型 | 必填 | 说明 |
  |--------|------|------|------|
  | id | String | 是 | Apex 触发器 ID |
- **响应参数**：
  | 参数名 | 类型 | 说明 |
  |--------|------|------|
  | code | Integer | 状态码（200 成功，其他失败） |
  | msg | String | 提示信息 |
- **成功示例**：
  ```json
  {
    "code": 200,
    "msg": "删除成功"
  }
  ```
- **失败示例**：
  ```json
  {
    "code": 500,
    "msg": "删除 Apex 触发器失败：触发器不存在"
  }
  ```

## 错误码

### 通用错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 500 | 服务器内部错误 |

### Apex 类错误码

| 错误码 | 说明 |
|--------|------|
| 501 | Apex 类名称已存在 |
| 502 | Apex 类不存在 |
| 503 | 创建 Apex 类失败 |
| 504 | 更新 Apex 类失败 |
| 505 | 删除 Apex 类失败 |

### Apex 触发器错误码

| 错误码 | 说明 |
|--------|------|
| 511 | Apex 触发器名称已存在 |
| 512 | Apex 触发器不存在 |
| 513 | 创建 Apex 触发器失败 |
| 514 | 更新 Apex 触发器失败 |
| 515 | 删除 Apex 触发器失败 |

## 相关文档
- [需求文档](../requirements/REQ-014-1.md)
- [设计文档](../design/2026-01-27-014-1-Apex类与触发器基础管理-设计.md)
- [决策记录](../decisions/adr/2026-01-27-014-1-ADR-ToolingAPI客户端代码生成方案.md)
- [复盘文档](../retros/2026-01-27-014-1-retro.md)