datai/docs/archive/REQ-013-4.md

# Apex 细粒度元数据操作需求

## 元数据
- 需求编号：013-4
- 父需求：013
- 创建时间：2026-01-26
- 创建人：SSOT 架构师
- 状态：进行中
- 优先级：中
- 关联代码：
    - `com.sforce.soap.apex.SoapConnection`
    - `com.sforce.soap.apex.CompileClasses_element`
    - `com.sforce.soap.apex.CompileClassResult`
    - `com.sforce.soap.apex.CompileTriggers_element`
    - `com.sforce.soap.apex.CompileTriggerResult`

## 需求概述
提供基于源码的细粒度编译功能，支持直接对 Apex 类和触发器进行即时编译（Compile），作为 Metadata API 部署（Deploy）的轻量级替代方案，适用于开发阶段的快速迭代。

## 目标
1.  实现 Apex 类的即时编译与保存。
2.  实现 Apex 触发器的即时编译与保存。
3.  **注意**：当前项目 `SoapConnection` 暂不支持 `deleteApex` 操作，故本需求不包含删除功能。

## 功能需求

### 1. 编译 Apex 类 (Compile Classes)
- **功能描述**：封装 `SoapConnection.compileClasses`。
- **接口定义**：
    ```java
    List<CompileResult> compileClasses(List<String> classSources);
    ```
- **输入参数**：
    - `classSources`: Apex 类的完整源码字符串列表（对应 SOAP `scripts` 字段，类型 `String[]`）。
- **处理逻辑**：
    1.  构建 `CompileClasses_element`。
    2.  设置 `scripts` 为传入的源码列表。
    3.  调用 `connection.compileClasses(scripts)`。
    4.  将返回的 `CompileClassResult[]` 转换为统一的 `CompileResult` VO (引用 REQ-013-1)。
- **输出**：
    - 返回 `CompileResult` 列表，包含每个类的 `success`, `id`, `name`, `problem`, `line`, `column`, `bodyCrc`, `problems`, `warnings` 等信息。

### 2. 编译 Apex 触发器 (Compile Triggers)
- **功能描述**：封装 `SoapConnection.compileTriggers`。
- **接口定义**：
    ```java
    List<CompileResult> compileTriggers(List<String> triggerSources);
    ```
- **输入参数**：
    - `triggerSources`: Apex 触发器的完整源码字符串列表（对应 SOAP `scripts` 字段，类型 `String[]`）。
- **处理逻辑**：
    1.  构建 `CompileTriggers_element`。
    2.  设置 `scripts` 为传入的源码列表。
    3.  调用 `connection.compileTriggers(scripts)`。
    4.  将返回的 `CompileTriggerResult[]` 转换为统一的 `CompileResult` VO。
- **输出**：
    - 返回 `CompileResult` 列表。

## 关键代码映射 (Source Code Mapping)

### SOAP 对象映射
| 逻辑概念 | SOAP 类名 | 关键字段 |
| :--- | :--- | :--- |
| 类编译请求 | `CompileClasses_element` | `scripts` (`String[]`) |
| 类编译响应 | `CompileClassResult` | `id`, `name`, `success`, `problem`, `line`, `column`, `bodyCrc`, `problems`, `warnings` |
| 触发器编译请求 | `CompileTriggers_element` | `scripts` (`String[]`) |
| 触发器编译响应 | `CompileTriggerResult` | `id`, `name`, `success`, `problem`, `line`, `column`, `bodyCrc`, `problems`, `warnings` |

## 异常处理规范
- **编译失败**：当 `CompileClassResult.success` 为 `false` 时，不抛出异常，而是返回包含错误信息的 `CompileResult` 对象，让前端展示具体的编译错误（行号、列号、错误消息）。
- **SOAP 故障**：网络或认证错误抛出 `ConnectionException`。

## 验证与测试
1.  **有效类编译**：传入有效的 Apex 类源码，断言返回 `success=true` 且 `id` 不为空。
2.  **无效类编译**：传入包含语法错误的源码，断言返回 `success=false`，且 `line` 和 `problem` 字段准确指示错误位置和原因。
3.  **有效触发器编译**：传入有效的 Apex 触发器源码，断言编译成功。
4.  **批量编译**：传入多个源码文件，验证批量处理能力。

## 相关文档
- [设计文档](../design/2026-01-27-013-4-Apex细粒度元数据操作设计.md)