datai/docs/archive/REQ-013-2.md

# Apex 动态代码执行与日志管理需求

## 元数据
- 需求编号：013-2
- 父需求：013
- 创建时间：2026-01-26
- 创建人：SSOT 架构师
- 状态：进行中
- 优先级：高
- 关联代码：
    - `com.sforce.soap.apex.ExecuteAnonymousResult`
    - `com.sforce.soap.apex.DebuggingHeader_element`
    - `com.sforce.soap.apex.LogCategory`
    - `com.sforce.soap.apex.LogCategoryLevel`
    - `com.sforce.soap.apex.DebuggingInfo_element`

## 需求概述
实现 `executeAnonymous` 的封装，允许用户执行任意 Apex 代码片段，并能够灵活控制和获取执行过程中的调试日志。通过封装 `DebuggingHeader` 实现细粒度的日志级别控制，并解析 `DebuggingInfo` 获取执行结果。

## 目标
1.  **统一执行接口**：封装底层的 SOAP 调用，提供友好的 Java 接口。
2.  **精确日志控制**：支持基于 `LogCategory` 和 `LogCategoryLevel` 的细粒度日志配置。
3.  **结果结构化**：将 SOAP 的 `ExecuteAnonymousResult` 转换为结构化的 Java 对象，区分编译错误和运行时异常。
4.  **日志内容提取**：自动从 SOAP Header 中提取并（可选）解析日志内容。

## 功能需求

### 1. 动态代码执行 (Anonymous Execution)
- **功能描述**：封装 `SoapConnection.executeAnonymous` 方法。
- **接口定义**：
    ```java
    ExecuteResult execute(String apexCode, DebuggingOptions options);
    ```
- **输入参数**：
    - `apexCode`: 待执行的 Apex 代码字符串。
    - `options`: 包含日志级别配置、模拟模式等选项。
- **处理逻辑**：
    1.  构建 `DebuggingHeader_element`，根据 `options` 设置日志级别。
    2.  调用 `connection.executeAnonymous(apexCode)`。
    3.  获取响应头中的 `DebuggingInfo_element`，提取 `debugLog`。
    4.  处理 `ExecuteAnonymousResult` 返回值：
        -   **编译检查**：检查 `isCompiled()`。
            -   若为 `false`，读取 `compileProblem`, `line`, `column`。
            -   抛出 `ApexCompilationException` (引用 REQ-013-1 定义)。
        -   **执行检查**：检查 `isSuccess()`。
            -   若为 `false`，读取 `exceptionMessage`, `exceptionStackTrace`。
            -   封装到 `ExecuteResult` 中作为运行时错误返回。
        -   **成功**：封装执行结果。
- **输出对象 (`ExecuteResult`)**：
    - `boolean success`: 执行是否成功。
    - `boolean compiled`: 代码是否编译成功。
    - `String debugLog`: 完整的调试日志内容。
    - `String exceptionMessage`: 运行时异常信息（如有）。
    - `String exceptionStackTrace`: 运行时堆栈跟踪（如有）。
    - `String compileProblem`: 编译错误描述（如有）。
    - `int compileLine`: 编译错误行号（如有）。
    - `int compileColumn`: 编译错误列号（如有）。
    - `long executionTime`: (可选) 从日志或响应时间估算的执行耗时。

### 2. 日志级别配置 (Logging Configuration)
- **功能描述**：构建 `DebuggingHeader`，支持两种日志配置模式。
- **配置模式**：
    -   **细粒度模式**：使用 `categories` 字段，基于 `LogCategory` 和 `LogCategoryLevel` 的精确配置。
    -   **预设模式**：使用 `debugLevel` 字段，基于 `LogType` 的快速配置。
- **枚举定义**：
    -   **`LogCategory`** (对应 `com.sforce.soap.apex.LogCategory`):
        -   `Db`, `Workflow`, `Validation`, `Callout`, `Apex_code`, `Apex_profiling`, `Visualforce`, `System`
        -   `Wave`, `Nba`, `Data_access`, `All`
    -   **`LogCategoryLevel`** (对应 `com.sforce.soap.apex.LogCategoryLevel`):
        -   `None`, `Finest`, `Finer`, `Fine`, `Debug`, `Info`, `Warn`, `Error`
    -   **`LogType`** (对应 `com.sforce.soap.apex.LogType`):
        -   `None`, `Debugonly`, `Db`, `Profiling`, `Callout`, `Detail`
