7.3 KiB
复盘文档
元数据
- 需求编号：004-06
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 状态：已完成
复盘概述
本次复盘对 Tooling API 访问和安全功能（004-06）的开发过程进行了全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
目标与实际产出对比
目标
- 实现 Tooling API 访问和安全功能，包括访问方法查询、访问资源类型查询、API 访问级别查询、API 类型查询、激活平台连接器类型查询、激活平台创建类型查询
- 实现操作日志记录功能，支持异步记录访问和安全操作
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范和若依框架的代码
实际产出
- 成功实现了 6 个访问和安全查询接口（访问方法、访问资源类型、API 访问级别、API 类型、激活平台连接器类型、激活平台创建类型）
- 成功实现了操作日志记录功能，使用 Spring @Async 异步记录
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求、设计、决策、SQL、提示词、会话记录、变更日志）
- 生成了 20 个代码文件（7 个代码生成器生成 + 13 个手动实现），符合项目规范和若依框架要求
- 定义了 4 个标准错误码（TOOLING_ACCESS_001 ~ TOOLING_ACCESS_004）
- 创建了 1 个数据库表（datai_tooling_access_security_log）
成功经验
1. SSOT 流程的严格执行
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。特别是在阶段 4（数据库结构）中，详细比对了 SQL 脚本和需求文档，确保了数据库设计的准确性。
2. 代码生成器与手动实现的良好结合
代码生成器生成了基础的 CRUD 代码（Entity、Mapper、Service、Controller），而手动实现则专注于业务逻辑（访问和安全查询、DTO 转换、错误处理）。这种分工提高了开发效率，同时保证了代码质量。
3. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和接口规范要求，特别是明确了 7 个 REST API 接口的定义和 4 个错误码的设计，确保了生成的代码符合需求和设计要求。
4. 异步日志记录的设计
采用 Spring @Async 异步记录操作日志，避免了日志记录对主流程性能的影响。这种设计在之前的 004-05（动作和自动化）中也得到了验证，证明了其有效性。
5. 复用现有组件
复用了 004-01 的 ToolingConnectionFactory 进行连接管理，复用了 SoqlBuilder 工具类构建 SOQL 查询，减少了重复代码，提高了代码的可维护性。
改进点
1. 枚举类型查询接口可以进一步优化
当前的 6 个枚举类型查询接口（访问方法、访问资源类型、API 访问级别、API 类型、激活平台连接器类型、激活平台创建类型）是独立的，可以考虑合并为一个通用的枚举类型查询接口，通过参数指定查询类型，减少接口数量。
2. 缓存机制可以考虑引入
当前的设计选择不缓存，每次实时查询 Salesforce。在实际生产环境中，这些枚举类型的数据变化频率较低，可以考虑引入缓存机制（如 Redis），减少 Salesforce API 调用次数，提高查询性能。
3. 单元测试覆盖可以更全面
虽然提示词中要求了单元测试，但在实际代码生成中，单元测试的覆盖可以更全面，特别是针对异常处理分支的测试。
问题分析
问题 1：Controller 中的错误码使用不够精确
在生成的 ToolingAccessSecurityController 中，所有查询接口都使用了相同的错误码（TOOLING_ACCESS_002）来表示查询失败，没有根据具体的查询类型使用对应的错误码。
根因：提示词中的错误码使用示例不够具体，没有明确说明每个查询接口应该使用哪个错误码。
解决方案：在后续的提示词设计中，增加更具体的错误码使用说明，明确每个查询接口应该使用哪个错误码。
问题 2：DTO 类的字段映射可以更丰富
当前的 DTO 类（如 AccessMethodDTO、AccessResourceTypeDTO 等）只包含了基本的字段（如 name、description），可以根据 Salesforce Tooling API 返回的实际数据，增加更多的字段映射。
根因：需求文档中对 DTO 字段的定义不够详细，只列出了基本字段。
解决方案：在后续的需求文档中，增加更详细的 DTO 字段定义，或者在实际开发中根据 Salesforce API 返回的数据动态调整。
行动计划
| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|---|---|---|---|---|
| 1 | 优化提示词中的错误码使用说明 | AI Assistant | 立即执行 | 高 |
| 2 | 探索引入缓存机制（Redis） | 项目团队 | 下一个迭代 | 中 |
| 3 | 完善单元测试覆盖 | AI Assistant | 立即执行 | 中 |
| 4 | 完善 DTO 字段映射 | AI Assistant | 下一个迭代 | 低 |
提取模式
有效的 Prompt 技巧
-
明确的接口定义：在提示词中明确列出所有 REST API 接口的定义（请求方式、请求路径、功能描述），可以提高生成代码的准确性和完整性。
-
详细的错误码设计：在提示词中详细定义错误码（包括错误码、错误信息、使用场景），可以确保生成的代码有完整的错误处理机制。
-
分层架构的明确要求：在提示词中明确要求分层架构（Controller → Service → Factory → Tooling API），可以确保生成的代码结构清晰、职责明确。
避免的坑
-
不要忽略 DTO 字段的详细定义：在需求文档和提示词中，应该详细定义 DTO 的字段，避免生成的 DTO 字段不完整。
-
不要混淆错误码的使用场景：不同的错误应该使用不同的错误码，避免所有错误都使用同一个错误码，导致问题定位困难。
-
不要忽视性能优化：虽然异步日志记录已经优化了性能，但在高并发场景下，还应该考虑引入缓存机制，减少 Salesforce API 调用次数。
模板迭代
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
-
错误码使用示例：增加更具体的错误码使用示例，明确每个接口应该使用哪个错误码。
-
DTO 字段定义：增加 DTO 字段定义的模板，要求详细列出每个字段的名称、类型、说明。
-
性能优化建议：增加性能优化的建议，如缓存机制、批量查询等。
计划在下一个迭代中更新提示词模板，增加上述内容。