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