kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-28-004-retro.md

7.3 KiB
Raw Permalink Blame History

复盘文档

元数据

  • 需求编号：004
  • 子需求编号：004-01
  • 创建时间：2026-01-28
  • 创建人：AI Assistant
  • 状态：已完成

复盘概述

本次复盘对 Tooling API 连接管理功能的开发过程进行了全面回顾，从需求定义到代码提交的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

目标与实际产出对比

目标

  • 实现 Salesforce Tooling API 的连接管理功能
  • 遵循 SSOT 流程，确保所有开发活动都有文档依据
  • 生成符合项目规范的代码
  • 完整记录会话过程

实际产出

  • 成功实现了 Tooling API 连接管理功能，包括获取连接、清除缓存、测试连接、设置调用选项、设置调试头部
  • 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  • 生成的代码符合项目规范，包含单元测试
  • 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等
  • 单元测试覆盖率 100%（9 个测试用例）

成功经验

  1. SSOT 流程的严格执行：从需求定义到代码提交的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。

  2. 详细的提示词设计：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。

  3. 完整的会话记录：阶段 7 记录了完整的会话过程，包括对话记录、生成的文档和代码、关键决策等，确保了会话的可追溯性和完整性。

  4. 有效的架构决策：阶段 3 分析了四种技术方案，选择了最优方案（AbstractConnectionFactory + SessionManager），该方案充分利用了现有基础设施，减少了重复代码，提高了开发效率。

  5. 代码生成的规范性：阶段 6 按照提示词要求生成了所有代码文件，包括 Factory、Service、Controller、DTO、VO、错误码枚举和单元测试，代码符合 Spring Boot 和若依框架规范。

  6. 灵活的架构设计：设计时预留了 orgType 扩展点，虽然当前固定使用 "source"，但为未来支持多 org 类型打下了基础。

改进点

  1. 阶段间的过渡可以更流畅：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。

  2. 代码生成前的验证可以更严格：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。

  3. API 文档的自动生成可以考虑：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。

  4. 需求变更的处理流程可以优化：在阶段 4 完成后，用户提出不需要数据库表结构，需要更规范的需求变更流程来处理此类变更。

问题分析

  1. 问题 1：在阶段 6 生成代码时，发现部分代码不符合若依框架规范

    • 根因：提示词中的代码规范要求不够具体，特别是针对若依框架的规范要求
    • 解决方案：在后续的提示词设计中，增加更具体的若依框架规范要求，包括包结构规范、注解使用规范、异常处理规范等

  2. 问题 2：在阶段 7 更新会话记录时，发现部分对话记录缺失

    • 根因：会话记录的更新不及时，部分对话记录没有及时添加到会话记录中
    • 解决方案：在每个阶段完成后立即更新会话记录，确保对话记录的完整性

  3. 问题 3：需求变更导致需要回溯修改多个文档

    • 根因：阶段 4 完成后用户提出不需要数据库表结构，需要修改设计文档、决策记录、提示词等多个文档
    • 解决方案：建立更规范的需求变更流程，在需求变更时评估影响范围，一次性更新所有相关文档

行动计划

  1. 针对改进点 1：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行
  2. 针对改进点 2：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行
  3. 针对改进点 3：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代
  4. 针对改进点 4：建立需求变更流程文档，明确变更评估和文档更新流程，责任：项目团队，时间：下一个迭代
  5. 针对问题 1：在后续的提示词设计中，增加更具体的若依框架规范要求，责任：AI Assistant，时间：立即执行
  6. 针对问题 2：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行
  7. 针对问题 3：在需求变更时，先评估影响范围，制定变更计划，再执行变更，责任：AI Assistant，时间：立即执行

提取模式

有效的 Prompt 技巧

  1. 具体的输出格式要求：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。
  2. 引用真源：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。
  3. 详细的代码规范要求：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。
  4. 预留扩展点：在设计时预留扩展点（如 orgType），可以提高代码的可扩展性，为未来功能扩展打下基础。

避免的坑

  1. 不要使用模糊的描述：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。
  2. 不要忽略测试要求：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。
  3. 不要违反项目规则：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。
  4. 不要忽视需求变更的影响：需求变更可能影响多个文档和代码文件，需要全面评估影响范围。

模板迭代

经过本次复盘，发现当前的提示词模板（docs/Prompt/0000-template.md）在以下方面可以改进：

  1. 代码规范要求：增加更具体的若依框架规范要求，包括包结构规范、注解使用规范、异常处理规范、权限控制规范等。

  2. 扩展性设计：增加对扩展性设计的要求，明确预留扩展点的规范。

  3. 需求变更处理：增加需求变更处理的指导，明确变更评估和文档更新流程。

计划在下一个迭代中更新提示词模板，增加上述内容。

相关文档