# API 文档：日志记录功能

## 元数据
- **需求编号**：002-06
- **需求名称**：日志记录
- **版本号**：v1.0.0
- **创建时间**：2026-02-05
- **创建人**：AI Assistant

## API 概述

日志记录 API 提供 Salesforce Apex 日志的查询、调试头部管理和日志分类管理功能。该 API 为测试执行、代码覆盖率、Flow 覆盖率等功能提供日志追踪支持，便于问题排查和性能分析。

### 基础信息
- **基础路径**：`/apex`
- **权限前缀**：`apex:apexlog`
- **数据格式**：JSON
- **字符编码**：UTF-8

### 核心功能
1. **日志查询**：支持分页查询 Apex 日志记录，可按应用名称、位置、操作、状态、时间范围筛选
2. **日志详情**：根据 ID 查询单个日志记录的详细信息
3. **调试头部管理**：支持设置和清除调试头部信息
4. **日志分类管理**：支持日志分类的创建、查询、更新、删除操作

## 接口列表

### 1. 查询日志列表

- **功能描述**：分页查询 Apex 日志记录列表，支持多种筛选条件
- **请求方式**：GET
- **请求路径**：`/apex/apexlog/list`
- **权限要求**：`apex:apexlog:list`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 当前页码，默认 1 |
| pageSize | Integer | 否 | 每页记录数，默认 10 |
| application | String | 否 | 应用程序名称，支持模糊查询 |
| location | String | 否 | 位置信息，支持模糊查询 |
| operation | String | 否 | 操作类型，支持模糊查询 |
| status | String | 否 | 日志状态 |
| startTime | String | 否 | 开始时间（格式：yyyy-MM-dd HH:mm:ss） |
| endTime | String | 否 | 结束时间（格式：yyyy-MM-dd HH:mm:ss） |

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 100,
    "rows": [
      {
        "id": 1,
        "application": "Apex",
        "location": "SystemLog",
        "operation": "CodeUnit",
        "status": "Success",
        "logLength": 2048,
        "duration": 150,
        "startTime": "2026-02-05 10:30:00",
        "createTime": "2026-02-05 10:30:05"
      }
    ]
  }
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "查询日志列表失败"
}
```

---

### 2. 获取日志详情

- **功能描述**：根据 ID 查询单个日志记录的详细信息
- **请求方式**：GET
- **请求路径**：`/apex/apexlog/{id}`
- **权限要求**：`apex:apexlog:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 日志 ID（路径参数） |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 日志详情 |
| data.id | Long | 日志 ID |
| data.application | String | 应用程序名称 |
| data.location | String | 位置信息 |
| data.operation | String | 操作类型 |
| data.status | String | 日志状态 |
| data.logLength | Integer | 日志长度 |
| data.logContent | String | 日志内容 |
| data.duration | Long | 持续时间（毫秒） |
| data.startTime | String | 开始时间 |
| data.endTime | String | 结束时间 |
| data.userId | String | 用户 ID |
| data.createTime | String | 创建时间 |

#### 成功示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "application": "Apex",
    "location": "SystemLog",
    "operation": "CodeUnit",
    "status": "Success",
    "logLength": 2048,
    "logContent": "EXECUTION_STARTED...",
    "duration": 150,
    "startTime": "2026-02-05 10:30:00",
    "endTime": "2026-02-05 10:30:02",
    "userId": "005xx000001X9YZAA0",
    "createTime": "2026-02-05 10:30:05"
  }
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "日志不存在"
}
```

---

### 3. 设置调试头部

- **功能描述**：设置调试头部信息，包括日志分类和日志类型
- **请求方式**：POST
- **请求路径**：`/apex/apexlog/debugHeader`
- **权限要求**：`apex:apexlog:debug`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| logCategories | Array | 是 | 日志分类数组 |
| logCategories[].category | String | 是 | 日志分类（DB、APEX_CODE、VALIDATION、WORKFLOW、CALLOUT、SYSTEM） |
| logCategories[].level | String | 是 | 日志级别（None、Fine、Finer、Finest、Debug、Info、Warn、Error） |
| logType | String | 是 | 日志类型（ApexCode、ApexProfiling、Callout、Database、System） |

#### 请求示例

```json
{
  "logCategories": [
    {
      "category": "DB",
      "level": "FINE"
    },
    {
      "category": "APEX_CODE",
      "level": "DEBUG"
    },
    {
      "category": "VALIDATION",
      "level": "INFO"
    }
  ],
  "logType": "ApexCode"
}
```

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "调试头部设置成功",
  "data": null
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "调试头部设置失败: 无效的日志分类"
}
```

