kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
27ce31edd3
datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-05-002-05-retro.md

8.3 KiB
Raw Blame History

复盘文档：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. 增加接口完整性检查要求

    • 要求对比设计文档中的接口列表
    • 要求确保所有规划接口都已实现
    • 要求检查是否有额外的接口（如导出功能）

计划在下一个迭代中更新提示词模板，增加以上要求。

相关文档