119 lines
7.3 KiB
Markdown
119 lines
7.3 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：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 技巧
|
||
|
||
1. **明确的接口定义**：在提示词中明确列出所有 REST API 接口的定义（请求方式、请求路径、功能描述），可以提高生成代码的准确性和完整性。
|
||
|
||
2. **详细的错误码设计**：在提示词中详细定义错误码（包括错误码、错误信息、使用场景），可以确保生成的代码有完整的错误处理机制。
|
||
|
||
3. **分层架构的明确要求**：在提示词中明确要求分层架构（Controller → Service → Factory → Tooling API），可以确保生成的代码结构清晰、职责明确。
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要忽略 DTO 字段的详细定义**：在需求文档和提示词中，应该详细定义 DTO 的字段，避免生成的 DTO 字段不完整。
|
||
|
||
2. **不要混淆错误码的使用场景**：不同的错误应该使用不同的错误码，避免所有错误都使用同一个错误码，导致问题定位困难。
|
||
|
||
3. **不要忽视性能优化**：虽然异步日志记录已经优化了性能，但在高并发场景下，还应该考虑引入缓存机制，减少 Salesforce API 调用次数。
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
1. **错误码使用示例**：增加更具体的错误码使用示例，明确每个接口应该使用哪个错误码。
|
||
|
||
2. **DTO 字段定义**：增加 DTO 字段定义的模板，要求详细列出每个字段的名称、类型、说明。
|
||
|
||
3. **性能优化建议**：增加性能优化的建议，如缓存机制、批量查询等。
|
||
|
||
计划在下一个迭代中更新提示词模板，增加上述内容。
|
||
|
||
## 相关文档
|
||
- [需求文档](../requirements/sub/2026-01-28-004-06-访问和安全.md)
|
||
- [设计文档](../design/2026-02-03-004-06-访问和安全-设计.md)
|
||
- [决策文档](../decisions/2026-02-03-004-06-ADR-访问和安全技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-004-06-访问和安全操作日志.sql)
|
||
- [提示词文档](../prompts/2026-02-06-004-06-prompt-访问和安全.md)
|
||
- [变更日志](../changelog/2026-02-06-004-06-changelog.md)
|
||
- [API 文档](../api-docs/2026-02-06-004-06-api.md)
|