307 lines
15 KiB
Markdown
307 lines
15 KiB
Markdown
|
# REQ-013-1 Apex 编译器接口与错误处理需求 - 会话记录
|
|||
|
|
|
|||
|
|
## 元数据
|
|||
|
|
- 需求编号：013-1
|
|||
|
|
- 创建时间：2026-01-28
|
|||
|
|
- 结束时间：2026-01-28
|
|||
|
|
- 当前阶段：阶段 9：闭环复盘和接口文档
|
|||
|
|
- 状态：已完成
|
|||
|
|
|
|||
|
|
## 需求描述
|
|||
|
|
实现 Apex 编译器接口与错误处理功能，包括：
|
|||
|
|
1. 统一错误模型：创建 ApexCompileIssue 类，映射 Salesforce SOAP API 的 CompileIssue
|
|||
|
|
2. 编译器结果封装：创建 CompileResult 类，封装编译结果
|
|||
|
|
3. WSDL 转 Apex：创建 WsdlToApexResult 类，封装 WSDL 转换结果
|
|||
|
|
4. 异常体系：创建 ApexException 及其子类，区分不同类型的错误
|
|||
|
|
5. 服务接口：创建 ApexCompilerService 和 WsdlConverterService 接口
|
|||
|
|
|
|||
|
|
## 执行阶段
|
|||
|
|
|
|||
|
|
### 阶段 1：需求定义
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **需求文档**：[REQ-013-1.md](../requirements/REQ-013-1.md)
|
|||
|
|
- **关键需求**：
|
|||
|
|
- 统一错误模型（ApexCompileIssue、ApexException 体系）
|
|||
|
|
- 编译器结果封装（CompileResult）
|
|||
|
|
- WSDL 转 Apex（WsdlToApexResult）
|
|||
|
|
|
|||
|
|
### 阶段 2：方案设计
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **设计文档**：[2026-01-28-013-1-Apex编译器接口设计.md](../design/2026-01-28-013-1-Apex编译器接口设计.md)
|
|||
|
|
- **关键设计决策**：
|
|||
|
|
- 使用 force-wsc 库与 Salesforce SOAP API 集成
|
|||
|
|
- 创建统一的错误模型和异常体系
|
|||
|
|
- 实现编译结果转换算法
|
|||
|
|
- 设计 RESTful API 接口
|
|||
|
|
- 采用 Spring Boot 和 Lombok 框架
|
|||
|
|
|
|||
|
|
### 阶段 3：方案决策
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **决策文档**：[2026-01-28-013-1-ADR-Apex编译器接口技术选型.md](../decisions/2026-01-28-013-1-ADR-Apex编译器接口技术选型.md)
|
|||
|
|
- **关键决策**：
|
|||
|
|
- 使用 force-wsc 库与 Salesforce SOAP API 集成
|
|||
|
|
- 使用统一的异常体系（ApexException 及其子类）
|
|||
|
|
- 创建统一的 CompileResult 模型封装 SOAP API 返回结果
|
|||
|
|
|
|||
|
|
### 阶段 4：数据库结构生成
|
|||
|
|
- **状态**：已完成（跳过）
|
|||
|
|
- **说明**：需求不涉及数据库变更，直接进入阶段 5
|
|||
|
|
|
|||
|
|
### 阶段 5：提示词生成
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **提示词文档**：[2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md](../prompts/2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md)
|
|||
|
|
- **提示词内容摘要**：
|
|||
|
|
- 引用真源（需求文档、设计文档、决策记录）
|
|||
|
|
- 定义输出格式（模型层、异常体系、接口层、实现层、单元测试）
|
|||
|
|
- 定义代码规范（命名规范、注释规范、代码格式、导入规范、异常处理规范）
|
|||
|
|
- 定义测试要求（覆盖率、测试场景、测试框架、测试用例命名）
|
|||
|
|
- 注意事项（Salesforce API 集成、错误处理、性能优化、安全性、兼容性）
|
|||
|
|
|
|||
|
|
### 阶段 6：代码生成
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **代码生成器使用**：不涉及数据库表新增，未使用代码生成器
|
|||
|
|
- **生成的代码文件**：
|
|||
|
|
- 模型层：
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/ApexCompileIssue.java` - 编译问题模型
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/CompileResult.java` - 编译结果模型
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/WsdlToApexResult.java` - WSDL 转换结果模型
|
|||
|
|
- 异常体系：
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexException.java` - 基类异常
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexCompilationException.java` - 编译异常
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexRuntimeException.java` - 运行时异常
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexConnectionException.java` - 连接异常
|
|||
|
|
- 接口层：
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/core/ApexCompilerService.java` - 编译器服务接口
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/core/WsdlConverterService.java` - WSDL 转换服务接口
|
|||
|
|
- 实现层：
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/impl/ApexCompilerServiceImpl.java` - 编译器服务实现
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/impl/WsdlConverterServiceImpl.java` - WSDL 转换服务实现
|
|||
|
|
- 单元测试：
|
|||
|
|
- `datai-salesforce-apex/src/test/java/com/datai/apex/impl/ApexCompilerServiceTest.java` - 编译器服务测试
|
|||
|
|
- `datai-salesforce-apex/src/test/java/com/datai/apex/impl/WsdlConverterServiceTest.java` - WSDL 转换服务测试
|
|||
|
|
|
|||
|
|
### 阶段 7：记录当前会话
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **会话文档**：本文档
|
|||
|
|
- **关键决策**：完整记录了当前会话的所有信息
|
|||
|
|
|
|||
|
|
### 阶段 8：变更记录与归档
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **变更日志**：[2026-01-28-013-1-changelog.md](../changelog/2026-01-28-013-1-changelog.md)
|
|||
|
|
- **变更内容**：
|
|||
|
|
- 新增功能：统一错误模型、编译器结果封装、WSDL 转 Apex 结果封装、异常体系、服务接口、服务实现、单元测试
|
|||
|
|
- 新增文档：需求文档、设计文档、决策记录、提示词文档、会话记录、变更日志
|
|||
|
|
- 新增代码文件：13 个文件（模型层 3 个、异常体系 4 个、接口层 2 个、实现层 2 个、单元测试 2 个）
|
|||
|
|
- 影响范围：datai-salesforce-apex 模块
|
|||
|
|
- 相关文档：需求文档、设计文档、决策记录、提示词文档、会话记录
|
|||
|
|
- **更新内容**：
|
|||
|
|
- 创建变更日志文档
|
|||
|
|
- 更新根目录 CHANGELOG.md
|
|||
|
|
- 更新索引文件，添加变更日志链接
|
|||
|
|
- 更新需求文档，添加变更日志引用
|
|||
|
|
- 更新会话记录，更新阶段 8 信息
|
|||
|
|
|
|||
|
|
### 阶段 9：闭环复盘和接口文档
|
|||
|
|
- **状态**：已完成
|
|||
|
|
- **复盘文档**：[2026-01-28-013-1-retro.md](../retros/2026-01-28-013-1-retro.md)
|
|||
|
|
- **API 文档**：[2026-01-28-013-1-api.md](../api-docs/2026-01-28-013-1-api.md)
|
|||
|
|
- **复盘内容**：
|
|||
|
|
- 目标与实际产出对比
|
|||
|
|
- 成功经验（5 条）
|
|||
|
|
- 改进点（5 条）
|
|||
|
|
- 问题分析（无重大问题）
|
|||
|
|
- 行动计划（5 条）
|
|||
|
|
- 提取模式（3 条有效的 Prompt 技巧，3 个避免的坑）
|
|||
|
|
- 模板迭代（Spring Boot 框架规范、Lombok 框架规范、测试要求详细化、验证步骤明确化）
|
|||
|
|
- **API 文档内容**：
|
|||
|
|
- ApexCompilerService 接口（compileClasses、compileTriggers）
|
|||
|
|
- WsdlConverterService 接口（convertWsdl）
|
|||
|
|
- 异常体系（ApexException、ApexCompilationException、ApexRuntimeException、ApexConnectionException）
|
|||
|
|
- 错误码（编译错误码、连接错误码、转换错误码）
|
|||
|
|
- **更新内容**：
|
|||
|
|
- 创建复盘文档
|
|||
|
|
- 创建 API 文档
|
|||
|
|
- 更新索引文件，添加复盘和 API 文档链接
|
|||
|
|
- 更新需求文档，添加复盘和 API 文档引用
|
|||
|
|
- 更新会话记录，更新阶段 9 信息
|
|||
|
|
|
|||
|
|
## 对话记录
|
|||
|
|
|
|||
|
|
2026-01-28 用户：结合 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\reference-code\sforce\soap\apex` apex源代码实际情况，优化需求文档 `d:\idea_demo\datai\datai-scenes\datai-scene-salesforce\docs\requirements\REQ-013-1.md`
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，我将根据实际的 Apex 源代码优化需求文档 REQ-013-1.md。让我先读取相关源代码文件。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已读取 CompileClassResult.java、CompileTriggerResult.java、CompileClasses_element.java、CompileTriggers_element.java 等源代码文件，了解了实际的字段和结构。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新需求文档 REQ-013-1.md，添加了以下字段：
|
|||
|
|
- CompileResult：name、bodyCrc、problems[]、warnings[]
|
|||
|
|
- ApexCompileIssue：className
|
|||
|
|
- WsdlToApexResult：apexScripts[]、errors[]
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新索引文件 docs/index.md，添加了新设计文档的链接。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新需求文档 REQ-013-1.md，添加了设计文档引用。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已创建会话记录文件 2026-01-28-013-1-session.md。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：需求文档优化完成。内容是否达标？是否进入下一阶段？
|
|||
|
|
|
|||
|
|
2026-01-28 用户：进入下一阶段（方案决策）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，进入阶段 3：方案决策。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：让我先读取设计文档，分析需要决策的关键技术方案。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已读取设计文档，识别了三个关键决策点：
|
|||
|
|
1. 使用 force-wsc 库与 Salesforce SOAP API 集成
|
|||
|
|
2. 使用统一的异常体系（ApexException 及其子类）
|
|||
|
|
3. 创建统一的 CompileResult 模型封装 SOAP API 返回结果
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已搜索已有的 ADR 记录，确认没有冲突。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已创建决策记录 2026-01-28-013-1-ADR-Apex编译器接口技术选型.md，包含：
|
|||
|
|
- 决策 1：使用 force-wsc 库与 Salesforce SOAP API 集成
|
|||
|
|
- 决策 2：使用统一的异常体系
|
|||
|
|
- 决策 3：创建统一的 CompileResult 模型
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新索引文件 docs/index.md，添加了新决策记录的链接。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新设计文档，添加了决策记录引用。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新会话记录 2026-01-28-013-1-session.md，更新了阶段 3 的完成状态和关键决策。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：决策记录已创建：[链接]。决策是否合理？是否进入下一阶段（数据库结构生成）？
|
|||
|
|
|
|||
|
|
2026-01-28 用户：进入下一阶段（数据库结构生成）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，进入阶段 4：数据库结构生成。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：让我先分析需求是否涉及数据库变更。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已读取设计文档，分析发现：
|
|||
|
|
- 需求主要涉及 Java 模型层、异常体系、服务接口和实现
|
|||
|
|
- 所有数据都是通过 Salesforce SOAP API 实时获取和处理的
|
|||
|
|
- 不需要在本地数据库中存储任何数据
|
|||
|
|
|
|||
|
|
2026-01-28 AI：结论：需求 REQ-013-1 不涉及数据库变更。跳过阶段 4（数据库结构生成），直接进入阶段 5（提示词生成）。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：是否进入下一阶段（提示词生成）？
|
|||
|
|
|
|||
|
|
2026-01-28 用户：进入下一阶段（提示词生成）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，进入阶段 5：提示词生成。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：让我先读取需求文档和设计文档，分析需求的核心任务。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已读取需求文档 REQ-013-1.md 和设计文档 2026-01-28-013-1-Apex编译器接口设计.md。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已生成提示词文档 2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md，包含：
|
|||
|
|
- 引用真源（需求文档、设计文档、决策记录）
|
|||
|
|
- 需求描述
|
|||
|
|
- 设计方案
|
|||
|
|
- 输出格式要求（模型层、异常体系、接口层、实现层、单元测试）
|
|||
|
|
- 代码规范要求（命名规范、注释规范、代码格式、导入规范、异常处理规范）
|
|||
|
|
- 测试要求（覆盖率、测试场景、测试框架、测试用例命名）
|
|||
|
|
- 注意事项（Salesforce API 集成、错误处理、性能优化、安全性、兼容性）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新索引文件 docs/index.md，添加了新提示词的链接。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新需求文档 REQ-013-1.md，添加了提示词引用。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新会话记录 2026-01-28-013-1-session.md，更新了阶段 5 的完成状态和提示词内容摘要。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：提示词已生成：[链接]。提示词是否合适？是否进入下一阶段（代码生成）？
|
|||
|
|
|
|||
|
|
2026-01-28 用户：进入下一阶段（代码生成）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，进入阶段 6：执行代码生成。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：现状：已完成需求定义、方案设计、方案决策、数据库结构生成（跳过）和提示词生成
|
|||
|
|
|
|||
|
|
2026-01-28 AI：目标：根据提示词生成符合项目规范的代码文件
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已读取提示词文档 2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已检查 datai-salesforce-apex 模块，确认模块已存在。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已参考 datai-salesforce-tooling 模块的代码风格。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已生成以下代码文件：
|
|||
|
|
|
|||
|
|
**模型层（3个文件）：**
|
|||
|
|
- ApexCompileIssue.java - 编译问题模型
|
|||
|
|
- CompileResult.java - 编译结果模型
|
|||
|
|
- WsdlToApexResult.java - WSDL 转换结果模型
|
|||
|
|
|
|||
|
|
**异常体系（4个文件）：**
|
|||
|
|
- ApexException.java - 基类异常
|
|||
|
|
- ApexCompilationException.java - 编译异常
|
|||
|
|
- ApexRuntimeException.java - 运行时异常
|
|||
|
|
- ApexConnectionException.java - 连接异常
|
|||
|
|
|
|||
|
|
**接口层（2个文件）：**
|
|||
|
|
- ApexCompilerService.java - 编译器服务接口
|
|||
|
|
- WsdlConverterService.java - WSDL 转换服务接口
|
|||
|
|
|
|||
|
|
**实现层（2个文件）：**
|
|||
|
|
- ApexCompilerServiceImpl.java - 编译器服务实现
|
|||
|
|
- WsdlConverterServiceImpl.java - WSDL 转换服务实现
|
|||
|
|
|
|||
|
|
**单元测试（2个文件）：**
|
|||
|
|
- ApexCompilerServiceTest.java - 编译器服务测试
|
|||
|
|
- WsdlConverterServiceTest.java - WSDL 转换服务测试
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新会话记录 2026-01-28-013-1-session.md，更新了阶段 6 的完成状态和生成的代码文件列表。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：代码生成完成。代码是否正确？是否进入下一阶段（会话记录）？
|
|||
|
|
|
|||
|
|
2026-01-28 用户：进入下一阶段（会话记录）
|
|||
|
|
|
|||
|
|
2026-01-28 AI：好的，进入阶段 7：记录当前会话。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：已更新会话记录 2026-01-28-013-1-session.md，添加了完整的对话记录。
|
|||
|
|
|
|||
|
|
2026-01-28 AI：会话记录已更新：[链接]。会话记录是否完整？是否进入下一阶段（变更记录与归档）？
|
|||
|
|
|
|||
|
|
## 生成的文档
|
|||
|
|
|
|||
|
|
### 需求文档
|
|||
|
|
- [REQ-013-1.md](../requirements/REQ-013-1.md)
|
|||
|
|
|
|||
|
|
### 设计文档
|
|||
|
|
- [2026-01-28-013-1-Apex编译器接口设计.md](../design/2026-01-28-013-1-Apex编译器接口设计.md)
|
|||
|
|
|
|||
|
|
### 决策记录
|
|||
|
|
- [2026-01-28-013-1-ADR-Apex编译器接口技术选型.md](../decisions/2026-01-28-013-1-ADR-Apex编译器接口技术选型.md)
|
|||
|
|
|
|||
|
|
### 提示词
|
|||
|
|
- [2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md](../prompts/2026-01-28-013-1-prompt-Apex编译器接口与错误处理.md)
|
|||
|
|
|
|||
|
|
## 生成的代码文件
|
|||
|
|
|
|||
|
|
### 模型层
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/ApexCompileIssue.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/CompileResult.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/model/WsdlToApexResult.java`
|
|||
|
|
|
|||
|
|
### 异常体系
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexException.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexCompilationException.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexRuntimeException.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/exception/ApexConnectionException.java`
|
|||
|
|
|
|||
|
|
### 接口层
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/core/ApexCompilerService.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/core/WsdlConverterService.java`
|
|||
|
|
|
|||
|
|
### 实现层
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/impl/ApexCompilerServiceImpl.java`
|
|||
|
|
- `datai-salesforce-apex/src/main/java/com/datai/apex/impl/WsdlConverterServiceImpl.java`
|
|||
|
|
|
|||
|
|
### 单元测试
|
|||
|
|
- `datai-salesforce-apex/src/test/java/com/datai/apex/impl/ApexCompilerServiceTest.java`
|
|||
|
|
- `datai-salesforce-apex/src/test/java/com/datai/apex/impl/WsdlConverterServiceTest.java`
|
|||
|
|
|
|||
|
|
## 回退记录
|
|||
|
|
无
|