219 lines
9.6 KiB
Markdown
219 lines
9.6 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：003
|
||
- 子需求编号：003-01
|
||
- 子需求名称：连接管理
|
||
- 创建时间：2026-02-05
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对子需求 003-01（Metadata API 连接管理）的开发过程进行了全面回顾。该子需求从 2026-01-28 开始，到 2026-02-05 完成，历时 8 天，完整经历了 SSOT 流程的 8 个阶段。复盘总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
1. 实现 Salesforce Metadata API 连接管理功能
|
||
2. 提供对源 org（Source Org）的 Metadata API 连接创建、管理、测试和监控能力
|
||
3. 集成 SessionManager 进行会话管理
|
||
4. 支持连接缓存、状态监控和历史记录
|
||
5. 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
6. 生成符合项目规范的代码
|
||
|
||
### 实际产出
|
||
1. ✅ 成功实现了 Metadata API 连接管理功能
|
||
2. ✅ 提供了完整的连接创建、管理、测试和监控能力
|
||
3. ✅ 成功集成了 SessionManager 进行会话管理
|
||
4. ✅ 实现了连接缓存机制、状态监控和历史记录功能
|
||
5. ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
6. ✅ 生成了 9 个符合项目规范的代码文件
|
||
7. ✅ 创建了完整的文档体系（需求文档、设计文档、决策记录、提示词文档、变更日志、复盘文档、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. 引用真源
|
||
在提示词开头明确引用需求文档和设计文档的链接，确保生成的代码符合需求和设计要求。
|
||
```markdown
|
||
## 真源引用
|
||
- **需求文档**: `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. 具体的输出格式要求
|
||
明确指定需要生成的文件、路径、格式等，提高生成代码的准确性和规范性。
|
||
```markdown
|
||
### 输出要求
|
||
1. **Factory 层**:
|
||
- 文件: `datai-salesforce-metadata/src/main/java/com/datai/metadata/factory/MetadataConnectionFactory.java`
|
||
- 实现: 继承 AbstractConnectionFactory<MetadataConnection>
|
||
```
|
||
|
||
#### 3. 详细的代码规范要求
|
||
明确指定代码规范、命名规范、注释规范等，提高生成代码的质量和可读性。
|
||
```markdown
|
||
### 代码规范
|
||
- 遵循若依框架规范
|
||
- 使用 Lombok 注解简化代码
|
||
- 使用 Slf4j 进行日志记录
|
||
- 使用自定义异常类进行错误处理
|
||
```
|
||
|
||
### 避免的坑
|
||
|
||
#### 1. 不要使用模糊的描述
|
||
❌ 错误示例："请生成高质量的代码"
|
||
✅ 正确示例："代码必须遵循若依框架规范，使用统一的异常处理机制，包含完整的 JavaDoc 注释"
|
||
|
||
#### 2. 不要忽略测试要求
|
||
❌ 错误示例：提示词中不提及单元测试
|
||
✅ 正确示例："为每个 Service 和 Factory 类生成对应的单元测试类，测试覆盖率不低于 80%"
|
||
|
||
#### 3. 不要违反项目规则
|
||
❌ 错误示例：生成的代码使用自定义异常而非项目定义的异常
|
||
✅ 正确示例："优先使用 `datai-salesforce-common` 模块中的现有异常类"
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
### 1. 增加单元测试要求
|
||
在提示词模板中增加专门的单元测试章节，明确要求：
|
||
- 为每个 Service 类生成对应的单元测试类
|
||
- 为每个 Factory 类生成对应的单元测试类
|
||
- 为每个 Controller 类生成对应的单元测试类
|
||
- 测试覆盖率要求（如不低于 80%）
|
||
|
||
### 2. 增加代码路径验证
|
||
在提示词模板中增加代码路径验证要求：
|
||
- 生成代码前检查项目实际目录结构
|
||
- 使用绝对路径或相对于项目根目录的路径
|
||
- 生成后验证文件路径是否正确
|
||
|
||
### 3. 增加文档交叉引用
|
||
在提示词模板中增加文档交叉引用要求：
|
||
- 每个文档必须列出相关文档
|
||
- 使用统一的文档引用格式
|
||
- 定期检查和更新文档间的链接
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-003-01-连接管理.md)
|
||
- [设计文档](../design/2026-02-02-003-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-02-02-003-01-ADR-连接管理技术选型.md)
|
||
- [提示词文档](../prompts/2026-02-02-003-01-prompt-Metadata连接管理.md)
|
||
- [变更日志](../changelog/2026-02-05-003-01-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-05-003-01-api.md)
|
||
- [会话记录](../sessions/2026-01-28-003-session.md)
|