61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
# 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)
|