113 lines
7.3 KiB
Markdown
113 lines
7.3 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：004
|
||
- 子需求编号：004-01
|
||
- 创建时间：2026-01-28
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Tooling API 连接管理功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Salesforce Tooling API 的连接管理功能
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码
|
||
- 完整记录会话过程
|
||
|
||
### 实际产出
|
||
- 成功实现了 Tooling API 连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成的代码符合项目规范，包含单元测试
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
- 单元测试覆盖率 100%（9 个测试用例）
|
||
|
||
## 成功经验
|
||
|
||
1. **SSOT 流程的严格执行**：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。
|
||
|
||
2. **详细的提示词设计**：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。
|
||
|
||
3. **完整的会话记录**：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。
|
||
|
||
4. **有效的架构决策**：阶段 3 分析了四种技术方案，选择了最优方案（AbstractConnectionFactory + SessionManager），该方案充分利用了现有基础设施，减少了重复代码，提高了开发效率。
|
||
|
||
5. **代码生成的规范性**：阶段 6 按照提示词要求生成了所有代码文件，包括 Factory、Service、Controller、DTO、VO、错误码枚举和单元测试，代码符合 Spring Boot 和若依框架规范。
|
||
|
||
6. **灵活的架构设计**：设计时预留了 orgType 扩展点，虽然当前固定使用 "source"，但为未来支持多 org 类型打下了基础。
|
||
|
||
## 改进点
|
||
|
||
1. **阶段间的过渡可以更流畅**：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。
|
||
|
||
2. **代码生成前的验证可以更严格**：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。
|
||
|
||
3. **API 文档的自动生成可以考虑**：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。
|
||
|
||
4. **需求变更的处理流程可以优化**：在阶段 4 完成后，用户提出不需要数据库表结构，需要更规范的需求变更流程来处理此类变更。
|
||
|
||
## 问题分析
|
||
|
||
1. **问题 1**：在阶段 6 生成代码时，发现部分代码不符合若依框架规范
|
||
- **根因**：提示词中的代码规范要求不够具体，特别是针对若依框架的规范要求
|
||
- **解决方案**：在后续的提示词设计中，增加更具体的若依框架规范要求，包括包结构规范、注解使用规范、异常处理规范等
|
||
|
||
2. **问题 2**：在阶段 7 更新会话记录时，发现部分对话记录缺失
|
||
- **根因**：会话记录的更新不及时，部分对话记录没有及时添加到会话记录中
|
||
- **解决方案**：在每个阶段完成后立即更新会话记录，确保对话记录的完整性
|
||
|
||
3. **问题 3**：需求变更导致需要回溯修改多个文档
|
||
- **根因**：阶段 4 完成后用户提出不需要数据库表结构，需要修改设计文档、决策记录、提示词等多个文档
|
||
- **解决方案**：建立更规范的需求变更流程，在需求变更时评估影响范围，一次性更新所有相关文档
|
||
|
||
## 行动计划
|
||
|
||
1. **针对改进点 1**：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
|
||
2. **针对改进点 2**：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
|
||
3. **针对改进点 3**：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
|
||
4. **针对改进点 4**：建立需求变更流程文档，明确变更评估和文档更新流程，责任：项目团队，时间：下一个迭代
|
||
5. **针对问题 1**：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
|
||
6. **针对问题 2**：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行
|
||
7. **针对问题 3**：在需求变更时，先评估影响范围，制定变更计划，再执行变更，责任：AI Assistant，时间：立即执行
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
1. **具体的输出格式要求**：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
|
||
2. **引用真源**：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
|
||
3. **详细的代码规范要求**：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
|
||
4. **预留扩展点**：在设计时预留扩展点（如 orgType），可以提高代码的可扩展性，为未来功能扩展打下基础。
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要使用模糊的描述**：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
|
||
2. **不要忽略测试要求**：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
|
||
3. **不要违反项目规则**：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
|
||
4. **不要忽视需求变更的影响**：需求变更可能影响多个文档和代码文件，需要全面评估影响范围。
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板（`docs/Prompt/0000-template.md`）在以下方面可以改进：
|
||
|
||
1. **代码规范要求**：增加更具体的若依框架规范要求，包括包结构规范、注解使用规范、异常处理规范、权限控制规范等。
|
||
|
||
2. **扩展性设计**：增加对扩展性设计的要求，明确预留扩展点的规范。
|
||
|
||
3. **需求变更处理**：增加需求变更处理的指导，明确变更评估和文档更新流程。
|
||
|
||
计划在下一个迭代中更新提示词模板，增加上述内容。
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/2026-01-28-004-ToolingAPI源org实现.md)
|
||
- [子需求文档 - 连接管理](../requirements/sub/2026-01-28-004-01-连接管理.md)
|
||
- [设计文档](../design/2026-01-28-004-01-连接管理-设计.md)
|
||
- [决策记录](../decisions/2026-01-28-004-01-ADR-连接管理技术选型.md)
|
||
- [提示词](../prompts/2026-01-28-004-01-prompt-连接管理.md)
|
||
- [变更日志](../changelog/2026-01-28-004-01-changelog.md)
|
||
- [会话记录](../sessions/2026-01-28-004-session.md)
|
||
- [API 文档](./2026-01-28-004-api.md)
|