84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# Apex 业务逻辑与元数据管理需求
|
||
|
||
## 元数据
|
||
- 需求编号：014
|
||
- 创建时间：2026-01-26
|
||
- 创建人：SSOT 架构师
|
||
- 状态：进行中
|
||
- 优先级：高
|
||
- 关联模块：`datai-salesforce-tooling`
|
||
- 关联代码：`com.sforce.soap.tooling.*`
|
||
|
||
## 需求概述
|
||
构建基于 Salesforce Tooling API 的元数据管理与业务逻辑执行模块。该模块旨在弥补 Partner API 的不足，通过管理 Apex 类和触发器，实现事务原子性、复杂 DTO 传输、逻辑集中化以及权限控制等高级集成模式。
|
||
|
||
## 目标
|
||
1. **高级集成能力**：提供工具链支持，使开发者能轻松部署和管理 Apex Web Services。
|
||
2. **开发效率提升**：通过 Tooling API 自动化管理 Apex 代码，支持快速迭代。
|
||
3. **架构优化**：支持将复杂业务逻辑下沉至 Salesforce 端（Logic Centralization），减少网络交互。
|
||
|
||
## 功能需求与子需求拆分
|
||
|
||
本需求已拆分为以下独立子需求，请按顺序实施：
|
||
|
||
1. **[REQ-014-1](./REQ-014-1.md) Apex 类与触发器基础管理**
|
||
- 建立 Tooling API 连接。
|
||
- 实现基础 CRUD。
|
||
2. **[REQ-014-2](./REQ-014-2.md) 符号表分析与 DTO 生成**
|
||
- 解析 SymbolTable。
|
||
- 生成 Java DTO。
|
||
3. **[REQ-014-3](./REQ-014-3.md) Apex 业务逻辑执行与日志管理**
|
||
- 匿名 Apex 执行。
|
||
- 调试日志管理。
|
||
4. **[REQ-014-4](./REQ-014-4.md) 元数据容器与原子性部署**
|
||
- MetadataContainer 管理。
|
||
- 原子性事务部署。
|
||
|
||
### 1. Apex 类与触发器管理 (Metadata Management)
|
||
- **功能描述**：使用 Tooling API 创建、更新、查询 Apex 类和触发器。
|
||
- **业务价值**：
|
||
- **事务原子性 (Transaction Atomicity)**：允许开发者编写包含多步 DML 操作的 Apex 方法（如 `createOrder`），并通过 Tooling API 部署。Salesforce 端保证事务原子性，Java 端只需一次调用。
|
||
- **权限控制 (System/User Mode)**：支持部署带有 `with sharing` 或 `without sharing` 关键字的类，实现灵活的权限上下文切换。
|
||
- **详细要求**：
|
||
- 封装 `create()`, `update()` 方法操作 `ApexClass` 和 `ApexTrigger` 对象。
|
||
- 支持使用 `MetadataContainer` 进行原子性部署（如果需要批量更新）。
|
||
|
||
### 2. 符号表分析 (Symbol Table Analysis)
|
||
- **功能描述**：使用 Tooling API 查询 `ApexClass` 的 `SymbolTable`。
|
||
- **业务价值**：
|
||
- **自定义 DTO (Custom DTOs)**：通过解析 `SymbolTable` 中的 `innerClasses` 和 `variables`，自动识别 Apex 端定义的复杂数据结构（UserSummary 等）。
|
||
- **客户端生成**：为 Java 端生成对应的 VO/DTO 对象，实现强类型调用，避免处理弱类型的 Map 或 JSON。
|
||
- **详细要求**：
|
||
- 提供 `getSymbolTable(String className)` 接口。
|
||
- 解析 `SymbolTable` 结构，提取方法签名、参数类型和返回值类型。
|
||
|
||
### 3. 业务逻辑执行 (Business Logic Execution)
|
||
- **功能描述**：封装 `executeAnonymous` 或提供对 Apex WebService 的动态调用支持。
|
||
- **业务价值**：
|
||
- **逻辑集中 (Logic Centralization)**：将复杂的计算规则（如价格计算）封装在 Apex 中，Java 端仅负责调用。
|
||
- **性能优化**：减少 "Chatty Calls"，将多次 Partner API 调用合并为一次 Apex 调用。
|
||
- **详细要求**：
|
||
- 虽然 `executeAnonymous` 在 Apex API 中也有，但 Tooling API 提供了更丰富的调试上下文。
|
||
- 支持通过 Tooling API 获取执行日志和覆盖率信息。
|
||
|
||
### 4. 调试与日志管理 (Debug & Logs)
|
||
- **功能描述**：管理 `TraceFlag` 和 `DebugLevel`。
|
||
- **业务价值**：
|
||
- 支持在调用复杂业务逻辑时捕获详细的调试日志，便于排查原子性事务中的故障。
|
||
- **详细要求**：
|
||
- 提供设置用户或类级别的调试日志功能的接口。
|
||
|
||
## 非功能需求
|
||
- **兼容性**：支持 Salesforce Tooling API v60.0+。
|
||
- **性能**：符号表查询应支持缓存，避免频繁调用 Tooling API。
|
||
- **安全性**：确保元数据操作符合 Salesforce 安全最佳实践。
|
||
|
||
## 技术约束
|
||
- 必须基于 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\soap\tooling` 下的源码生成客户端代码。
|
||
- 依赖 `datai-salesforce-soap` 模块提供的基础连接能力（如果共享）。
|
||
|
||
## 成功标准
|
||
1. 能够通过模块 API 创建一个新的 Apex 类。
|
||
2. 能够获取指定 Apex 类的符号表，并解析出内部类的结构。
|
||
3. 能够设置 TraceFlag 并获取调试日志。
|