# Apex 编译器接口与错误处理需求

## 元数据
- 需求编号：013-1
- 父需求：013
- 创建时间：2026-01-26
- 创建人：SSOT 架构师
- 状态：进行中
- 优先级：高

## 需求概述
作为 Apex 开发工具包的基础，需要优先实现编译器接口和错误处理对象的封装。这将为后续的动态执行、单元测试和元数据操作提供统一的数据结构和异常处理机制。

## 目标
1.  **统一错误模型**：将 Salesforce SOAP API 返回的各类错误（编译错误、运行时错误、测试失败）转换为统一的 Java 对象模型。
2.  **封装 WSDL 工具**：实现 `wsdlToApex` 功能，支持从 WSDL 生成 Apex 代码。
3.  **提供基础 VO/DTO**：定义供上层调用的值对象（Value Object），屏蔽底层 SOAP 对象的复杂性。

## 功能需求

### 1. 统一错误模型 (Unified Error Model)
- **功能描述**：定义标准化的错误对象，屏蔽底层 SOAP 对象的差异。
- **详细要求**：
    -   创建 `ApexCompileIssue` 类，映射 `com.sforce.soap.apex.CompileIssue`。
    -   字段包含：
        -   `line` (行号)：对应 SOAP `line` 字段。
        -   `column` (列号)：对应 SOAP `column` 字段。
        -   `problem` (错误描述)：对应 SOAP `message` 字段。
        -   `className` (类名/文件名)：在批量编译时关联到具体文件。
    -   创建 `ApexException` 体系，区分：
        -   `ApexCompilationException`: 编译期错误，包含 `List<ApexCompileIssue>`。
        -   `ApexRuntimeException`: 运行期错误。
        -   `ApexConnectionException`: 连接/网络错误。

### 2. 编译器结果封装 (Compiler Result Encapsulation)
- **功能描述**：封装编译结果，提供更友好的访问方式。
- **详细要求**：
    - 创建 `CompileResult` 类，映射 `com.sforce.soap.apex.CompileClassResult` 和 `com.sforce.soap.apex.CompileTriggerResult`。
    - 字段包含：
        -   `success` (是否成功)：对应 SOAP `success` 字段。
        -   `id` (元数据 ID)：对应 SOAP `id` 字段。
        -   `name` (类名/触发器名)：对应 SOAP `name` 字段。
        -   `bodyCrc` (内容校验码)：对应 SOAP `bodyCrc` 字段。
        -   `line` (错误行号)：对应 SOAP `line` 字段（当 `success` 为 `false` 时）。
        -   `column` (错误列号)：对应 SOAP `column` 字段（当 `success` 为 `false` 时）。
        -   `problem` (错误描述)：对应 SOAP `problem` 字段（当 `success` 为 `false` 时）。
        -   `problems` (错误列表 `List<ApexCompileIssue>`)：对应 SOAP `problems` 字段。
        -   `warnings` (警告列表 `List<ApexCompileIssue>`)：对应 SOAP `warnings` 字段。

### 3. WSDL 转 Apex (WSDL to Apex)
- **功能描述**：封装 `SoapConnection.wsdlToApex` 方法。
- **详细要求**：
    -   输入：WSDL 内容字符串或 URL。
    -   输出：`WsdlToApexResult` 封装对象。
    -   字段包含：
        -   `success` (是否成功)：对应 SOAP `success` 字段。
        -   `apexScripts` (生成的 Apex 代码)：对应 SOAP `apexScripts` 数组，转换为 `List<String>`。
        -   `errors` (错误信息)：对应 SOAP `errors` 数组，转换为 `List<String>`。
    -   异常处理：处理 WSDL 解析错误和生成错误，统一抛出 `ApexCompilationException`。

## 非功能需求
- **无状态**：对象设计应为无状态，便于序列化和传输。
- **易用性**：提供 Builder 模式或静态工厂方法创建对象。
- **兼容性**：字段映射需兼容 Salesforce API v58.0+。

## 技术约束
- 位于 `datai-salesforce-apex` 模块。
- 包路径：`com.datai.apex.model` (模型), `com.datai.apex.core` (接口)。
- 依赖 `com.force.api:force-wsc`。

## 成功标准
1.  能够将 `CompileIssue` SOAP 对象正确转换为 `ApexCompileIssue` POJO。
2.  能够将 `CompileClassResult` 和 `CompileTriggerResult` 统一转换为 `CompileResult` 对象。
3.  能够通过 Service 接口传入 WSDL 内容，返回生成的 Apex 代码列表或错误信息。

## 相关文档
- [设计文档](../design/2026-01-28-013-1-Apex编译器接口设计.md)
- [决策记录](../decisions/2026-01-28-013-1-ADR-Apex编译器接口技术选型.md)
- [提示词文档](../prompts/2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md)
- [变更日志](../changelog/2026-01-28-013-1-changelog.md)
- [复盘文档](../retros/2026-01-28-013-1-retro.md)
- [API 文档](../api-docs/2026-01-28-013-1-api.md)