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-04-retro.md

13 KiB
Raw Blame History

复盘文档 - 代码覆盖率功能

元数据

  • 需求编号：002-04
  • 需求名称：代码覆盖率
  • 创建时间：2026-02-05
  • 创建人：AI Assistant
  • 版本：v2.0.0
  • 状态：已完成

复盘概述

本次复盘对 Salesforce Apex 代码覆盖率功能的开发过程进行了全面回顾，从需求定义到变更记录归档的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

代码覆盖率功能实现了 Salesforce Apex 代码覆盖率的查询、统计和分析功能，支持分页查询、多条件筛选、详情查询、总体统计和按类型统计等核心功能，生成 10 个新代码文件，新增 4 个 REST API 接口，完整遵循 SSOT 流程执行。

目标与实际产出对比

目标

  1. 实现 Salesforce Apex 代码覆盖率查询功能（支持分页、多条件筛选）
  2. 实现代码覆盖率详情查询功能
  3. 实现总体代码覆盖率统计功能
  4. 实现按类型（Class/Trigger）统计代码覆盖率功能
  5. 遵循 SSOT 流程，确保所有开发活动都有文档依据
  6. 生成符合项目规范的代码，包含完整单元测试
  7. 复用现有数据库表，不创建新表

实际产出

  1. 成功实现了代码覆盖率查询功能，支持按测试结果 ID、类/触发器名称、类型、命名空间、覆盖率范围等多条件筛选
  2. 成功实现了代码覆盖率详情查询功能，返回完整的覆盖率信息
  3. 成功实现了总体代码覆盖率统计功能，计算加权平均覆盖率
  4. 成功实现了按类型统计功能，分别统计 Class 和 Trigger 的覆盖率
  5. 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求、设计、决策、提示词、会话、变更记录）
  6. 生成的代码符合项目规范，包含 9 个测试方法的完整单元测试，覆盖正常场景、异常场景和边界条件
  7. 复用了 002-02 的 datai_apex_code_coverage 表，无需数据库变更
  8. 生成 10 个新代码文件（2 个 DTO + 4 个 VO + 2 个 Service + 1 个 Controller + 1 个单元测试）
  9. 新增 4 个 REST API 接口

成功经验

1. 数据库表复用策略的成功实施

本次开发采用了复用现有数据库表的策略，避免了数据冗余和不一致。通过扫描现有的 datai_apex_code_coverage 表，确认其包含所有必要字段（id、test_result_id、name、type、namespace、num_locations、num_locations_not_covered、coverage_percent 等），完全满足代码覆盖率功能的业务需求。这一决策显著减少了开发工作量，避免了不必要的数据库变更，同时保持了数据模型的一致性。

2. 完整的 SSOT 流程执行

从需求定义到变更记录归档的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。需求文档完整描述了功能需求和验收标准，设计文档详细说明了技术方案和实现细节，决策记录明确了关键技术选型，提示词文档提供了准确的代码生成指导，会话记录完整记录了开发过程中的对话和决策，变更记录归档了所有变更内容。这种完整的文档体系显著提高了代码的可追溯性和可维护性。

3. 详细的提示词设计确保代码质量

阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求。提示词明确指定了需要生成的 10 个代码文件及其路径和命名规范，详细描述了每个 DTO、VO、Service、Controller 的字段和方法要求，明确了代码规范（命名规范、注释规范、代码格式、异常处理、日志规范），并要求单元测试覆盖率不低于 80%。这些详细的提示词要求确保了生成的代码完全符合项目规范和需求。

4. 完整的单元测试覆盖

生成的单元测试（ApexCodeCoverageServiceImplTest）包含 9 个测试方法，覆盖了正常场景（查询列表、查询详情、统计总体覆盖率、统计类型覆盖率）、异常场景（记录不存在、参数验证失败）和边界条件（空结果集、边界覆盖率值）。完整的测试覆盖确保了代码的可靠性和健壮性，降低了生产环境的故障风险。

