# Apex 编译器接口与错误处理 - 复盘文档

## 元数据
- 需求编号：013-1
- 创建时间：2026-01-28
- 创建人：AI Assistant
- 状态：已完成

## 复盘概述
本次复盘对 Apex 编译器接口与错误处理功能的开发过程进行了全面回顾，从需求定义到变更记录的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

## 目标与实际产出对比

### 目标
1. 实现统一错误模型，创建 ApexCompileIssue 类映射 Salesforce SOAP API 的 CompileIssue
2. 实现编译器结果封装，创建 CompileResult 类封装编译结果
3. 实现 WSDL 转 Apex 结果封装，创建 WsdlToApexResult 类封装 WSDL 转换结果
4. 实现异常体系，创建 ApexException 及其子类
5. 实现服务接口，创建 ApexCompilerService 和 WsdlConverterService 接口
6. 遵循 SSOT 流程，确保所有开发活动都有文档依据
7. 生成符合项目规范的代码，包含单元测试

### 实际产出
1. 成功实现了统一错误模型，创建了 ApexCompileIssue 类
2. 成功实现了编译器结果封装，创建了 CompileResult 类
3. 成功实现了 WSDL 转 Apex 结果封装，创建了 WsdlToApexResult 类
4. 成功实现了异常体系，创建了 ApexException 及其子类（ApexCompilationException、ApexRuntimeException、ApexConnectionException）
5. 成功实现了服务接口，创建了 ApexCompilerService 和 WsdlConverterService 接口
6. 成功实现了服务实现，创建了 ApexCompilerServiceImpl 和 WsdlConverterServiceImpl
7. 成功实现了单元测试，创建了 ApexCompilerServiceTest 和 WsdlConverterServiceTest
8. 严格按照 SSOT 流程执行，每个阶段都有相应的文档
9. 生成的代码符合项目规范，包含单元测试
10. 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

## 成功经验

### 1. SSOT 流程的严格执行
从需求定义到变更记录的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段完成后都会向用户确认，确保用户对进度和方向的理解一致。

### 2. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词引用了真源（需求文档、设计文档、决策记录），确保了代码生成的准确性。

### 3. 完整的会话记录
阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。会话记录包含了每个阶段的执行状态、关键决策和生成的文档链接，便于后续查阅。

### 4. 基于真实源代码的需求优化
在阶段 1，通过读取 Salesforce SOAP API 的真实源代码（CompileClassResult.java、CompileTriggerResult.java 等），优化了需求文档，确保了需求的准确性和可行性。这种基于真实源代码的需求优化方法，避免了需求与实际 API 不匹配的问题。

### 5. 灵活的阶段跳过机制
在阶段 4，通过分析需求确认不涉及数据库变更，灵活地跳过了数据库结构生成阶段，直接进入提示词生成阶段。这种灵活的阶段跳过机制，提高了开发效率，避免了不必要的文档创建。

## 改进点

### 1. 阶段间的过渡可以更流畅
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 6（代码生成）前，可以更详细地说明将要生成的代码文件、代码结构、测试策略等。

### 2. 代码生成前的验证可以更严格
在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的接口定义是否与需求文档中的功能需求一致，决策记录中的技术选型是否与实际代码实现一致。

### 3. API 文档的自动生成可以考虑
可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。目前 API 文档是手动编写的，容易出现遗漏或不准确的情况。

### 4. 单元测试的覆盖率验证
在代码生成完成后，可以增加单元测试覆盖率的验证步骤，确保测试用例的完整性。目前虽然生成了单元测试，但没有验证测试覆盖率是否达到要求。

### 5. 代码生成的批量验证
在代码生成完成后，可以增加批量验证步骤，检查所有生成的代码文件是否符合项目规范，包括命名规范、注释规范、导入规范等。目前虽然提示词中包含了代码规范要求，但没有批量验证步骤。

## 问题分析

本次需求执行过程中未发现重大问题，整体执行顺利。所有阶段都按时完成，生成的代码符合项目规范和需求，文档完整准确。

### 无重大问题
- 需求定义清晰准确，基于真实源代码优化
- 设计方案合理，技术选型正确
- 代码生成符合规范，包含单元测试
- 文档完整准确，索引更新及时
- 会话记录完整，可追溯性强

## 行动计划

### 针对改进点 1：阶段间的过渡可以更流畅
- **行动**：在阶段转换时，增加对下一阶段的目的和流程的详细解释
- **责任人**：AI Assistant
- **时间**：立即执行
- **具体措施**：
  - 在进入阶段 6（代码生成）前，详细说明将要生成的代码文件、代码结构、测试策略等
  - 在进入阶段 7（会话记录）前，详细说明会话记录的内容和作用
  - 在进入阶段 8（变更记录与归档）前，详细说明变更记录的内容和作用
  - 在进入阶段 9（闭环复盘和接口文档）前，详细说明复盘文档和 API 文档的内容和作用