---

### 4. 清除调试头部

- **功能描述**：清除已设置的调试头部信息
- **请求方式**：DELETE
- **请求路径**：`/apex/apexlog/debugHeader`
- **权限要求**：`apex:apexlog:debug`

#### 请求参数

无

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "调试头部清除成功",
  "data": null
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "调试头部清除失败"
}
```

---

### 5. 查询日志分类列表

- **功能描述**：分页查询日志分类列表，支持按分类名称、级别筛选
- **请求方式**：GET
- **请求路径**：`/apex/apexlogcategory/list`
- **权限要求**：`apex:apexlogcategory:list`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| pageNum | Integer | 否 | 当前页码，默认 1 |
| pageSize | Integer | 否 | 每页记录数，默认 10 |
| categoryName | String | 否 | 分类名称，支持模糊查询 |
| categoryLevel | String | 否 | 日志级别 |
| enabled | Boolean | 否 | 是否启用 |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 响应数据 |
| data.total | Long | 总记录数 |
| data.rows | Array | 日志分类列表 |
| data.rows[].id | Long | 分类 ID |
| data.rows[].categoryName | String | 分类名称 |
| data.rows[].categoryLevel | String | 日志级别 |
| data.rows[].description | String | 描述 |
| data.rows[].enabled | Boolean | 是否启用 |
| data.rows[].createTime | String | 创建时间 |

#### 成功示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total": 10,
    "rows": [
      {
        "id": 1,
        "categoryName": "数据库操作",
        "categoryLevel": "FINE",
        "description": "记录数据库操作日志",
        "enabled": true,
        "createTime": "2026-02-05 10:00:00"
      }
    ]
  }
}
```

---

### 6. 获取日志分类详情

- **功能描述**：根据 ID 查询单个日志分类的详细信息
- **请求方式**：GET
- **请求路径**：`/apex/apexlogcategory/{id}`
- **权限要求**：`apex:apexlogcategory:query`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 分类 ID（路径参数） |

#### 响应参数

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | Integer | 状态码（200 成功，其他失败） |
| msg | String | 提示信息 |
| data | Object | 分类详情 |
| data.id | Long | 分类 ID |
| data.categoryName | String | 分类名称 |
| data.categoryLevel | String | 日志级别 |
| data.description | String | 描述 |
| data.enabled | Boolean | 是否启用 |
| data.createTime | String | 创建时间 |
| data.updateTime | String | 更新时间 |

#### 成功示例

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "id": 1,
    "categoryName": "数据库操作",
    "categoryLevel": "FINE",
    "description": "记录数据库操作日志",
    "enabled": true,
    "createTime": "2026-02-05 10:00:00",
    "updateTime": "2026-02-05 10:00:00"
  }
}
```

---

### 7. 创建日志分类

- **功能描述**：创建新的日志分类配置
- **请求方式**：POST
- **请求路径**：`/apex/apexlogcategory`
- **权限要求**：`apex:apexlogcategory:add`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| categoryName | String | 是 | 分类名称，长度 1-100 字符 |
| categoryLevel | String | 是 | 日志级别（None、Fine、Finer、Finest、Debug、Info、Warn、Error） |
| description | String | 否 | 描述，长度 0-500 字符 |
| enabled | Boolean | 否 | 是否启用，默认 true |

#### 请求示例

```json
{
  "categoryName": "数据库操作",
  "categoryLevel": "FINE",
  "description": "记录数据库操作日志",
  "enabled": true
}
```

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "创建成功",
  "data": null
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "创建失败: 分类名称已存在"
}
```

---

### 8. 更新日志分类

- **功能描述**：更新现有日志分类配置
- **请求方式**：PUT
- **请求路径**：`/apex/apexlogcategory`
- **权限要求**：`apex:apexlogcategory:edit`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 分类 ID |
| categoryName | String | 是 | 分类名称，长度 1-100 字符 |
| categoryLevel | String | 是 | 日志级别 |
| description | String | 否 | 描述，长度 0-500 字符 |
| enabled | Boolean | 否 | 是否启用 |

#### 请求示例

