193 lines
9.2 KiB
Markdown
193 lines
9.2 KiB
Markdown
# 复盘文档 - 高级功能 (004-07)
|
||
|
||
## 元数据
|
||
- **需求编号**: 004-07
|
||
- **需求名称**: 高级功能
|
||
- **创建时间**: 2026-02-06
|
||
- **创建人**: AI Assistant
|
||
- **状态**: 已完成
|
||
|
||
---
|
||
|
||
## 复盘概述
|
||
|
||
本次复盘对 Tooling API 高级功能模块的开发过程进行了全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
高级功能模块实现了 12 个元数据类型的查询功能，包括聚合和计算、预测和预测、激活和应用三大类功能，为 Salesforce Tooling API 的高级元数据查询提供了完整的支持。
|
||
|
||
---
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 12 个元数据类型的查询功能
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码
|
||
- 提供完整的 REST API 接口
|
||
|
||
### 实际产出
|
||
- 成功实现了 12 个元数据类型的查询功能：
|
||
- 聚合和计算：AccumulateResultOperator、AccumulateResultCondInputType、AggregateExpressionResultColumnMetadata、AggregateQueryResultColumnMetadata
|
||
- 预测和预测：AdvAcctFrcstDisplayGroupType、AdvAcctFcstMeasureType、AdvAcctFcstFormulaType、AdvAcctFcstComputationMethod
|
||
- 激活和应用：ActivationFlowType、ActivationFeatureType、ActivationAppType、ACPStatus
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成了 25 个代码文件（7 个代码生成器生成 + 18 个手动实现）
|
||
- 提供了 12 个 REST API 接口
|
||
- 定义了 14 个错误码
|
||
- 创建了 1 个数据库表用于操作日志记录
|
||
|
||
---
|
||
|
||
## 成功经验
|
||
|
||
### 1. SSOT 流程的严格执行
|
||
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。特别是在阶段 4（数据库结构）中，详细比对了 SQL 脚本和需求文档，确保了数据库设计的准确性。
|
||
|
||
### 2. 代码生成器与手动实现的良好结合
|
||
代码生成器生成了基础的 CRUD 代码（Entity、Mapper、Service、Controller），而手动实现则专注于业务逻辑（元数据查询、DTO 转换、错误处理）。这种分工提高了开发效率，同时保证了代码质量。
|
||
|
||
### 3. 详细的 DTO 设计
|
||
为每个元数据类型设计了独立的 DTO 类，虽然字段简单（只有 name 和 description），但结构清晰，便于后续扩展。同时设计了统一的 Result 包装类，提高了接口响应的一致性。
|
||
|
||
### 4. 异步日志记录的设计
|
||
采用 Spring @Async 异步记录操作日志，避免了日志记录对主流程性能的影响。这种设计在之前的 004-05（动作和自动化）和 004-06（访问和安全）中也得到了验证，证明了其有效性。
|
||
|
||
### 5. 复用现有组件
|
||
复用了 004-01 的 ToolingConnectionFactory 进行连接管理，复用了 SoqlBuilder 工具类构建 SOQL 查询，减少了重复代码，提高了代码的可维护性。
|
||
|
||
---
|
||
|
||
## 改进点
|
||
|
||
### 1. DTO 字段可以更丰富
|
||
当前 DTO 只包含 name 和 description 两个字段，如果后续需要更多字段（如 Id、CreatedDate 等），需要修改 DTO 类和转换逻辑。建议在初始设计时考虑更全面的字段映射。
|
||
|
||
### 2. 缓存机制可以考虑
|
||
元数据类型通常是固定的枚举值，不会频繁变化。可以考虑引入缓存机制（如 Redis 或本地缓存），减少重复查询 Salesforce API 的次数，提高查询性能。
|
||
|
||
### 3. 批量查询接口可以考虑
|
||
当前每个元数据类型都有独立的查询接口，如果前端需要同时查询多个元数据类型，需要发起多次请求。可以考虑提供批量查询接口，一次性返回多个元数据类型的数据。
|
||
|
||
### 4. 接口文档的自动化生成
|
||
当前 API 文档是手动编写的，维护成本较高。可以探索使用 Swagger 或 SpringDoc 自动生成 API 文档，提高文档的准确性和维护性。
|
||
|
||
---
|
||
|
||
## 问题分析
|
||
|
||
### 问题 1：部分元数据类型在 Salesforce 中可能不存在
|
||
**现象**: 在开发过程中发现，部分元数据类型（如 AccumulateResultOperator）在某些 Salesforce 版本中可能不存在或不可访问。
|
||
|
||
**根因**: Salesforce 的不同版本和不同许可证类型对 Tooling API 的支持程度不同，部分高级功能可能只在特定版本中可用。
|
||
|
||
**解决方案**:
|
||
- 在文档中明确标注每个接口的 Salesforce 版本要求
|
||
- 在代码中增加对元数据类型不存在的处理，返回友好的错误提示
|
||
- 建议用户在使用前检查其 Salesforce 版本是否支持相应的元数据类型
|
||
|
||
### 问题 2：错误码设计过于细化
|
||
**现象**: 为 12 个查询接口设计了 12 个独立的错误码（TOOLING_ADVANCED_002 ~ TOOLING_ADVANCED_013），导致错误码数量较多。
|
||
|
||
**根因**: 希望为每个查询操作提供精确的错误定位，但过度细化的错误码增加了维护成本。
|
||
|
||
**解决方案**:
|
||
- 考虑将同类错误合并，如将所有查询失败错误合并为一个通用的"查询失败"错误码
|
||
- 在错误消息中提供具体的操作类型信息，便于问题定位
|
||
- 在日志中记录详细的错误信息，便于排查问题
|
||
|
||
### 问题 3：缺少单元测试
|
||
**现象**: 生成的代码中没有包含单元测试。
|
||
|
||
**根因**: 阶段 5 的提示词中没有明确要求生成单元测试。
|
||
|
||
**解决方案**:
|
||
- 在后续的提示词设计中，增加对单元测试的要求
|
||
- 明确指定单元测试的覆盖率要求（如不低于 80%）
|
||
- 明确指定测试用例的设计要求（包括正常场景和异常场景）
|
||
|
||
---
|
||
|
||
## 行动计划
|
||
|
||
| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|
||
|------|--------|--------|----------|--------|
|
||
| 1 | 在文档中标注 Salesforce 版本要求 | AI Assistant | 立即执行 | 高 |
|
||
| 2 | 优化错误码设计，合并同类错误 | AI Assistant | 下一个迭代 | 中 |
|
||
| 3 | 补充单元测试 | 开发团队 | 下一个迭代 | 高 |
|
||
| 4 | 探索缓存机制的实现 | 开发团队 | 后续迭代 | 低 |
|
||
| 5 | 探索批量查询接口的设计 | 开发团队 | 后续迭代 | 低 |
|
||
| 6 | 探索 Swagger 自动生成 API 文档 | 开发团队 | 后续迭代 | 低 |
|
||
|
||
---
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
1. **明确的文件路径要求**
|
||
在提示词中明确指定需要生成的文件的完整路径，可以避免文件生成到错误的位置。例如："在 `datai-salesforce-tooling/src/main/java/com/datai/tooling/dto/` 目录下创建 DTO 类"。
|
||
|
||
2. **分层的代码结构设计**
|
||
将代码按 Controller、Service、DTO、ErrorCode 等分层设计，每层独立生成，可以提高代码的可维护性和可读性。
|
||
|
||
3. **复用现有组件的明确指示**
|
||
在提示词中明确指示复用哪些现有组件（如 ToolingConnectionFactory、SoqlBuilder），可以避免重复造轮子，提高开发效率。
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要忽视 Salesforce 版本差异**
|
||
Salesforce 的不同版本对 Tooling API 的支持程度不同，开发前需要确认目标 Salesforce 版本是否支持相应的元数据类型。
|
||
|
||
2. **不要过度设计错误码**
|
||
错误码的设计需要在精确性和维护成本之间取得平衡，过度细化的错误码会增加维护成本。
|
||
|
||
3. **不要忽略单元测试**
|
||
单元测试是保证代码质量的重要手段，在代码生成阶段就应该考虑单元测试的生成。
|
||
|
||
---
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
1. **增加 Salesforce 版本兼容性检查要求**
|
||
在提示词中增加对 Salesforce 版本兼容性的检查要求，确保生成的代码能够在目标版本中正常运行。
|
||
|
||
2. **增加单元测试生成要求**
|
||
在提示词中明确指定需要生成单元测试，并明确测试覆盖率和测试用例设计要求。
|
||
|
||
3. **增加缓存机制设计建议**
|
||
对于查询类接口，在提示词中增加缓存机制的设计建议，提高查询性能。
|
||
|
||
计划在下一个迭代中更新提示词模板，增加上述内容。
|
||
|
||
---
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-004-07-高级功能.md)
|
||
- [设计文档](../design/2026-02-03-004-07-高级功能-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-07-ADR-高级功能技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-004-07-高级功能操作日志.sql)
|
||
- [变更日志](../changelog/2026-02-06-004-07-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-06-004-07-api.md)
|
||
- [会话记录](../sessions/2026-02-06-004-07-session.md)
|
||
|
||
---
|
||
|
||
## 总结
|
||
|
||
本次高级功能模块的开发过程总体顺利，严格按照 SSOT 流程执行，成功实现了 12 个元数据类型的查询功能。通过本次复盘，总结了成功经验，识别了改进点，制定了行动计划，为后续的开发工作提供了宝贵的经验。
|
||
|
||
特别值得肯定的是：
|
||
1. SSOT 流程的严格执行确保了开发过程的规范性和可追溯性
|
||
2. 代码生成器与手动实现的良好结合提高了开发效率
|
||
3. 异步日志记录的设计保证了系统性能
|
||
|
||
需要改进的方面包括：
|
||
1. DTO 字段设计可以更丰富，便于后续扩展
|
||
2. 错误码设计可以进一步优化，减少维护成本
|
||
3. 需要补充单元测试，提高代码质量
|
||
|
||
通过持续的复盘和改进，相信后续的开发工作会更加高效和规范。
|