218 lines
9.1 KiB
Markdown
218 lines
9.1 KiB
Markdown
# 复盘文档
|
||
|
||
## 元数据
|
||
- 需求编号：004-05
|
||
- 创建时间：2026-02-06
|
||
- 创建人：AI Assistant
|
||
- 状态：已完成
|
||
|
||
## 复盘概述
|
||
本次复盘对 Tooling API 动作和自动化功能的开发过程进行了全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。
|
||
|
||
## 目标与实际产出对比
|
||
|
||
### 目标
|
||
- 实现 Tooling API 动作和自动化功能，包括：
|
||
- 动作覆盖（ActionOverride）的创建、更新、删除、查询
|
||
- 可操作列表（ActionableList）的查询
|
||
- 8 种枚举类型（动作覆盖类型、动作子类型、可操作列表类型、可操作列表源类型、动作任务分配类型、动作 HTTP 方法、动作邮件发送者类型）的获取
|
||
- 所有操作支持异步日志记录
|
||
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
|
||
- 生成符合项目规范的代码
|
||
|
||
### 实际产出
|
||
- 成功实现了动作覆盖的创建、更新、删除、查询功能
|
||
- 成功实现了可操作列表查询功能
|
||
- 成功实现了 8 种枚举类型获取功能
|
||
- 实现了异步日志记录功能（使用 Spring @Async）
|
||
- 定义了完整的错误码体系（11 个错误码）
|
||
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档
|
||
- 生成的代码符合项目规范，遵循若依框架规范
|
||
- 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
|
||
|
||
## 成功经验
|
||
|
||
1. **SSOT 流程的严格执行**
|
||
- 从需求定义到变更日志的每个阶段都严格按照项目规则执行
|
||
- 确保了所有开发活动都有文档依据
|
||
- 提高了代码的可追溯性和可维护性
|
||
- 每个阶段完成后都进行了用户确认，确保了需求的准确性
|
||
|
||
2. **详细的提示词设计**
|
||
- 阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求
|
||
- 明确了需要生成的文件、路径、格式等
|
||
- 确保了生成的代码符合项目规范和需求
|
||
- 引用了需求文档和设计文档，确保了代码的一致性
|
||
|
||
3. **完整的会话记录**
|
||
- 阶段 7 记录了完整的会话过程
|
||
- 包括对话记录、生成的文档和代码、关键决策等
|
||
- 确保了会话的可追溯性和完整性
|
||
- 为后续的复盘提供了详实的资料
|
||
|
||
4. **代码生成器的有效利用**
|
||
- 使用代码生成器生成了基础代码（DataiToolingActionAutomationLog）
|
||
- 减少了重复性工作，提高了开发效率
|
||
- 在此基础上手动实现了核心业务逻辑
|
||
|
||
5. **错误码体系的完善设计**
|
||
- 定义了 11 个标准错误码（TOOLING_ACTION_001 ~ TOOLING_ACTION_011）
|
||
- 覆盖了 Session 过期、CRUD 操作失败、查询失败、权限不足等场景
|
||
- 便于前端进行错误处理和用户提示
|
||
|
||
## 改进点
|
||
|
||
1. **阶段间的过渡可以更流畅**
|
||
- 在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程
|
||
- 提高用户的理解和参与度
|
||
- 减少用户的等待时间和不确定性
|
||
|
||
2. **API 文档的自动生成可以考虑**
|
||
- 可以探索使用 Swagger 等工具自动生成 API 文档
|
||
- 提高文档的准确性和维护性
|
||
- 减少手动编写 API 文档的工作量
|
||
|
||
3. **单元测试的覆盖率可以提升**
|
||
- 当前生成的代码缺少完整的单元测试
|
||
- 可以在提示词中增加更具体的单元测试要求
|
||
- 提高代码的质量和可靠性
|
||
|
||
4. **性能优化的考虑可以前置**
|
||
- 在设计阶段可以考虑更多的性能优化方案
|
||
- 如缓存策略、批量操作优化等
|
||
- 减少后期的性能调优工作
|
||
|
||
## 问题分析
|
||
|
||
1. **问题 1**：代码生成器生成的部分代码需要手动调整
|
||
- **现象**：代码生成器生成的 DataiToolingActionAutomationLog 相关代码需要手动调整以符合项目规范
|
||
- **根因**：代码生成器的模板与项目规范存在差异
|
||
- **解决方案**：
|
||
- 在提示词中明确指定代码生成器的输出格式要求
|
||
- 在代码生成后进行人工审核和调整
|
||
- 考虑优化代码生成器的模板
|
||
|
||
2. **问题 2**：部分枚举类型的值需要与 Salesforce 文档保持一致
|
||
- **现象**：在实现枚举类型获取功能时，需要确保返回的值与 Salesforce 官方文档一致
|
||
- **根因**：Salesforce 的枚举类型可能会更新，需要及时同步
|
||
- **解决方案**：
|
||
- 在代码中添加注释，说明枚举值的来源
|
||
- 定期检查和更新枚举值
|
||
- 考虑从 Salesforce API 动态获取枚举值
|
||
|
||
3. **问题 3**：异步日志记录的异常处理需要完善
|
||
- **现象**：异步日志记录方法没有返回值，异常处理不够完善
|
||
- **根因**：@Async 方法的异常处理机制与普通方法不同
|
||
- **解决方案**：
|
||
- 添加 AsyncUncaughtExceptionHandler 处理异步方法的异常
|
||
- 在日志记录方法中添加 try-catch 块
|
||
- 考虑使用 CompletableFuture 处理异步结果
|
||
|
||
## 行动计划
|
||
|
||
1. **针对改进点 1**
|
||
- 行动：在阶段转换时，增加对下一阶段的目的和流程的解释
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
2. **针对改进点 2**
|
||
- 行动：探索使用 Swagger 等工具自动生成 API 文档
|
||
- 责任：项目团队
|
||
- 时间：下一个迭代
|
||
|
||
3. **针对改进点 3**
|
||
- 行动：在后续的提示词设计中，增加更具体的单元测试要求
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
4. **针对改进点 4**
|
||
- 行动：在设计阶段增加性能优化方案的讨论
|
||
- 责任：AI Assistant + 项目团队
|
||
- 时间：下一个迭代
|
||
|
||
5. **针对问题 1**
|
||
- 行动：优化代码生成器的模板，使其更符合项目规范
|
||
- 责任：项目团队
|
||
- 时间：下一个迭代
|
||
|
||
6. **针对问题 2**
|
||
- 行动：在代码中添加枚举值来源的注释，并定期检查更新
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
7. **针对问题 3**
|
||
- 行动：完善异步日志记录的异常处理机制
|
||
- 责任：AI Assistant
|
||
- 时间：立即执行
|
||
|
||
## 提取模式
|
||
|
||
### 有效的 Prompt 技巧
|
||
|
||
1. **具体的输出格式要求**
|
||
- 在提示词中明确指定需要生成的文件、路径、格式等
|
||
- 可以提高生成代码的准确性和规范性
|
||
- 示例："文件路径：`datai-salesforce-tooling/src/main/java/com/datai/tooling/controller/ToolingActionAutomationController.java`"
|
||
|
||
2. **引用真源**
|
||
- 在提示词开头引用需求文档和设计文档的链接
|
||
- 可以确保生成的代码符合需求和设计要求
|
||
- 示例："基于需求文档 [004-05-动作和自动化](../requirements/sub/2026-01-28-004-05-动作和自动化.md) 和设计文档 [004-05-动作和自动化-设计](../design/2026-02-03-004-05-动作和自动化-设计.md)"
|
||
|
||
3. **详细的代码规范要求**
|
||
- 在提示词中明确指定代码规范、命名规范、注释规范等
|
||
- 可以提高生成代码的质量和可读性
|
||
- 示例："使用 Lombok 注解简化代码，使用 @Slf4j 记录日志"
|
||
|
||
### 避免的坑
|
||
|
||
1. **不要使用模糊的描述**
|
||
- 在提示词中使用模糊的描述（如"请生成高质量的代码"）
|
||
- 会导致生成的代码不符合预期
|
||
- 应该使用具体的描述（如"使用 Spring Boot 2.7.x，遵循若依框架规范"）
|
||
|
||
2. **不要忽略异常处理**
|
||
- 在提示词中忽略异常处理要求
|
||
- 会导致生成的代码缺少完善的异常处理机制
|
||
- 应该明确要求捕获和处理各种异常场景
|
||
|
||
3. **不要违反项目规则**
|
||
- 在代码生成过程中违反项目规则（如不遵循若依框架规范）
|
||
- 会导致生成的代码不符合项目要求，需要重新生成
|
||
- 应该严格遵守项目规则，特别是 SSOT 流程
|
||
|
||
## 模板迭代
|
||
|
||
经过本次复盘，发现当前的提示词模板在以下方面可以改进：
|
||
|
||
1. **代码生成器集成**
|
||
- 在提示词模板中增加代码生成器的使用说明
|
||
- 明确哪些代码可以使用代码生成器生成
|
||
- 明确哪些代码需要手动实现
|
||
|
||
2. **异常处理规范**
|
||
- 在提示词模板中增加更详细的异常处理要求
|
||
- 包括同步方法和异步方法的异常处理
|
||
- 包括异常日志记录和错误码返回
|
||
|
||
3. **单元测试要求**
|
||
- 在提示词模板中增加单元测试的具体要求
|
||
- 包括测试覆盖率、测试场景、Mock 使用等
|
||
- 提高代码的质量和可靠性
|
||
|
||
4. **性能优化考虑**
|
||
- 在提示词模板中增加性能优化的考虑
|
||
- 包括缓存策略、批量操作、异步处理等
|
||
- 提高系统的性能和可扩展性
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档](../requirements/sub/2026-01-28-004-05-动作和自动化.md)
|
||
- [设计文档](../design/2026-02-03-004-05-动作和自动化-设计.md)
|
||
- [决策记录](../decisions/2026-02-03-004-05-ADR-动作和自动化技术选型.md)
|
||
- [SQL 脚本](../sql/2026-02-03-004-05-动作和自动化操作日志.sql)
|
||
- [提示词文档](../prompts/2026-02-06-004-05-prompt-动作和自动化.md)
|
||
- [变更日志](../changelog/2026-02-06-004-05-changelog.md)
|
||
- [会话记录](../sessions/2026-02-03-004-05-session.md)
|
||
- [API 文档](../api-docs/2026-02-06-004-05-api.md)
|