# Apex 业务逻辑执行与日志管理需求

## 元数据
- 需求编号：014-3
- 创建时间：2026-01-26
- 创建人：SSOT 架构师
- 状态：待开始
- 优先级：中
- 父需求：[REQ-014](../REQ-014.md)
- 关联代码：`com.sforce.soap.tooling.ExecuteAnonymousResult`, `com.sforce.soap.tooling.TraceFlag`

## 需求概述
实现“逻辑集中”的关键模块。允许 Java 端直接调用 Apex 逻辑（通过 Execute Anonymous 或 WebService），并能动态管理调试日志，以便在生产环境中排查问题。
**关联模块**：本需求与 `REQ-013-2`（Apex 动态代码执行与日志管理）高度重叠。经扫描，`ExecuteAnonymousResult` 等 SOAP 对象已存在。本需求应作为 `REQ-013-2` 的 Tooling API 实现版本（如果使用 Tooling API 的 `/executeAnonymous` 端点），或者复用 `REQ-013-2` 的实现。鉴于 Tooling API 提供了更丰富的调试上下文，建议在此处侧重于 **Tooling 特有的调试功能**（如 `TraceFlag` 管理）。

## 目标
1.  **动态执行**：通过 Tooling API 执行匿名 Apex（作为 Partner/Apex API 的补充）。
2.  **日志管理**：通过 Tooling API 的 `TraceFlag` 和 `DebugLevel` 对象，实现持久化的日志级别配置（不仅仅是单次执行的 Header）。
3.  **日志获取**：下载并解析 `ApexLog`。

## 功能需求
### 核心功能
1.  **匿名执行器 (Anonymous Executor)**
    - 接口：`executeApex(String apexCode)`
    - 实现：调用 `ToolingConnection.executeAnonymous(String code)`。
    - 差异：Tooling API 的执行结果可能包含行号覆盖率信息（需验证）。

2.  **持久化调试配置 (Persistent Debug Configuration)**
    - **管理 TraceFlag**：
        - CRUD 操作 `TraceFlag` 对象。
        - 关联 `DebugLevel`，设置 `ApexCode`, `Visualforce`, `System`, `Database` 等类别的日志级别。
        - 设置 `StartDate` 和 `ExpirationDate`，实现临时调试窗口。
    - **管理 DebugLevel**：
        - CRUD 操作 `DebugLevel` 对象，定义复用的日志配置模板。

3.  **日志获取 (Log Retriever)**
    - 接口：`getLog(String logId)`
    - 实现：通过 `ToolingConnection.retrieve()` 获取 `ApexLog` 对象的 `Body` 字段（需处理 Blob 类型）。

### 次要功能
- **日志分析**：简单的日志解析，提取 `USER_DEBUG` 行。

## 非功能需求
- **低侵入性**：设置 TraceFlag 后应及时清理（或利用 ExpirationDate 自动过期），避免日志空间爆满。
- **并发控制**：同一用户同一时间只能有一个生效的 TraceFlag，需处理冲突。

## 技术约束
- **依赖**：`com.sforce.soap.tooling.TraceFlag`, `com.sforce.soap.tooling.DebugLevel`, `com.sforce.soap.tooling.ApexLog`。
- **权限**：操作 TraceFlag 需要 `View All Data` 权限。

## 成功标准
1.  能够创建一个有效期为 30 分钟的 `TraceFlag`。
2.  执行一段 Apex 代码后，能在 `ApexLog` 表中查询到生成的日志 ID。
3.  能够下载并打印日志内容。

## 相关文档
- [设计文档](../design/2026-01-27-014-3-Apex业务逻辑执行与日志管理-设计.md)
- [决策记录](../decisions/adr/2026-01-27-014-3-ADR-Apex执行与日志管理技术选型.md)
- [提示词文档](../prompts/2026-01-27-014-3-prompt-Apex业务逻辑执行与日志管理.md)
- [变更日志](../changelog/2026-01-27-014-3-changelog.md)