206 lines
8.3 KiB
Markdown
206 lines
8.3 KiB
Markdown
# 复盘文档：Flow 覆盖率功能
|
||
|
||
## 元数据
|
||
- 需求编号：002-05
|
||
- 需求名称：Flow 覆盖率
|
||
- 创建时间：2026-02-05
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Flow 覆盖率功能的开发过程进行了全面回顾，从需求定义到变更日志归档的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Salesforce Apex Flow 覆盖率查询和统计功能
|
||
- 支持 Flow 覆盖率数据的存储、查询、统计和警告管理
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码（17 个代码文件）
|
||
- 提供 6 个 REST API 接口
|
||
|
||
### 实际产出
|
||
- 成功实现了 Flow 覆盖率查询、统计、警告查询等核心功能
|
||
- 创建了 2 张数据库表（datai_apex_flow_coverage、datai_apex_flow_coverage_warning）
|
||
- 创建了 2 个统计视图优化查询性能
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成了 17 个代码文件，符合项目规范
|
||
- 提供了 6 个 REST API 接口
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
|
||
## 成功经验
|
||
|
||
1. **SSOT 流程的严格执行**
|
||
- 从需求定义到变更日志归档的 8 个阶段都严格按照项目规则执行
|
||
- 每个阶段都有相应的文档记录，确保了所有开发活动都有文档依据
|
||
- 提高了代码的可追溯性和可维护性
|
||
|
||
2. **详细的提示词设计**
|
||
- 阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求
|
||
- 提示词中引用了真源（需求文档、设计文档、决策记录、SQL 脚本）
|
||
- 确保了生成的代码符合项目规范和需求
|
||
|
||
3. **完整的会话记录**
|
||
- 阶段 7 和阶段 8 记录了完整的会话过程
|
||
- 包括对话记录、生成的文档和代码、关键决策、回退记录等
|
||
- 确保了会话的可追溯性和完整性
|
||
|
||
4. **合理的架构决策**
|
||
- 采用分层架构（Controller -> Service -> Mapper -> Entity）
|
||
- Flow 覆盖率表与代码覆盖率表分离，避免数据混淆
|
||
- Service 层独立设计，遵循单一职责原则
|
||
- 为后续维护和扩展提供了良好的基础
|
||
|
||
5. **有效的回退机制**
|
||
- 在阶段 4 发现 002-04 代码覆盖率遗漏警告表时，及时执行回退
|
||
- 补充创建代码覆盖率警告表后，重新进入阶段 5
|
||
- 确保了数据库设计的完整性和一致性
|
||
|
||
## 改进点
|
||
|
||
1. **阶段间的过渡可以更流畅**
|
||
- 在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程
|
||
- 提高用户的理解和参与度
|
||
- 减少用户的认知负担
|
||
|
||
2. **API 接口设计可以更加统一**
|
||
- Flow 覆盖率 Controller 提供了完整的 CRUD 接口（6 个接口）
|
||
- 但设计文档中只规划了 5 个接口（缺少导出接口）
|
||
- 后续应在设计阶段就明确所有接口
|
||
|
||
3. **统计接口的实现可以更加完善**
|
||
- 设计文档中规划了总体覆盖率统计、按命名空间统计、按类型统计接口
|
||
- 但实际生成的代码中缺少这些统计接口的具体实现
|
||
- 后续应在代码生成阶段确保所有规划接口都实现
|
||
|
||
4. **单元测试的生成可以更加及时**
|
||
- 本次代码生成未包含单元测试
|
||
- 后续应在提示词中明确要求生成单元测试
|
||
- 提高代码的质量和可靠性
|
||
|
||
## 问题分析
|
||
|
||
1. **问题 1**：统计接口未完全实现
|
||
- **现象**：设计文档中规划了 3 个统计接口（总体覆盖率统计、按命名空间统计、按类型统计），但实际代码中缺少这些接口
|
||
- **根因**：代码生成器的模板可能未完全覆盖所有接口类型，或者提示词中对统计接口的描述不够具体
|
||
- **解决方案**：
|
||
- 在提示词中更详细地描述统计接口的要求
|
||
- 在代码生成后，人工检查是否所有规划接口都已实现
|
||
- 补充实现缺失的统计接口
|
||
|
||
2. **问题 2**：设计文档与实际代码不完全一致
|
||
- **现象**：设计文档规划了 5 个接口，但实际生成了 6 个接口（增加了导出接口）
|
||
- **根因**：代码生成器自动添加了导出功能，但设计文档未明确说明
|
||
- **解决方案**：
|
||
- 在设计文档中明确是否需要导出功能
|
||
- 保持设计文档与实际代码的一致性
|
||
|
||
3. **问题 3**：缺少单元测试
|
||
- **现象**：生成的 17 个代码文件中不包含单元测试
|
||
- **根因**：提示词中未明确要求生成单元测试
|
||
- **解决方案**：
|
||
- 在提示词中增加单元测试的生成要求
|
||
- 明确单元测试的覆盖范围和测试场景
|
||
|
||
## 行动计划
|
||
|
||
1. **针对改进点 1**
|
||
- 行动：在阶段转换时，增加对下一阶段的目的和流程的解释
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
2. **针对改进点 2**
|
||
- 行动：在设计阶段明确所有接口，包括是否需要导出功能
|
||
- 责任：AI Assistant
|
||
- 时间：下一个需求
|
||
|
||
3. **针对改进点 3**
|
||
- 行动：补充实现缺失的统计接口（总体覆盖率统计、按命名空间统计、按类型统计）
|
||
- 责任：AI Assistant
|
||
- 时间：2026-02-06
|
||
|
||
4. **针对改进点 4**
|
||
- 行动：在提示词中增加单元测试的生成要求
|
||
- 责任：AI Assistant
|
||
- 时间：下一个需求
|
||
|
||
5. **针对问题 1**
|
||
- 行动：在提示词中更详细地描述统计接口的要求
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
6. **针对问题 2**
|
||
- 行动：更新设计文档，添加导出接口的说明
|
||
- 责任：AI Assistant
|
||
- 时间：2026-02-06
|
||
|
||
7. **针对问题 3**
|
||
- 行动：为 Flow 覆盖率功能补充单元测试
|
||
- 责任：AI Assistant
|
||
- 时间：2026-02-06
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
1. **引用真源**
|
||
- 在提示词开头引用需求文档、设计文档、决策记录、SQL 脚本的链接
|
||
- 确保生成的代码符合需求和设计要求
|
||
- 示例："请基于以下真源文档生成代码：[需求文档链接]、[设计文档链接]"
|
||
|
||
2. **具体的输出格式要求**
|
||
- 明确指定需要生成的文件、路径、格式等
|
||
- 提高生成代码的准确性和规范性
|
||
- 示例："请生成以下文件：1. Entity 层：路径 xxx，包含字段 xxx"
|
||
|
||
3. **详细的代码规范要求**
|
||
- 明确指定代码规范、命名规范、注释规范等
|
||
- 提高生成代码的质量和可读性
|
||
- 示例："类名使用大驼峰命名，方法名使用小驼峰命名，字段需要添加注释"
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要忽略统计接口的具体要求**
|
||
- 在提示词中明确描述统计接口的计算逻辑和返回格式
|
||
- 避免生成的代码缺少关键接口
|
||
|
||
2. **不要假设代码生成器会自动处理所有细节**
|
||
- 在提示词中明确所有要求，包括导出功能、权限控制等
|
||
- 生成后需要人工检查代码完整性
|
||
|
||
3. **不要忘记单元测试**
|
||
- 在提示词中明确要求生成单元测试
|
||
- 明确单元测试的覆盖范围和测试场景
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
1. **增加统计接口的详细描述要求**
|
||
- 要求明确统计接口的计算逻辑
|
||
- 要求明确统计接口的返回格式
|
||
- 要求明确统计接口的查询条件
|
||
|
||
2. **增加单元测试的生成要求**
|
||
- 要求生成 Service 层的单元测试
|
||
- 要求覆盖正常和异常场景
|
||
- 要求使用 Mockito 进行模拟测试
|
||
|
||
3. **增加接口完整性检查要求**
|
||
- 要求对比设计文档中的接口列表
|
||
- 要求确保所有规划接口都已实现
|
||
- 要求检查是否有额外的接口（如导出功能）
|
||
|
||
计划在下一个迭代中更新提示词模板，增加以上要求。
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-002-05-Flow覆盖率.md)
|
||
- [设计文档](../design/2026-02-03-002-05-Flow覆盖率-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-002-05-ADR-Flow覆盖率技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-002-05-Flow覆盖率.sql)
|
||
- [提示词](../prompts/2026-02-03-002-05-prompt-Flow覆盖率.md)
|
||
- [变更日志](../changelog/2026-02-05-002-05-changelog.md)
|
||
- [会话记录](../sessions/2026-02-03-002-05-session.md)
|
||
- [API 文档](../api-docs/2026-02-05-002-05-api.md)
|