# 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 并获取调试日志。