83 lines
4.5 KiB
Markdown
83 lines
4.5 KiB
Markdown
# 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)
|