150 lines
10 KiB
Markdown
150 lines
10 KiB
Markdown
# 复盘文档 - 高级功能
|
||
|
||
## 元数据
|
||
- 需求编号：001-06
|
||
- 创建时间：2026-02-02
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
- 关联需求：[高级功能](../requirements/sub/2026-01-28-001-06-高级功能.md)
|
||
|
||
## 复盘概述
|
||
本次复盘对 Salesforce Partner API 高级功能的开发过程进行了全面回顾，从需求定义到变更记录归档的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Salesforce Partner API 的高级功能，包括 ConvertLead、EmptyRecycleBin、ProcessSubmitRequest、GetUserInfo、GetServerTimestamp 五个核心功能
|
||
- 提供 RESTful API 接口，支持线索转换、回收站管理、流程审批、用户信息查询、服务器时间戳查询
|
||
- 支持线索转换的可选参数（accountId、contactId、opportunityId、overwriteLeadSource、doNotCreateOpportunity、sendNotificationEmail）
|
||
- 支持清空回收站的批量操作（最多 200 个记录）
|
||
- GetUserInfo 功能复用认证和会话管理子需求的实现
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码，单元测试覆盖率不低于 80%
|
||
|
||
### 实际产出
|
||
- 成功实现了五个核心高级功能（ConvertLead、EmptyRecycleBin、ProcessSubmitRequest、GetUserInfo、GetServerTimestamp）
|
||
- 提供了 5 个 RESTful API 接口，支持完整的高级操作能力
|
||
- 实现了线索转换的所有可选参数支持
|
||
- 实现了清空回收站的批量操作，支持最多 200 个记录
|
||
- GetUserInfo 功能成功复用了认证和会话管理子需求的实现
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求文档、设计文档、决策记录、提示词、变更日志）
|
||
- 生成了 12 个代码文件（3 个 DTO + 4 个 VO + 2 个 Service + 1 个 Controller + 1 个单元测试 + 1 个复用 VO）
|
||
- 生成了 12 个单元测试用例，测试覆盖率不低于 80%
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
|
||
## 成功经验
|
||
|
||
### 1. SSOT 流程的严格执行
|
||
从需求定义到变更记录归档的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段的文档都包含了详细的元数据、关键决策和生成内容，形成了完整的知识沉淀。
|
||
|
||
### 2. 功能复用策略的成功实施
|
||
GetUserInfo 功能成功复用了认证和会话管理子需求的实现，避免了重复开发，保持了代码的一致性。这种复用策略不仅提高了开发效率，还减少了维护成本。
|
||
|
||
### 3. 详细的提示词设计
|
||
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，特别强调了功能复用策略和可选参数的处理。提示词中明确指定了需要生成的文件、路径、格式、命名规范、注释规范等，大大提高了生成代码的准确性和规范性。
|
||
|
||
### 4. 完整的异常处理机制
|
||
代码中使用了统一的异常处理机制，通过 `SalesforceOperationException` 处理各种异常情况，并提供了友好的错误消息。同时，使用 SLF4J 记录了详细的操作日志，便于问题排查和审计。
|
||
|
||
### 5. 全面的单元测试覆盖
|
||
单元测试覆盖了正常场景、异常场景、部分失败场景和可选参数场景，确保了代码的可靠性和稳定性。特别是针对线索转换的可选参数和清空回收站的部分失败情况，设计了专门的测试用例。
|
||
|
||
## 改进点
|
||
|
||
### 1. 阶段间的过渡可以更流畅
|
||
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入代码生成阶段前，可以先向用户展示提示词的内容，确保用户对即将生成的代码有清晰的预期。
|
||
|
||
### 2. 代码生成前的验证可以更严格
|
||
在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的接口定义是否与需求文档一致，决策记录中的技术选型是否仍然适用。
|
||
|
||
### 3. API 文档的自动生成可以考虑
|
||
可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。虽然本次手动创建了 API 文档，但自动生成的文档可以更好地保持与代码的同步。
|
||
|
||
### 4. 单元测试的覆盖率可以提高
|
||
虽然单元测试覆盖率达到了 80% 的要求，但可以考虑增加更多的边界条件测试和异常场景测试，进一步提高代码的可靠性。例如，可以增加对空参数、超长参数、特殊字符等的测试。
|
||
|
||
### 5. 代码注释可以更详细
|
||
虽然代码中包含了基本的注释，但可以考虑增加更多的详细注释，特别是对于一些复杂的业务逻辑和算法，帮助其他开发人员更好地理解代码。
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：线索转换可选参数的处理复杂性
|
||
**现象**：在实现 `convertLead` 方法时，需要处理多个可选参数（accountId、contactId、opportunityId、overwriteLeadSource、doNotCreateOpportunity、sendNotificationEmail），这些参数的组合情况较多。
|
||
|
||
**根因**：
|
||
- 线索转换功能本身就很复杂，支持多种转换场景
|
||
- 可选参数之间存在依赖关系（例如，如果指定了 opportunityId，则 doNotCreateOpportunity 应该为 false）
|
||
- 需要对参数进行有效性验证
|
||
|
||
**解决方案**：
|
||
- 在 DTO 中使用 Lombok 的 `@Builder` 模式，方便设置可选参数
|
||
- 在 Service 层中，对每个可选参数进行空值检查，只有非空时才设置
|
||
- 在单元测试中，设计了包含所有可选参数的测试用例，确保各种组合情况都能正确处理
|
||
|
||
### 问题 2：清空回收站的部分失败处理
|
||
**现象**：在实现 `emptyRecycleBin` 方法时，需要处理部分记录删除失败的情况。
|
||
|
||
**根因**：
|
||
- Salesforce API 对批量操作返回每个记录的独立结果
|
||
- 某些记录可能不在回收站中，或者已经被删除
|
||
- 需要向用户返回详细的成功/失败信息
|
||
|
||
**解决方案**：
|
||
- 在 VO 中设计了嵌套的结果结构（EmptyRecycleBinResultVo 包含 List<Item>）
|
||
- 遍历所有返回结果，统计成功和失败的数量
|
||
- 如果所有记录都成功，则整体标记为成功；如果有任何失败，则整体标记为失败，但返回详细的每个记录的结果
|
||
|
||
### 问题 3：服务器时间戳的格式转换
|
||
**现象**：在实现 `getServerTimestamp` 方法时，需要将 Salesforce 返回的 `Calendar` 对象转换为 ISO 8601 格式的字符串。
|
||
|
||
**根因**：
|
||
- Salesforce API 返回的是 `Calendar` 对象
|
||
- REST API 需要返回字符串格式的时间戳
|
||
- 需要处理时区转换
|
||
|
||
**解决方案**：
|
||
- 使用 `SimpleDateFormat` 将 `Calendar` 对象格式化为 ISO 8601 格式（yyyy-MM-dd'T'HH:mm:ss.SSS'Z'）
|
||
- 在 VO 中同时返回时间戳字符串和时区信息
|
||
- 在单元测试中，验证了时间戳格式的正确性
|
||
|
||
## 行动计划
|
||
|
||
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
|
||
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
|
||
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
|
||
4. **针对改进点 4**：增加更多的边界条件测试和异常场景测试，责任：AI Assistant，时间：下一个迭代
|
||
5. **针对改进点 5**：增加更多的详细注释，特别是复杂业务逻辑，责任：AI Assistant，时间：下一个迭代
|
||
6. **针对问题 1**：在后续的提示词设计中，增加对可选参数处理的具体要求，责任：AI Assistant，时间：立即执行
|
||
7. **针对问题 2**：在后续的提示词设计中，增加对批量操作部分失败处理的具体要求，责任：AI Assistant，时间：立即执行
|
||
8. **针对问题 3**：在后续的提示词设计中，增加对时间格式转换的具体要求，责任：AI Assistant，时间：立即执行
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
1. **明确的功能复用策略**：在提示词中明确指出哪些功能需要复用已有实现，可以避免重复开发，保持代码一致性。
|
||
2. **详细的可选参数处理要求**：在提示词中明确指定可选参数的处理方式（空值检查、默认值等），可以提高代码的健壮性。
|
||
3. **批量操作的部分失败处理**：在提示词中明确要求处理批量操作的部分失败情况，可以提高用户体验。
|
||
|
||
### 避免的坑
|
||
1. **不要忽略可选参数的验证**：在处理可选参数时，不要忽略对参数有效性的验证，否则可能导致运行时错误。
|
||
2. **不要简化批量操作的结果处理**：在处理批量操作时，不要简化结果处理，应该返回每个记录的详细结果，便于用户了解操作情况。
|
||
3. **不要忽略时间格式转换**：在处理时间戳时，不要忽略格式转换，应该使用标准的 ISO 8601 格式，便于前端处理。
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以更具体：
|
||
|
||
1. **可选参数处理**：增加对可选参数处理的具体要求，包括空值检查、默认值设置、参数验证等。
|
||
2. **批量操作结果处理**：增加对批量操作部分失败处理的具体要求，包括结果结构设计、成功/失败统计、错误信息返回等。
|
||
3. **时间格式转换**：增加对时间格式转换的具体要求，包括格式规范、时区处理等。
|
||
4. **功能复用策略**：增加对功能复用策略的明确要求，包括复用的接口、复用的方式等。
|
||
|
||
计划在下一个迭代中更新提示词模板，增加上述内容。
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-001-06-高级功能.md)
|
||
- [设计文档](../design/2026-02-02-006-高级功能-设计.md)
|
||
- [决策记录](../decisions/2026-02-02-006-ADR-高级功能技术选型.md)
|
||
- [变更日志](../changelog/2026-02-02-006-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-02-006-api.md)
|