187 lines
9.2 KiB
Markdown
187 lines
9.2 KiB
Markdown
# 复盘文档 - 代码覆盖率功能
|
||
|
||
## 元数据
|
||
- 需求编号：002-04
|
||
- 需求名称：代码覆盖率
|
||
- 创建时间：2026-02-03
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对代码覆盖率功能的开发过程进行了全面回顾，从需求定义到变更归档的每个阶段都进行了分析。代码覆盖率功能是 Apex 开发工具包的重要组成部分，通过复用测试执行功能的数据库表，实现了代码覆盖率查询和统计功能。本次复盘总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现代码覆盖率查询功能，支持多条件筛选、分页查询、覆盖率范围筛选
|
||
- 实现代码覆盖率详情查询功能
|
||
- 实现总体代码覆盖率统计功能（总体、类、触发器）
|
||
- 实现按类型统计代码覆盖率功能（Class/Trigger 分组）
|
||
- 复用 002-03 测试执行功能的数据库表，避免重复建表
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码
|
||
|
||
### 实际产出
|
||
- 成功实现了代码覆盖率查询功能，支持多条件筛选、分页查询、覆盖率范围筛选
|
||
- 成功实现了代码覆盖率详情查询功能
|
||
- 成功实现了总体代码覆盖率统计功能（总体、类、触发器）
|
||
- 成功实现了按类型统计代码覆盖率功能（Class/Trigger 分组）
|
||
- 复用了 002-03 的 `datai_apex_code_coverage` 表，避免了重复建表
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成了符合项目规范的代码，包含 4 个 REST API 接口、7 个代码文件
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
|
||
## 成功经验
|
||
|
||
### 1. 数据库表复用策略的成功实践
|
||
本功能通过复用 002-03 测试执行功能的 `datai_apex_code_coverage` 表，避免了重复建表，减少了数据库维护成本。这一策略的成功实践证明了在功能开发中，通过合理的设计和规划，可以实现资源的有效复用。
|
||
|
||
### 2. 独立 Service 层的设计
|
||
通过创建独立的 `IApexCodeCoverageService` 接口和实现，与 `ApexTestService` 分离，使得代码覆盖率功能的职责更加清晰。这种设计模式提高了代码的可维护性和可测试性。
|
||
|
||
### 3. 覆盖率计算算法的精确实现
|
||
实现了精确的覆盖率计算算法，包括：
|
||
- 单个类/触发器覆盖率：(1 - numLocationsNotCovered / numLocations) * 100
|
||
- 总体覆盖率：汇总所有类的总位置数和未覆盖位置数后计算
|
||
- 保留两位小数，除零保护
|
||
|
||
这种精确的实现确保了覆盖率统计的准确性。
|
||
|
||
### 4. SSOT 流程的严格执行
|
||
从需求定义到变更归档的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。这种严格的流程执行提高了代码的可追溯性和可维护性。
|
||
|
||
### 5. 详细的提示词设计
|
||
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词中明确指定了需要生成的文件、路径、格式等，提高了生成代码的准确性和规范性。
|
||
|
||
## 改进点
|
||
|
||
### 1. 覆盖率范围筛选的性能优化
|
||
当前覆盖率范围筛选（最小覆盖率、最大覆盖率）是在内存中进行的，因为覆盖率是计算字段。对于大数据量场景，这种筛选方式可能会影响性能。可以考虑：
|
||
- 在数据库表中增加覆盖率字段，实现数据库层面的筛选
|
||
- 使用缓存机制，减少重复计算
|
||
|
||
### 2. 代码覆盖率数据的可视化
|
||
当前功能只提供了数据查询和统计接口，缺少可视化展示。可以考虑：
|
||
- 增加覆盖率趋势分析功能
|
||
- 提供覆盖率报告导出功能（PDF、Excel 等）
|
||
- 增加覆盖率对比功能（不同版本、不同时间）
|
||
|
||
### 3. 代码覆盖率警告的实时通知
|
||
当前功能缺少代码覆盖率警告的实时通知机制。可以考虑：
|
||
- 当代码覆盖率低于阈值时，发送邮件或消息通知
|
||
- 集成到 CI/CD 流程中，实现自动化检查
|
||
|
||
### 4. 更细粒度的代码覆盖率分析
|
||
当前功能只提供了类/触发器级别的覆盖率统计。可以考虑：
|
||
- 提供方法级别的覆盖率分析
|
||
- 提供代码行级别的覆盖率展示
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：部分 VO 和 DTO 已在 002-03 中生成
|
||
**现象**：在阶段 6 代码生成时，发现部分 VO 和 DTO（如 `QueryCodeCoverageDto.java`、`CodeCoverageResultVo.java`）已在 002-03 测试执行功能中生成。
|
||
|
||
**根因**：
|
||
- 002-03 测试执行功能在存储代码覆盖率数据时，需要这些 VO 和 DTO
|
||
- 002-04 功能复用了 002-03 的数据库表，因此也复用了相关的 VO 和 DTO
|
||
|
||
**解决方案**：
|
||
- 在代码生成前，先扫描项目目录，识别已存在的代码文件
|
||
- 对于已存在的文件，不再重复生成，只生成新增的文件
|
||
- 在变更日志中明确标注复用的代码文件
|
||
|
||
**预防措施**：
|
||
- 在阶段 2 方案设计时，更仔细地分析已有功能的代码结构
|
||
- 在阶段 5 提示词生成时，明确说明哪些代码文件需要生成，哪些需要复用
|
||
|
||
### 问题 2：覆盖率计算字段的筛选性能
|
||
**现象**：覆盖率范围筛选（最小覆盖率、最大覆盖率）需要在内存中进行，因为覆盖率是计算字段。
|
||
|
||
**根因**：
|
||
- 数据库表中只存储了 `numLocations` 和 `numLocationsNotCovered`，没有存储计算后的覆盖率
|
||
- 覆盖率计算需要在查询后进行
|
||
|
||
**解决方案**：
|
||
- 在内存中进行覆盖率范围筛选
|
||
- 使用 Java 8 Stream API 进行高效的内存筛选
|
||
|
||
**预防措施**：
|
||
- 在设计阶段，考虑是否需要在数据库表中增加覆盖率字段
|
||
- 评估数据量和性能要求，选择合适的方案
|
||
|
||
## 行动计划
|
||
|
||
| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|
||
|------|--------|--------|----------|--------|
|
||
| 1 | 评估覆盖率范围筛选的性能，必要时优化 | 开发团队 | 下一个迭代 | 中 |
|
||
| 2 | 设计代码覆盖率数据可视化方案 | 产品团队 | 下一个迭代 | 低 |
|
||
| 3 | 设计代码覆盖率警告通知机制 | 产品团队 | 下一个迭代 | 低 |
|
||
| 4 | 在阶段 2 方案设计时，更仔细地分析已有功能的代码结构 | AI Assistant | 立即执行 | 高 |
|
||
| 5 | 在阶段 5 提示词生成时，明确说明哪些代码文件需要生成，哪些需要复用 | AI Assistant | 立即执行 | 高 |
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
#### 1. 明确的代码复用说明
|
||
在提示词中明确说明哪些代码文件需要生成，哪些需要复用，可以避免重复生成和代码冲突。例如：
|
||
```
|
||
注意：以下文件已在 002-03 中生成，请复用，不要重复生成：
|
||
- QueryCodeCoverageDto.java
|
||
- CodeCoverageResultVo.java
|
||
- DataiApexCodeCoverageMapper.java
|
||
- DataiApexCodeCoverage.java
|
||
```
|
||
|
||
#### 2. 详细的算法描述
|
||
在提示词中详细描述算法逻辑，可以确保生成的代码符合预期。例如：
|
||
```
|
||
覆盖率计算算法：
|
||
- 单个类覆盖率：(1 - numLocationsNotCovered / numLocations) * 100
|
||
- 保留两位小数，使用 BigDecimal 进行精确计算
|
||
- 除零保护：当 numLocations 为 0 时，返回 0.0
|
||
```
|
||
|
||
#### 3. 具体的异常处理要求
|
||
在提示词中明确指定异常处理要求，可以提高代码的健壮性。例如：
|
||
```
|
||
异常处理要求：
|
||
- 所有 Service 方法必须声明 throws SalesforceOperationException
|
||
- 使用 try-catch 块捕获 Salesforce API 异常
|
||
- 记录详细的错误日志
|
||
```
|
||
|
||
### 避免的坑
|
||
|
||
#### 1. 不要忽略已有代码的复用
|
||
在生成代码前，必须先扫描项目目录，识别已存在的代码文件。忽略已有代码的复用会导致代码重复、冲突和维护困难。
|
||
|
||
#### 2. 不要忽略性能考虑
|
||
在设计阶段，必须考虑性能要求。对于大数据量场景，内存筛选可能会影响性能，需要提前规划优化方案。
|
||
|
||
#### 3. 不要忽略数据一致性
|
||
在复用其他功能的数据库表时，必须确保数据一致性。例如，本功能复用了 002-03 的 `datai_apex_code_coverage` 表，需要确保数据格式和字段含义的一致性。
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
### 1. 增加代码复用分析章节
|
||
在提示词模板中增加"代码复用分析"章节，要求分析哪些代码文件可以复用，哪些需要新生成。
|
||
|
||
### 2. 增加性能考虑章节
|
||
在提示词模板中增加"性能考虑"章节，要求分析大数据量场景下的性能问题，并提出优化方案。
|
||
|
||
### 3. 增加数据一致性检查章节
|
||
在提示词模板中增加"数据一致性检查"章节，要求在复用其他功能的数据库表时，检查数据格式和字段含义的一致性。
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../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-03-002-04-prompt-代码覆盖率.md)
|
||
- [变更日志](../changelog/2026-02-03-002-04-changelog.md)
|
||
- [会话记录](../sessions/2026-02-03-002-04-session.md)
|
||
- [API 文档](../api-docs/2026-02-03-002-04-api.md)
|