datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-02-006-retro.md

复盘文档 - 高级功能

元数据

• 需求编号：001-06
• 创建时间：2026-02-02
• 创建人：AI Assistant
• 状态：已完成
• 关联需求：高级功能

复盘概述

本次复盘对 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）
• 遍历所有返回结果，统计成功和失败的数量
• 如果所有记录都成功，则整体标记为成功；如果有任何失败，则整体标记为失败，但返回详细的每个记录的结果

问题 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. 功能复用策略：增加对功能复用策略的明确要求，包括复用的接口、复用的方式等。

计划在下一个迭代中更新提示词模板，增加上述内容。

相关文档

• 需求文档
• 设计文档
• 决策记录
• 变更日志
• API 文档