datai/docs/archive/REQ-014.md

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 Apex 类与触发器基础管理
   • 建立 Tooling API 连接。
   • 实现基础 CRUD。
2. REQ-014-2 符号表分析与 DTO 生成
   • 解析 SymbolTable。
   • 生成 Java DTO。
3. REQ-014-3 Apex 业务逻辑执行与日志管理
   • 匿名 Apex 执行。
   • 调试日志管理。
4. REQ-014-4 元数据容器与原子性部署
   • 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 并获取调试日志。