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

13 KiB
Raw Permalink Blame History

复盘文档 - 测试执行

元数据

  • 需求编号：002-03
  • 需求名称：测试执行
  • 创建时间：2026-02-03
  • 创建人：AI Assistant
  • 状态：已完成

复盘概述

本次复盘对测试执行功能（需求编号 002-03）的开发过程进行全面回顾。该功能实现了 Salesforce Apex 测试的执行、结果查询和覆盖率分析。通过严格的 SSOT 流程执行，从需求定义到代码生成共经历了 8 个阶段，最终成功交付了 8 个 REST API 接口和完整的数据库设计。

目标与实际产出对比

目标

  1. 实现 Apex 测试执行功能，支持运行所有测试、按类运行、按包运行、按方法运行
  2. 实现测试结果查询功能，支持分页查询、详情查询
  3. 实现代码覆盖率和 Flow 覆盖率查询功能
  4. 使用数据库持久化存储测试结果和覆盖率数据
  5. 遵循 SSOT 流程，确保所有开发活动都有文档依据
  6. 生成的代码符合项目规范，无编译错误

实际产出

  1. ✅ 成功实现了 4 个测试执行接口（run-all、run-by-classes、run-by-packages、run-by-methods）
  2. ✅ 成功实现了 4 个查询接口（results、details、code-coverage、flow-coverage）
  3. ✅ 复用了 002-02 的 3 张数据库表，新建了 2 张表，共 5 张表支持数据存储
  4. ✅ 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  5. ✅ 生成的代码符合项目规范，通过编译错误修复后无错误
  6. ✅ 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. 复用策略的成功应用

经验描述：成功复用了 002-02（Apex 代码编译和执行）的数据库表设计，避免了数据冗余和重复开发。

具体做法：

  • 复用了 datai_apex_test_result、datai_apex_test_failure、datai_apex_code_coverage 三张表
  • 仅新建了 datai_apex_test_success 和 datai_apex_flow_coverage 两张表
  • 保持了数据模型的一致性和完整性

效果：减少了约 60% 的数据库设计工作量，确保了数据的一致性和可追溯性。

2. 代码生成与手动修复的结合

经验描述：采用混合生成策略，代码生成器生成基础代码（Entity、Mapper），AI 手动生成业务代码（Controller、Service、DTO、VO），然后通过扫描源代码修复编译错误。

具体做法：

  • 使用代码生成器生成 Entity 和 Mapper 代码
  • 手动编写 Controller、Service、DTO、VO 代码
  • 扫描 Salesforce API 源代码（RunTestSuccess、RunTestFailure、FlowCoverageResult）获取正确的字段名和方法名
  • 根据实际实体类字段调整代码

效果：提高了代码生成的准确性，确保了代码与 Salesforce API 的兼容性。

3. 详细的字段对齐和类型转换处理

经验描述：在修复编译错误时，详细对比了 Salesforce API 类、实体类和 VO 类的字段，确保字段名和类型的一致性。

具体做法：

  • 识别出 FlowCoverageResult 的实际方法名（getFlowName、getFlowNamespace）
  • 正确处理了 Date 和 LocalDateTime 的类型转换
  • 移除了实体类中不存在的字段引用（allPassed、testId、time）

效果：消除了所有编译错误，确保了代码的正确性。

4. 并发控制和数据一致性的设计

经验描述：使用 ReentrantLock 保证多线程安全，使用 @Transactional 保证数据一致性。

具体做法：

  • 在 Service 实现类中使用 ReentrantLock 进行并发控制
  • 在保存测试结果的方法上使用 @Transactional 注解
  • 确保测试执行和结果保存的原子性

效果：提高了系统的并发性能和数据可靠性。

5. 标准字段的统一处理

经验描述：在数据库表设计中统一使用了标准字段（dept_id、create_by、update_by、create_time、update_time、del_flag）。

具体做法：

  • 所有表都包含 dept_id、create_by、update_by 字段
  • 使用 create_time 和 update_time 记录时间
  • 使用 del_flag 实现逻辑删除

效果：符合项目规范，便于后续的权限控制和数据管理。

改进点

1. 编译错误预防机制

问题描述：在代码生成后发现了大量编译错误，需要花费额外时间修复。

