9.6 KiB
复盘文档
元数据
- 需求编号：003
- 子需求编号：003-01
- 子需求名称：连接管理
- 创建时间：2026-02-05
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对子需求 003-01（Metadata API 连接管理）的开发过程进行了全面回顾。该子需求从 2026-01-28 开始，到 2026-02-05 完成，历时 8 天，完整经历了 SSOT 流程的 8 个阶段。复盘总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Salesforce Metadata API 连接管理功能
- 提供对源 org（Source Org）的 Metadata API 连接创建、管理、测试和监控能力
- 集成 SessionManager 进行会话管理
- 支持连接缓存、状态监控和历史记录
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码
实际产出
- ✅ 成功实现了 Metadata API 连接管理功能
- ✅ 提供了完整的连接创建、管理、测试和监控能力
- ✅ 成功集成了 SessionManager 进行会话管理
- ✅ 实现了连接缓存机制、状态监控和历史记录功能
- ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
- ✅ 生成了 9 个符合项目规范的代码文件
- ✅ 创建了完整的文档体系（需求文档、设计文档、决策记录、提示词文档、变更日志、复盘文档、API 文档）
成功经验
1. SSOT 流程的严格执行
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。这种做法带来了以下好处：
- 可追溯性：每个决策、每行代码都有文档支撑，便于后续维护
- 一致性：通过文档驱动开发，确保代码实现与需求一致
- 协作效率：团队成员可以通过文档快速了解功能设计和实现细节
2. 复用现有基础设施
通过继承 AbstractConnectionFactory 和集成 SessionManager，成功复用了现有连接管理基础设施：
- 减少了重复代码的编写
- 确保了与 Partner API、Apex API 模块的一致性
- 连接缓存和 Session 有效性检查由基础设施统一提供
3. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求：
- 明确了需要生成的文件列表和路径
- 指定了代码必须遵循的若依框架规范
- 要求使用特定的异常类和日志记录方式
- 这种详细的提示词设计确保了生成的代码符合项目规范
4. 清晰的架构设计
采用 Controller → Service → Factory → Metadata API 的分层架构：
- 职责清晰：Controller 处理 HTTP 请求，Service 处理业务逻辑，Factory 处理连接创建
- 易于测试：各层之间通过接口解耦，便于单元测试
- 可扩展性：后续可以方便地添加新的连接类型或功能
5. 完整的错误码体系
定义了标准的错误码体系，覆盖连接管理的各种异常场景：
METADATA_CONNECTION_ERROR：连接错误METADATA_AUTH_ERROR：认证错误METADATA_OPERATION_ERROR：操作错误- 这种标准化的错误码便于前端统一处理错误
改进点
1. 单元测试需要补充
虽然提示词中要求生成单元测试，但实际生成的代码文件中缺少单元测试。改进措施：
- 在后续的代码生成中，明确要求生成完整的单元测试代码
- 将单元测试作为代码生成的必选项，而非可选项
- 在阶段 6 完成后，专门安排时间补充单元测试
2. 阶段转换时的沟通可以更充分
在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程。改进措施：
- 在每个阶段开始时，简要介绍该阶段的目标和产出
- 提供该阶段的预计时间和关键检查点
- 询问用户是否有特殊要求或关注点
3. API 文档可以更加详细
当前 API 文档描述了接口的基本信息，但可以进一步增加：
- 接口的调用场景和注意事项
- 更详细的错误处理示例
- 性能指标和限制说明
4. 数据库表设计可以更早确定
虽然当前子需求不需要创建新的数据库表，但在设计阶段可以更明确地确定表结构。改进措施：
- 在阶段 2（方案设计）中，明确数据库表结构
- 在阶段 4（数据库结构）中，即使跳过也要说明原因
- 确保后续子需求的数据库设计一致性
问题分析
问题 1：代码生成时的路径问题
现象：在生成代码时，部分文件路径与项目实际结构不完全匹配。
根因分析：
- 提示词中的路径描述不够精确
- 对项目结构的了解不够深入
解决方案：
- 在生成代码前，先检查项目的实际目录结构
- 在提示词中使用相对路径，并明确说明基准目录
- 生成代码后，验证文件路径是否正确
问题 2：会话记录更新时的重复内容
现象：在更新会话记录时，出现了重复的内容。
根因分析：
- 会话记录的更新逻辑不够严谨
- 没有检查是否已存在相同内容
解决方案：
- 在更新会话记录前，先读取现有内容
- 使用 SearchReplace 工具精确替换，而非追加
- 更新后验证内容是否正确
问题 3：部分文档的交叉引用不够完善
现象：部分文档之间的交叉引用链接不够完善。
根因分析：
- 文档创建时的关注点主要在内容
- 对文档间的关联性考虑不够
解决方案：
- 在创建每个文档时，明确列出相关文档
- 使用统一的文档引用格式
- 定期检查和更新文档间的链接
行动计划
| 序号 | 改进点/问题 | 行动项 | 责任人 | 时间节点 |
|---|---|---|---|---|
| 1 | 单元测试缺失 | 补充 MetadataConnectionFactory、Service、Controller 的单元测试 | AI Assistant | 2026-02-06 |
| 2 | 阶段转换沟通 | 在每个阶段开始时，简要介绍该阶段的目标和产出 | AI Assistant | 立即执行 |
| 3 | API 文档详细度 | 在 API 文档中增加调用场景、注意事项、性能指标 | AI Assistant | 2026-02-06 |
| 4 | 代码生成路径 | 生成代码前检查项目结构，使用精确路径 | AI Assistant | 立即执行 |
| 5 | 会话记录更新 | 使用 SearchReplace 精确更新，避免重复内容 | AI Assistant | 立即执行 |
| 6 | 文档交叉引用 | 创建文档时明确相关文档，统一引用格式 | AI Assistant | 立即执行 |
提取模式
有效的 Prompt 技巧
1. 引用真源
在提示词开头明确引用需求文档和设计文档的链接，确保生成的代码符合需求和设计要求。
## 真源引用
- **需求文档**: `docs/requirements/sub/2026-01-28-003-01-连接管理.md`
- **设计文档**: `docs/design/2026-02-02-003-01-连接管理-设计.md`
- **决策记录**: `docs/decisions/2026-02-02-003-01-ADR-连接管理技术选型.md`
2. 具体的输出格式要求
明确指定需要生成的文件、路径、格式等，提高生成代码的准确性和规范性。
### 输出要求
1. **Factory 层**:
- 文件: `datai-salesforce-metadata/src/main/java/com/datai/metadata/factory/MetadataConnectionFactory.java`
- 实现: 继承 AbstractConnectionFactory<MetadataConnection>
3. 详细的代码规范要求
明确指定代码规范、命名规范、注释规范等，提高生成代码的质量和可读性。
### 代码规范
- 遵循若依框架规范
- 使用 Lombok 注解简化代码
- 使用 Slf4j 进行日志记录
- 使用自定义异常类进行错误处理
避免的坑
1. 不要使用模糊的描述
❌ 错误示例："请生成高质量的代码"
✅ 正确示例："代码必须遵循若依框架规范，使用统一的异常处理机制，包含完整的 JavaDoc 注释"
2. 不要忽略测试要求
❌ 错误示例：提示词中不提及单元测试
✅ 正确示例："为每个 Service 和 Factory 类生成对应的单元测试类，测试覆盖率不低于 80%"
3. 不要违反项目规则
❌ 错误示例：生成的代码使用自定义异常而非项目定义的异常
✅ 正确示例："优先使用 datai-salesforce-common 模块中的现有异常类"
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
1. 增加单元测试要求
在提示词模板中增加专门的单元测试章节，明确要求：
- 为每个 Service 类生成对应的单元测试类
- 为每个 Factory 类生成对应的单元测试类
- 为每个 Controller 类生成对应的单元测试类
- 测试覆盖率要求（如不低于 80%）
2. 增加代码路径验证
在提示词模板中增加代码路径验证要求：
- 生成代码前检查项目实际目录结构
- 使用绝对路径或相对于项目根目录的路径
- 生成后验证文件路径是否正确
3. 增加文档交叉引用
在提示词模板中增加文档交叉引用要求：
- 每个文档必须列出相关文档
- 使用统一的文档引用格式
- 定期检查和更新文档间的链接