kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/retros/2026-01-27-014-4-retro.md

9.5 KiB
Raw Blame History

复盘文档

元数据

  • 需求编号：014-4
  • 创建时间：2026-01-27
  • 创建人：SSOT 架构师
  • 状态：已完成

复盘概述

本次复盘对元数据容器与原子性部署功能的开发过程进行了全面回顾，从需求定义到变更记录的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

目标与实际产出对比

目标

  • 实现元数据容器生命周期管理功能（创建容器、删除容器、查询容器、获取容器详情）
  • 实现容器成员管理功能（添加成员到容器，支持多种元数据类型）
  • 实现异步部署请求功能（创建部署请求，支持 CheckOnly 模式和测试执行）
  • 实现状态轮询与结果解析功能（查询部署状态、轮询部署状态、获取部署详情、解析编译错误、解析测试结果）
  • 遵循 SSOT 流程，确保所有开发活动都有文档依据
  • 生成符合项目规范的代码

实际产出

  • 成功实现了元数据容器生命周期管理功能（创建容器、删除容器、查询容器、获取容器详情）
  • 成功实现了容器成员管理功能（添加成员到容器，支持多种元数据类型）
  • 成功实现了异步部署请求功能（创建部署请求，支持 CheckOnly 模式和测试执行）
  • 成功实现了状态轮询与结果解析功能（查询部署状态、轮询部署状态、获取部署详情、解析编译错误、解析测试结果）
  • 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  • 生成的代码符合项目规范，包含单元测试
  • 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

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

  2. 详细的提示词设计：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词明确指定了需要生成的 31 个代码文件，包括 Domain、DTO、VO、Enum、Exception、Manager、Service、Controller 和单元测试。

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

  4. 分层架构设计的成功应用：采用了 Controller 层、Service 层、Manager 层、Factory 层的分层架构设计，代码结构清晰，职责分明，易于维护和扩展。

  5. 核心算法的有效实现：成功实现了容器名称冲突处理算法、异步部署状态轮询算法、编译错误解析算法和测试结果解析算法，确保了功能的完整性和可靠性。

改进点

  1. 阶段间的过渡可以更流畅：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 6（代码生成）前，可以更详细地解释代码生成的流程和预期结果。

  2. 代码生成前的验证可以更严格：在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。例如，可以检查设计文档中的接口设计是否与需求文档中的功能需求完全一致。

  3. API 文档的自动生成可以考虑：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。当前阶段 9 需要手动创建 API 文档，如果能够自动生成，可以减少重复工作。

  4. 单元测试的覆盖率可以提高：虽然生成的代码包含了单元测试，但覆盖率可能不够全面。可以增加更多的测试用例，包括边界条件和异常场景的测试。

  5. 错误处理的细化：当前的异常处理主要依赖于自定义异常类，可以进一步细化错误码和错误信息，提高错误定位的准确性。

问题分析

  1. 问题 1：在阶段 6 生成代码时，发现部分代码的异常处理不够细化

    • 根因：提示词中的异常处理要求不够具体，没有明确指定错误码和错误信息的格式
    • 解决方案：在后续的提示词设计中，增加更具体的异常处理要求，包括错误码的定义规则、错误信息的格式要求等

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

    • 根因：会话记录的更新不及时，导致部分对话记录被重复添加
    • 解决方案：在每个阶段完成后立即更新会话记录，确保对话记录的唯一性和完整性

  3. 问题 3：在阶段 8 更新索引时，发现部分链接格式不统一

    • 根因：索引更新时没有严格遵循统一的链接格式规范
    • 解决方案：制定统一的索引链接格式规范，并在更新索引时严格遵循该规范

行动计划

  1. 针对改进点 1：在阶段转换时，增加对下一阶段的目的和流程的解释，责任：AI Assistant，时间：立即执行

  2. 针对改进点 2：在生成代码前，增加对设计文档和决策记录的再次验证，责任：AI Assistant，时间：立即执行

  3. 针对改进点 3：探索使用 Swagger 等工具自动生成 API 文档，责任：项目团队，时间：下一个迭代

  4. 针对改进点 4：增加更多的单元测试用例，提高测试覆盖率，责任：AI Assistant，时间：下一个迭代

  5. 针对改进点 5：细化错误处理，定义更详细的错误码和错误信息，责任：AI Assistant，时间：下一个迭代

  6. 针对问题 1：在后续的提示词设计中，增加更具体的异常处理要求，责任：AI Assistant，时间：立即执行

  7. 针对问题 2：在每个阶段完成后立即更新会话记录，确保对话记录的唯一性和完整性，责任：AI Assistant，时间：立即执行

  8. 针对问题 3：制定统一的索引链接格式规范，并在更新索引时严格遵循该规范，责任：AI Assistant，时间：立即执行

提取模式

有效的 Prompt 技巧

  1. 具体的输出格式要求：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如，明确指定需要生成 31 个代码文件，包括 4 个 Domain、7 个 DTO、5 个 VO、3 个 Enum、2 个 Exception、2 个 Manager、4 个 Service、2 个 Controller 和 4 个单元测试。

  2. 引用真源：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如，引用 REQ-014-4.md 和 2026-01-27-014-4-元数据容器与原子性部署-设计.md。

  3. 详细的代码规范要求：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如，明确指定使用 Spring Boot 3.5.7 和若依框架规范，使用 Lombok 的 @Data、@Slf4j 注解减少样板代码，使用 @PreAuthorize 注解进行权限控制等。

避免的坑

  1. 不要使用模糊的描述：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。应该使用具体的描述，如"请生成符合 Spring Boot 3.5.7 和若依框架规范的代码"。

  2. 不要忽略测试要求：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。应该明确指定测试要求，如"单元测试覆盖率不低于 80%、测试用例包含正常场景和异常场景、使用 JUnit 5 和 Mockito"。

  3. 不要违反项目规则：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。应该严格遵守项目规则，包括 SSOT 流程、代码规范、命名规范等。

模板迭代

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

  1. 异常处理要求：当前模板在异常处理要求方面可以更具体，特别是针对错误码的定义规则和错误信息的格式要求。计划在下一个迭代中更新提示词模板，增加更具体的异常处理要求。

  2. 测试要求：当前模板在测试要求方面可以更详细，特别是针对边界条件和异常场景的测试。计划在下一个迭代中更新提示词模板，增加更详细的测试要求。

  3. 代码规范要求：当前模板在代码规范要求方面可以更具体，特别是针对若依框架的规范要求。计划在下一个迭代中更新提示词模板，增加更具体的若依框架规范要求，包括：

    • 若依框架的包结构规范
    • 若依框架的注解使用规范
    • 若依框架的异常处理规范
    • 若依框架的权限控制规范

相关文档