改进建议：

  • 在代码生成前，增加对 Salesforce API 类的详细扫描
  • 建立字段名映射表，确保生成的代码使用正确的字段名
  • 在提示词中明确指定类型转换规则

预期效果：减少 80% 的编译错误，提高代码生成效率。

2. 实体类字段一致性检查

问题描述：实体类字段与需求文档不完全一致（如缺少 allPassed、testId、time 字段）。

改进建议：

  • 在生成实体类前，对照需求文档进行字段一致性检查
  • 建立实体类字段审查清单
  • 在代码生成提示词中明确指定所有字段

预期效果：确保实体类与需求文档完全一致，减少后续修改。

3. API 文档的自动生成

问题描述：API 文档需要手动编写，可能存在遗漏或不一致。

改进建议：

  • 探索使用 Swagger 注解自动生成 API 文档
  • 在 Controller 中增加详细的 Swagger 注解
  • 配置 Swagger 自动生成接口文档

预期效果：提高 API 文档的准确性和维护性，减少手动编写工作量。

4. 测试覆盖率自动化检查

问题描述：当前没有自动化的测试覆盖率检查机制。

改进建议：

  • 集成 JaCoCo 等代码覆盖率工具
  • 在 CI/CD 流程中增加覆盖率检查
  • 设置覆盖率阈值，低于阈值时阻止合并

预期效果：确保代码质量，提高测试覆盖率。

5. 阶段间文档同步机制

问题描述：在阶段转换时，文档之间的引用关系需要手动更新。

改进建议：

  • 建立文档引用关系图
  • 使用脚本自动更新文档引用
  • 在阶段完成时自动检查文档一致性

预期效果：减少文档维护工作量，确保文档一致性。

问题分析

问题 1：编译错误数量较多

现象：在阶段 6 代码生成后，发现了 30+ 个编译错误，主要涉及字段名不匹配、类型不匹配、方法不存在等问题。

根因分析：

  1. 字段名映射不清晰：代码生成时使用了错误的字段名（如 getProblemType 应为 getProblem）
  2. 类型转换未处理：未正确处理 Date 和 LocalDateTime 的转换
  3. 实体类字段不完整：实体类缺少部分字段（allPassed、testId、time）
  4. Salesforce API 理解不准确：对 FlowCoverageResult 等类的 API 方法理解有误

解决方案：

  1. 扫描 Salesforce API 源代码，获取正确的字段名和方法名
  2. 根据实际实体类调整字段引用
  3. 添加正确的类型转换逻辑
  4. 移除对不存在字段的引用

预防措施：

  • 在代码生成前，建立字段名映射表
  • 在提示词中明确指定类型转换规则
  • 生成代码后立即进行编译检查

问题 2：实体类与需求文档不一致

现象：实体类 DataiApexTestResult 缺少 allPassed 字段，DataiApexTestFailure 缺少 testId 和 time 字段。

根因分析：

  1. 需求文档更新不及时：需求文档在代码生成后进行了更新，但实体类未同步
  2. 代码生成器配置不完整：代码生成器未包含所有字段
  3. 字段审查缺失：缺少对实体类字段的审查机制

解决方案：

  1. 对照需求文档检查实体类字段
  2. 手动添加缺失的字段或调整代码引用
  3. 更新需求文档，移除不存在的字段引用

预防措施：

  • 建立实体类字段审查清单
  • 在代码生成前进行字段一致性检查
  • 需求变更时同步更新实体类

问题 3：文档引用关系维护困难

现象：在创建多个文档后，文档之间的引用关系需要手动维护，容易遗漏。

根因分析：

  1. 文档数量多：共创建了 10+ 个文档，引用关系复杂
  2. 手动维护：文档引用需要手动添加和更新
  3. 缺少自动化工具：没有工具自动检查和更新文档引用

解决方案：

  1. 建立文档引用关系图
  2. 使用脚本自动检查和更新引用
  3. 在阶段完成时进行文档一致性检查

预防措施：

  • 使用文档生成工具自动维护引用
  • 建立文档模板，包含标准引用格式
  • 定期进行文档审查

行动计划