5. Stream API 和 PageHelper 的高效结合

代码实现中采用了 PageHelper 进行物理分页，Stream API 进行数据转换和过滤的策略。PageHelper 保证了分页查询的性能，避免了内存溢出问题；Stream API 提供了简洁优雅的数据处理方式，支持覆盖率计算（保留两位小数）、分组统计等功能。这种技术组合既保证了查询性能，又提高了代码的可读性和可维护性。

改进点

1. 阶段间过渡的解释可以更充分

在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入代码生成阶段时，可以详细说明代码生成器的工作原理和局限性，帮助用户更好地理解生成结果。

2. 基础代码与业务代码的区分可以更清晰

代码生成器生成的基础代码（Entity、Mapper、基础 Service）与业务专用代码（DTO、VO、业务 Service、Controller）在目录结构和命名规范上可以更清晰地区分，便于后续维护和代码审查。

3. API 文档的自动生成可以探索

目前 API 文档是手动编写的，可以探索使用 Swagger/OpenAPI 规范自动生成 API 文档，提高文档的准确性和维护性，减少文档与代码不一致的风险。

4. 变更日志的粒度可以更细

当前变更日志记录了功能级别的变更，可以进一步细化到代码文件级别的变更追踪，便于代码审查和问题定位。

问题分析

问题 1：数据库表扫描需要人工判断

问题描述：在阶段 4 判断是否需要数据库变更时，需要人工扫描现有 SQL 文件判断表结构是否满足需求，这个过程比较繁琐且容易出错。

根因：缺乏自动化的数据库表结构验证工具，无法自动检查现有表是否包含所有必要字段和索引。

解决方案：后续可以开发数据库表结构验证工具，自动扫描并验证现有表结构是否满足新功能需求，减少人工判断的工作量和错误风险。

问题 2：代码生成器的局限性

问题描述：代码生成器主要生成基础代码（Entity、Mapper、基础 Service），业务专用代码（DTO、VO、业务 Service、Controller）仍需要手动编写或修改。

根因：代码生成器的模板设计主要面向 CRUD 基础代码生成，对于复杂的业务逻辑代码生成能力有限。

解决方案：扩展代码生成器的模板库，增加更多业务场景的代码生成模板，提高代码生成的覆盖面和智能化程度。

问题 3：索引更新可能遗漏

问题描述：在更新索引文件时，需要手动添加新创建的文档链接，存在遗漏的风险。

根因：索引更新是手动操作，依赖于开发人员的记忆和细心程度。

解决方案：实现索引文件的自动更新机制，在创建新文档时自动更新索引，减少人工操作带来的遗漏风险。

行动计划

短期行动计划（立即执行）

  1. 针对改进点 1：在阶段转换时，增加对下一阶段的目的和流程的解释，提高用户的理解和参与度

    • 责任人：AI Assistant
    • 优先级：高

  2. 针对改进点 2：在代码生成时，更清晰地标记基础代码与业务代码的区分，便于后续维护

    • 责任人：AI Assistant
    • 优先级：中

  3. 针对问题 1：在项目规则中添加数据库表结构验证的检查清单，减少人工判断的遗漏

    • 责任人：AI Assistant
    • 优先级：中

中期行动计划（下一个迭代）

  1. 针对改进点 3：探索 Swagger/OpenAPI 规范自动生成 API 文档的可行性

    • 责任人：项目团队
    • 优先级：中

  2. 针对改进点 4：优化变更日志模板，增加代码文件级别的变更追踪

    • 责任人：AI Assistant
    • 优先级：低

  3. 针对问题 2：扩展代码生成器的模板库，增加更多业务场景的代码生成模板

    • 责任人：项目团队
    • 优先级：中

长期行动计划（后续优化）

  1. 针对问题 3：开发索引文件自动更新机制，实现文档创建的自动化追踪
    • 责任人：项目团队
    • 优先级：低