- **配置模板**：
    -   **细粒度模板**：
        -   `DEBUG_ONLY`: `Apex_code`=DEBUG, `System`=DEBUG, 其他=INFO
        -   `DB_ANALYSIS`: `Db`=FINEST, `Apex_profiling`=FINEST, 其他=INFO
    -   **预设模板**：
        -   `DEBUGONLY`: 使用 `LogType.Debugonly`
        -   `DB`: 使用 `LogType.Db`
        -   `PROFILING`: 使用 `LogType.Profiling`

### 3. 日志获取与解析 (Log Retrieval & Parsing)
- **功能描述**：处理 `DebuggingInfo_element`。
- **详细要求**：
    -   **自动提取**：每次执行后，自动检查 SOAP 响应头，提取 `debugLog` 字符串。
    -   **日志解析器 (LogParser)** (可选组件):
        -   `List<String> getUserDebugs(String log)`: 提取所有 `USER_DEBUG` 行。
        -   `Map<String, String> getLimits(String log)`: 提取 `LIMIT_USAGE` 部分（如 "Number of SOQL queries: 2 out of 100"）。

## 关键代码映射 (Source Code Mapping)

### SOAP 对象映射
| 逻辑概念 | SOAP 类名 | 关键字段 |
| :--- | :--- | :--- |
| 执行结果 | `ExecuteAnonymousResult` | `compiled`, `compileProblem`, `line`, `column`, `success`, `exceptionMessage`, `exceptionStackTrace` |
| 调试头 | `DebuggingHeader_element` | `categories` (`LogInfo[]`), `debugLevel` (`LogType`) |
| 日志信息配置 | `LogInfo` | `category` (`LogCategory`), `level` (`LogCategoryLevel`) |
| 调试信息返回 | `DebuggingInfo_element` | `debugLog` |

### 枚举值对应
- **LogCategory**: 严格匹配 `com.sforce.soap.apex.LogCategory` 的枚举值（12个值：Db, Workflow, Validation, Callout, Apex_code, Apex_profiling, Visualforce, System, Wave, Nba, Data_access, All）。
- **LogCategoryLevel**: 严格匹配 `com.sforce.soap.apex.LogCategoryLevel` 的枚举值（8个值：None, Finest, Finer, Fine, Debug, Info, Warn, Error）。
- **LogType**: 严格匹配 `com.sforce.soap.apex.LogType` 的枚举值（6个值：None, Debugonly, Db, Profiling, Callout, Detail）。

## 异常处理规范
1.  **编译异常**：当 `ExecuteAnonymousResult.compiled == false` 时，必须阻断流程，抛出受检异常 `ApexCompilationException`，包含具体的行列号和错误信息。
2.  **运行时异常**：当 `ExecuteAnonymousResult.success == false` 时，不抛出异常，而是将错误信息封装在 `ExecuteResult` 中返回，因为这属于代码执行的预期结果之一（例如代码逻辑抛出异常）。
3.  **SOAP 故障**：网络或认证错误抛出 `ConnectionException` 或运行时异常。

## 验证与测试
1.  **基础执行**：执行 `System.debug('Hello');`，断言 `success=true` 且 `debugLog` 包含 'Hello'。
2.  **编译错误**：执行 `In valid Code;`，断言抛出 `ApexCompilationException` 且包含行号。
3.  **运行时错误**：执行 `throw new MyException('Test');`，断言 `success=false` 且 `exceptionMessage` 包含 'Test'。
4.  **日志级别**：设置 `Apex_code=FINEST`，执行代码，断言日志长度或内容详细程度增加。

## 相关文档
- [设计文档](../design/2026-01-28-013-2-Apex动态代码执行与日志管理设计.md)
- [提示词文档](../prompts/2026-01-27-013-2-prompt-Apex动态代码执行与日志管理.md)
- [变更日志](../changelog/2026-01-27-013-2-changelog.md)
- [复盘文档](../retros/2026-01-27-013-2-retro.md)
- [API 文档](../api-docs/apex/2026-01-27-013-2-api.md)