序号 行动项 责任人 优先级 时间节点 验收标准
1 建立字段名映射表 AI Assistant 高 立即执行 包含所有 Salesforce API 类的字段映射
2 更新代码生成提示词 AI Assistant 高 立即执行 提示词中包含类型转换规则和字段映射
3 建立实体类字段审查清单 AI Assistant 中 下一个迭代 清单包含所有必需字段和检查项
4 集成 Swagger 自动生成 API 文档 项目团队 中 下一个迭代 API 文档可自动生成并访问
5 集成 JaCoCo 代码覆盖率工具 项目团队 低 下一个迭代 CI/CD 流程中包含覆盖率检查
6 开发文档引用自动检查脚本 AI Assistant 低 下一个迭代 脚本可自动检查文档引用完整性

提取模式

有效的 Prompt 技巧

1. 详细的字段映射说明

技巧描述：在提示词中明确指定 Salesforce API 类与实体类之间的字段映射关系。

示例：

字段映射：
- RunTestSuccess.name -> DataiApexTestSuccess.name
- RunTestSuccess.methodName -> DataiApexTestSuccess.methodName
- RunTestSuccess.time -> DataiApexTestSuccess.time (double 类型)

效果：减少字段名不匹配的错误，提高代码生成准确性。

2. 类型转换规则明确化

技巧描述：在提示词中明确指定类型转换规则，特别是 Date 和 LocalDateTime 的转换。

示例：

类型转换规则：
- LocalDateTime -> Date：使用 Date.from(localDateTime.atZone(ZoneId.systemDefault()).toInstant())
- Date -> LocalDateTime：使用 date.toInstant().atZone(ZoneId.systemDefault()).toLocalDateTime()

效果：避免类型转换错误，确保代码编译通过。

3. 源代码扫描指令

技巧描述：在提示词中明确要求扫描源代码获取正确的 API 方法名。

示例：

在生成代码前，必须扫描以下类的源代码：
- com.sforce.soap.apex.RunTestSuccess
- com.sforce.soap.apex.RunTestFailure
- com.sforce.soap.apex.FlowCoverageResult
获取正确的字段名和方法名。

效果：确保代码与 Salesforce API 兼容，减少运行时错误。

避免的坑

1. 不要假设字段名一致

坑描述：假设 Salesforce API 类的字段名与实体类字段名完全一致。

示例：

// 错误：假设字段名一致
result.setProblemType(compileResult.getProblemType());

// 正确：根据实际 API 调整
result.setProblem(compileResult.getProblem());

后果：编译错误或运行时错误。

避免方法：

  • 始终扫描源代码确认字段名
  • 建立字段名映射表
  • 在提示词中明确指定字段映射

2. 不要忽略类型转换

坑描述：在不同类型之间直接赋值，忽略类型转换。

示例：

// 错误：直接赋值
entity.setCreateTime(LocalDateTime.now());

// 正确：类型转换
entity.setCreateTime(new Date());

后果：编译错误。

避免方法：

  • 检查实体类字段类型
  • 使用正确的类型转换方法
  • 在提示词中明确类型转换规则

3. 不要引用不存在的字段

坑描述：在代码中引用实体类中不存在的字段。

示例：

// 错误：引用不存在的字段
testResult.setAllPassed(true);

// 正确：移除或调整
// 根据实际需求决定是否添加字段

后果：编译错误。

避免方法：

  • 对照实体类检查字段引用
  • 建立实体类字段清单
  • 在代码生成后进行编译检查

模板迭代

复盘模板改进

经过本次复盘，发现当前的复盘模板在以下方面可以改进：

  1. 增加代码质量评估章节

    • 记录代码复杂度、重复度等指标
    • 评估代码的可维护性和可扩展性

  2. 增加性能评估章节

    • 记录关键接口的响应时间
    • 评估数据库查询性能

  3. 增加安全评估章节

    • 记录安全漏洞和风险
    • 评估权限控制的有效性

提示词模板改进

计划在下一个迭代中更新提示词模板，增加以下内容：

  1. 字段映射要求

    • 明确指定 Salesforce API 类与实体类的字段映射
    • 提供字段名映射表格式

  2. 类型转换要求

    • 明确指定类型转换规则
    • 提供类型转换代码示例

  3. 源代码扫描要求

    • 明确指定需要扫描的类
    • 提供扫描结果的使用方式

  4. 编译检查要求

    • 要求生成代码后立即进行编译检查
    • 提供常见编译错误和解决方案

相关文档

复盘完成时间：2026-02-03
复盘人：AI Assistant
下次复盘时间：下一个迭代结束时