提取模式

有效的 Prompt 技巧

1. 具体的输出格式要求

在提示词中明确指定需要生成的文件、路径、格式等，可以显著提高生成代码的准确性和规范性。例如，明确列出每个 DTO 的字段、类型、注释要求，每个 VO 的属性和方法要求，每个 Service 接口和实现的方法签名和业务逻辑要求，每个 Controller 的接口路径和 HTTP 方法要求。这种具体的要求可以减少生成代码的返工率。

2. 引用真源

在提示词开头引用需求文档、设计文档、决策记录的链接，确保生成的代码符合需求和设计要求。引用真源可以帮助 AI 更好地理解业务背景和技术约束，避免生成不符合要求的代码。

3. 详细的代码规范要求

在提示词中明确指定代码规范、命名规范、注释规范、异常处理规范、日志规范等，可以提高生成代码的质量和可读性。例如，要求使用 Swagger 注解装饰接口，要求使用 SLF4J 进行日志记录，要求返回统一的结果格式（ResultVo），这些具体的要求可以确保生成的代码符合项目整体规范。

4. 明确的测试要求

在提示词中明确指定单元测试的覆盖范围、测试方法数量、测试场景（正常场景、异常场景、边界条件），可以确保生成的测试代码具有足够的质量。例如，要求测试覆盖率不低于 80%，包含记录不存在、空结果集、边界值等测试场景，这些要求可以显著提高测试代码的完整性。

避免的坑

1. 不要使用模糊的描述

在提示词中使用模糊的描述（如"请生成高质量的代码"、"实现查询功能"），会导致生成的代码不符合预期。应该使用具体的描述（如"使用 PageHelper 进行物理分页"、"返回分页结果包含 total、rows、code、msg 字段"），确保 AI 准确理解需求。

2. 不要忽略测试要求

在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该在提示词中明确要求生成单元测试，并指定测试方法和场景的要求。

3. 不要违反项目规则

在代码生成过程中违反项目规则（如不遵循若依框架规范、不使用统一的结果格式），会导致生成的代码不符合项目要求，需要重新生成。应该严格遵守项目规则，确保生成的代码可以直接用于生产环境。

4. 不要跳过文档更新

在创建新文档后，不要跳过索引更新、需求文档更新、会话记录更新等步骤，这些文档是 SSOT 架构的重要组成部分，跳过会导致文档体系不完整，影响后续的维护和追溯工作。

模板迭代

经过本次复盘，发现当前的文档模板体系基本完善，但有以下改进建议：

1. 提示词模板优化

当前的提示词模板已经包含了引用真源、需求描述、设计方案、输出格式要求、代码规范要求、测试要求等核心章节。建议增加以下章节：

  • 代码生成器配置说明：明确代码生成器的配置参数和生成范围
  • 基础代码与业务代码分离指南：指导如何区分和使用基础代码与业务代码
  • 数据库表结构验证检查清单：列出验证现有表结构是否满足需求的检查项

2. 变更日志模板优化

当前的变更日志模板已经包含了变更内容、详细变更清单、API 变更清单、代码变更清单等章节。建议增加以下章节：

  • 代码文件级别变更：详细列出每个代码文件的变更内容
  • 数据库变更（如有）：记录数据库表结构和索引的变更
  • 向后兼容性评估：评估变更是否影响现有功能

3. 复盘文档模板优化

当前的复盘文档模板已经包含了元数据、复盘概述、目标与实际产出对比、成功经验、改进点、问题分析、行动计划、提取模式、模板迭代等章节。建议优化以下内容：

  • 数据指标量化：增加可量化的指标（如代码行数、测试覆盖率、API 接口数量等）
  • 时间线回顾：增加开发过程的时间线回顾，便于了解各阶段耗时
  • 资源消耗分析：分析开发过程中的资源消耗（如文档数量、代码文件数量、会议次数等）

相关文档