185 lines
13 KiB
Markdown
185 lines
13 KiB
Markdown
# 复盘文档 - 代码覆盖率功能
|
||
|
||
## 元数据
|
||
- 需求编号：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
|
||
- 优先级：中
|
||
|
||
### 中期行动计划（下一个迭代）
|
||
4. **针对改进点 3**：探索 Swagger/OpenAPI 规范自动生成 API 文档的可行性
|
||
- 责任人：项目团队
|
||
- 优先级：中
|
||
|
||
5. **针对改进点 4**：优化变更日志模板，增加代码文件级别的变更追踪
|
||
- 责任人：AI Assistant
|
||
- 优先级：低
|
||
|
||
6. **针对问题 2**：扩展代码生成器的模板库，增加更多业务场景的代码生成模板
|
||
- 责任人：项目团队
|
||
- 优先级：中
|
||
|
||
### 长期行动计划（后续优化）
|
||
7. **针对问题 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 接口数量等）
|
||
- **时间线回顾**：增加开发过程的时间线回顾，便于了解各阶段耗时
|
||
- **资源消耗分析**：分析开发过程中的资源消耗（如文档数量、代码文件数量、会议次数等）
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-002-04-代码覆盖率.md)
|
||
- [设计文档](../design/2026-02-03-002-04-代码覆盖率-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-002-04-ADR-代码覆盖率技术选型.md)
|
||
- [提示词文档](../prompts/2026-02-05-002-04-prompt-代码覆盖率.md)
|
||
- [会话记录](../sessions/2026-02-05-002-04-session.md)
|
||
- [变更日志 v2.0.0](../changelog/2026-02-05-002-04-changelog-v2.md)
|
||
- [API 文档](./2026-02-05-002-04-api.md)
|