### 针对改进点 2：代码生成前的验证可以更严格
- **行动**：在生成代码前，增加对设计文档和决策记录的再次验证
- **责任人**：AI Assistant
- **时间**：立即执行
- **具体措施**：
  - 检查设计文档中的接口定义是否与需求文档中的功能需求一致
  - 检查决策记录中的技术选型是否与实际代码实现一致
  - 检查设计文档中的数据模型是否与需求文档中的数据模型一致
  - 检查设计文档中的异常处理是否与需求文档中的异常处理一致

### 针对改进点 3：API 文档的自动生成可以考虑
- **行动**：探索使用 Swagger 等工具自动生成 API 文档
- **责任人**：项目团队
- **时间**：下一个迭代
- **具体措施**：
  - 调研 Swagger 等工具的集成方案
  - 评估自动生成 API 文档的可行性和成本
  - 制定 API 文档自动生成的实施方案
  - 在下一个需求中试点 API 文档自动生成

### 针对改进点 4：单元测试的覆盖率验证
- **行动**：在代码生成完成后，增加单元测试覆盖率的验证步骤
- **责任人**：AI Assistant
- **时间**：立即执行
- **具体措施**：
  - 在代码生成完成后，运行单元测试
  - 使用 JaCoCo 等工具生成测试覆盖率报告
  - 验证测试覆盖率是否达到 80% 的要求
  - 如果测试覆盖率不达标，补充测试用例

### 针对改进点 5：代码生成的批量验证
- **行动**：在代码生成完成后，增加批量验证步骤
- **责任人**：AI Assistant
- **时间**：立即执行
- **具体措施**：
  - 检查所有生成的代码文件是否符合命名规范
  - 检查所有生成的代码文件是否包含必要的注释
  - 检查所有生成的代码文件的导入语句是否规范
  - 检查所有生成的代码文件的异常处理是否符合规范

## 提取模式

### 有效的 Prompt 技巧

#### 1. 具体的输出格式要求
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如：
```
## 输出格式要求
### 模型层
- 文件路径：`datai-salesforce-apex/src/main/java/com/datai/apex/model/`
- 文件格式：Java 类文件
- 必须使用 Lombok 注解（@Data、@NoArgsConstructor、@AllArgsConstructor）
- 必须实现 Serializable 接口
```

#### 2. 引用真源
在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如：
```
## 引用真源
- 需求文档：[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)
```

#### 3. 详细的代码规范要求
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如：
```
## 代码规范要求
### 命名规范
- 类名：使用大驼峰命名法（PascalCase）
- 方法名：使用小驼峰命名法（camelCase）
- 变量名：使用小驼峰命名法（camelCase）
- 常量名：使用全大写字母和下划线（UPPER_SNAKE_CASE）

### 注释规范
- 类注释：使用 Javadoc 格式，包含类的功能描述、作者、版本等信息
- 方法注释：使用 Javadoc 格式，包含方法的功能描述、参数说明、返回值说明、异常说明等
- 字段注释：使用 Javadoc 格式，包含字段的说明
```

### 避免的坑

#### 1. 不要使用模糊的描述
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。应该使用具体的描述，如"请生成符合 Spring Boot 规范的代码，使用 @Service 注解，包含单元测试"。

#### 2. 不要忽略测试要求
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该在提示词中明确指定测试要求，如"每个服务实现类都需要包含单元测试，测试覆盖率不低于 80%"。

#### 3. 不要违反项目规则
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。应该在提示词中明确指定项目规则，如"遵循若依框架规范，使用 @RestController、@RequestMapping、@GetMapping 等注解"。

## 模板迭代

经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在以下方面可以改进：

### 需要改进的方面
1. **代码规范要求可以更具体**：特别是针对 Spring Boot 框架和 Lombok 框架的规范要求
2. **测试要求可以更详细**：特别是测试覆盖率、测试场景、测试框架等方面的要求
3. **验证步骤可以更明确**：特别是代码生成后的验证步骤，如批量验证、覆盖率验证等

### 模板更新计划
在下一个迭代中更新提示词模板，增加以下内容：
1. **Spring Boot 框架规范要求**：
   - 包结构规范
   - 注解使用规范
   - 配置文件规范
   - 依赖注入规范

2. **Lombok 框架规范要求**：
   - 注解使用规范（@Data、@Getter、@Setter、@NoArgsConstructor、@AllArgsConstructor 等）
   - 序列化规范（@Builder、@ToString、@EqualsAndHashCode 等）

3. **测试要求详细化**：
   - 测试覆盖率要求（不低于 80%）
   - 测试场景要求（正常场景、异常场景、边界场景）
   - 测试框架要求（JUnit 5、Mockito、AssertJ）
   - 测试用例命名规范（should_ExpectedBehavior_When_StateUnderTest）

4. **验证步骤明确化**：
   - 批量验证步骤（命名规范、注释规范、导入规范、异常处理规范）
   - 覆盖率验证步骤（使用 JaCoCo 生成测试覆盖率报告）
   - 集成测试步骤（验证服务间的协作）

## 相关文档
- [需求文档](../requirements/REQ-013-1.md)
- [设计文档](../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)
- [会话记录](../sessions/2026-01-28-013-1-session.md)