145 lines
9.4 KiB
Markdown
145 lines
9.4 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：014-1
|
||
- 创建时间：2026-01-27
|
||
- 创建人：SSOT 架构师
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Apex 类与触发器基础管理功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Apex 类与触发器基础管理功能，包括 Tooling API 连接管理、Apex 类 CRUD 操作、Apex 触发器 CRUD 操作
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码，包括异常处理、数据模型、工厂、管理器、服务、控制器和单元测试
|
||
|
||
### 实际产出
|
||
- ✅ 成功实现了 Apex 类与触发器基础管理功能，包括 Tooling API 连接管理、Apex 类 CRUD 操作、Apex 触发器 CRUD 操作
|
||
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求文档、设计文档、决策记录、提示词文档、会话记录、变更日志）
|
||
- ✅ 生成了 20 个代码文件，符合项目规范，包含 3 个单元测试
|
||
- ✅ 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
- ✅ 生成了 8 个 RESTful API 接口，支持 Apex 类和触发器的 CRUD 操作
|
||
|
||
## 成功经验
|
||
|
||
### 1. SSOT 流程的严格执行
|
||
从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段完成后都向用户确认，确保用户对每个阶段的输出满意后再进入下一阶段。
|
||
|
||
### 2. 详细的提示词设计
|
||
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词中明确指定了需要生成的 20 个文件（17 个核心文件 + 3 个单元测试），并提供了详细的代码规范要求（命名规范、注释规范、代码格式、异常处理、日志规范、权限控制、参数验证）。
|
||
|
||
### 3. 完整的会话记录
|
||
阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。会话记录包含了从阶段 1 到阶段 8 的完整过程，包括每个阶段的完成时间、生成文档、关键决策等。
|
||
|
||
### 4. 有效的 AI 质疑与解决方案
|
||
在代码生成过程中，AI 主动质疑了 Service 实现类中直接 new Manager 和 Factory 的问题，并及时进行了修正。这体现了代码生成过程中的自我审查和改进能力，确保了生成的代码符合 Spring Boot 最佳实践。
|
||
|
||
### 5. 架构一致性的保证
|
||
生成的代码严格遵循了项目的架构设计，包括继承 `AbstractConnectionFactory<ToolingConnection>`、使用 `ConnectionProxy` 创建代理连接、复用 `SessionManager` 获取 Session 信息、遵循若依框架规范、遵循 Spring Boot 最佳实践等。这确保了新代码与现有代码的架构一致性。
|
||
|
||
## 改进点
|
||
|
||
### 1. 阶段间的过渡可以更流畅
|
||
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 2（方案设计）时，可以更详细地解释方案设计的目标、需要考虑的方面、预期的输出等。
|
||
|
||
### 2. 代码生成前的验证可以更严格
|
||
在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的所有设计要点是否都在提示词中得到了体现，决策记录中的所有决策是否都在代码中得到了落实。
|
||
|
||
### 3. API 文档的自动生成可以考虑
|
||
可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。当前阶段 9 需要手动创建 API 文档，如果能够自动生成，可以节省时间并减少人为错误。
|
||
|
||
### 4. 单元测试的覆盖率可以提高
|
||
虽然生成了 3 个单元测试类，但测试覆盖率可能不够全面。可以考虑增加更多的测试用例，包括边界条件、异常场景、并发场景等，提高代码的可靠性和稳定性。
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：Service 实现类中直接 new Manager 和 Factory
|
||
|
||
**问题描述**：在 `ApexClassServiceImpl` 和 `ApexTriggerServiceImpl` 的 `listApexClasses` 和 `listApexTriggers` 方法中，直接 new 了 Manager 和 Factory 实例，没有使用依赖注入。
|
||
|
||
**根因**：提示词中的依赖注入要求不够具体，没有明确要求使用 `@Autowired` 注解进行依赖注入。
|
||
|
||
**解决方案**：在 Service 实现类中添加 `@Autowired private ToolingConnectionFactory connectionFactory;`，移除 `ApexClassManager manager = new ApexClassManager();` 和 `ToolingConnectionFactory factory = new ToolingConnectionFactory();`，直接使用注入的 `connectionFactory.getConnection(orgType)`。
|
||
|
||
**预防措施**：在后续的提示词设计中，增加更具体的依赖注入要求，明确要求使用 `@Autowired` 注解进行依赖注入，避免直接 new 实例。
|
||
|
||
### 问题 2：阶段 4（数据库结构）被跳过
|
||
|
||
**问题描述**：本需求不涉及数据库表，所有数据存储在 Salesforce 端，因此阶段 4（数据库结构）被跳过。
|
||
|
||
**根因**：需求本身不涉及数据库表，这是正常的设计决策。
|
||
|
||
**解决方案**：在会话记录中明确标注阶段 4 被跳过，并说明原因。
|
||
|
||
**预防措施**：在后续的需求分析中，提前识别是否涉及数据库表，如果涉及则正常执行阶段 4，如果不涉及则明确标注跳过。
|
||
|
||
## 行动计划
|
||
|
||
### 针对改进点 1：阶段间的过渡可以更流畅
|
||
- **行动**：在阶段转换时，增加对下一阶段的目的和流程的解释
|
||
- **责任人**：AI Assistant
|
||
- **时间**：立即执行
|
||
|
||
### 针对改进点 2：代码生成前的验证可以更严格
|
||
- **行动**：在生成代码前，增加对设计文档和决策记录的再次验证
|
||
- **责任人**：AI Assistant
|
||
- **时间**：立即执行
|
||
|
||
### 针对改进点 3：API 文档的自动生成可以考虑
|
||
- **行动**：探索使用 Swagger 等工具自动生成 API 文档
|
||
- **责任人**：项目团队
|
||
- **时间**：下一个迭代
|
||
|
||
### 针对改进点 4：单元测试的覆盖率可以提高
|
||
- **行动**：增加更多的测试用例，包括边界条件、异常场景、并发场景等
|
||
- **责任人**：AI Assistant
|
||
- **时间**：下一个迭代
|
||
|
||
### 针对问题 1：Service 实现类中直接 new Manager 和 Factory
|
||
- **行动**：在后续的提示词设计中，增加更具体的依赖注入要求
|
||
- **责任人**：AI Assistant
|
||
- **时间**：立即执行
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
#### 1. 具体的输出格式要求
|
||
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如，在本次提示词中明确指定了需要生成的 20 个文件，包括文件路径、类名、方法名等。
|
||
|
||
#### 2. 引用真源
|
||
在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如，在本次提示词中引用了 `[需求文档](../requirements/REQ-014-1.md)` 和 `[设计文档](../design/2026-01-27-014-1-Apex类与触发器基础管理-设计.md)`。
|
||
|
||
#### 3. 详细的代码规范要求
|
||
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如，在本次提示词中详细说明了命名规范、注释规范、代码格式、异常处理、日志规范、权限控制、参数验证等要求。
|
||
|
||
### 避免的坑
|
||
|
||
#### 1. 不要使用模糊的描述
|
||
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。应该使用具体的描述，如"请生成 20 个文件，包括 3 个异常类、2 个 Domain 类、6 个 DTO 类、2 个 VO 类、1 个 Factory 类、2 个 Manager 类、4 个 Service 类、2 个 Controller 类、3 个单元测试类"。
|
||
|
||
#### 2. 不要忽略测试要求
|
||
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该明确要求生成单元测试，包括测试覆盖率、测试场景等。
|
||
|
||
#### 3. 不要违反项目规则
|
||
在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。应该严格遵守项目规则，包括架构设计、代码规范、命名规范等。
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在依赖注入要求方面可以更具体。计划在下一个迭代中更新提示词模板，增加更具体的依赖注入要求，包括：
|
||
- 明确要求使用 `@Autowired` 注解进行依赖注入
|
||
- 明确要求不要直接 new 实例
|
||
- 明确要求使用 Spring 的依赖注入机制
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/REQ-014-1.md)
|
||
- [设计文档](../design/2026-01-27-014-1-Apex类与触发器基础管理-设计.md)
|
||
- [决策记录](../decisions/adr/2026-01-27-014-1-ADR-ToolingAPI客户端代码生成方案.md)
|
||
- [提示词文档](../prompts/2026-01-27-014-1-prompt-Apex类与触发器基础管理.md)
|
||
- [会话记录](../sessions/2026-01-27-014-1-session.md)
|
||
- [变更日志](../changelog/2026-01-27-014-1-changelog.md)
|
||
- [主索引](../index.md)
|