```json
{
  "id": 1,
  "categoryName": "数据库操作",
  "categoryLevel": "DEBUG",
  "description": "记录数据库操作日志（更新）",
  "enabled": true
}
```

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "更新成功",
  "data": null
}
```

---

### 9. 删除日志分类

- **功能描述**：删除日志分类配置（支持批量删除）
- **请求方式**：DELETE
- **请求路径**：`/apex/apexlogcategory/{ids}`
- **权限要求**：`apex:apexlogcategory:remove`

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| ids | String | 是 | 分类 ID 列表，多个 ID 用逗号分隔（路径参数） |

#### 响应参数

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

#### 成功示例

```json
{
  "code": 200,
  "msg": "删除成功",
  "data": null
}
```

#### 失败示例

```json
{
  "code": 500,
  "msg": "删除失败: 分类不存在"
}
```

---

## 错误码

### 日志记录错误码

| 错误码 | 错误名称 | 说明 | HTTP 状态码 |
|--------|---------|------|-------------|
| APEX_LOG_001 | LOG_NOT_FOUND | 日志不存在 | 404 |
| APEX_LOG_002 | LOG_QUERY_FAILED | 日志查询失败 | 500 |
| APEX_LOG_003 | DEBUG_HEADER_SET_FAILED | 调试头部设置失败 | 500 |
| APEX_LOG_004 | DEBUG_HEADER_CLEAR_FAILED | 调试头部清除失败 | 500 |
| APEX_LOG_005 | INVALID_LOG_CATEGORY | 无效的日志分类 | 400 |
| APEX_LOG_006 | INVALID_LOG_LEVEL | 无效的日志级别 | 400 |
| APEX_LOG_007 | INVALID_LOG_TYPE | 无效的日志类型 | 400 |

### 日志分类错误码

| 错误码 | 错误名称 | 说明 | HTTP 状态码 |
|--------|---------|------|-------------|
| APEX_LOG_CATEGORY_001 | CATEGORY_NOT_FOUND | 日志分类不存在 | 404 |
| APEX_LOG_CATEGORY_002 | CATEGORY_CREATE_FAILED | 日志分类创建失败 | 500 |
| APEX_LOG_CATEGORY_003 | CATEGORY_UPDATE_FAILED | 日志分类更新失败 | 500 |
| APEX_LOG_CATEGORY_004 | CATEGORY_DELETE_FAILED | 日志分类删除失败 | 500 |
| APEX_LOG_CATEGORY_005 | CATEGORY_NAME_EXISTS | 分类名称已存在 | 400 |

### 通用错误码

| 错误码 | 错误名称 | 说明 | HTTP 状态码 |
|--------|---------|------|-------------|
| 400 | BAD_REQUEST | 请求参数错误 | 400 |
| 401 | UNAUTHORIZED | 未授权 | 401 |
| 403 | FORBIDDEN | 禁止访问 | 403 |
| 404 | NOT_FOUND | 资源不存在 | 404 |
| 500 | INTERNAL_ERROR | 服务器内部错误 | 500 |

## 枚举值定义

### 日志分类（LogCategory）

| 值 | 说明 |
|----|------|
| DB | 数据库操作 |
| APEX_CODE | Apex 代码 |
| VALIDATION | 验证规则 |
| WORKFLOW | 工作流 |
| CALLOUT | 外部调用 |
| SYSTEM | 系统操作 |

### 日志级别（LogCategoryLevel）

| 值 | 说明 |
|----|------|
| None | 无 |
| Fine | 细粒度 |
| Finer | 更细粒度 |
| Finest | 最细粒度 |
| Debug | 调试 |
| Info | 信息 |
| Warn | 警告 |
| Error | 错误 |

### 日志类型（LogType）

| 值 | 说明 |
|----|------|
| ApexCode | Apex 代码日志 |
| ApexProfiling | Apex 性能分析日志 |
| Callout | 外部调用日志 |
| Database | 数据库操作日志 |
| System | 系统日志 |

### 日志状态（LogStatus）

| 值 | 说明 |
|----|------|
| Success | 成功 |
| Failed | 失败 |
| Pending | 进行中 |

## 相关文档

- [需求文档](../requirements/sub/2026-01-28-002-06-日志记录.md)
- [设计文档](../design/2026-02-03-002-06-日志记录-设计.md)
- [决策记录](../decisions/2026-02-03-002-06-ADR-日志记录技术选型.md)
- [SQL 脚本](../sql/2026-02-03-002-06-日志记录.sql)
- [提示词](../prompts/2026-02-03-002-06-prompt-日志记录.md)
- [变更日志](../changelog/2026-02-05-002-06-changelog.md)
- [会话记录](../sessions/2026-02-05-002-06-session.md)
- [复盘文档](../retros/2026-02-05-002-06-retro.md)

## 版本历史

| 版本号 | 日期 | 变更内容 | 作者 |
|--------|------|----------|------|
| v1.0.0 | 2026-02-05 | 初始版本，实现日志记录功能的所有 API 接口 | AI Assistant |