datai/docs/archive/retros/2026-01-27-014-2-retro.md

复盘文档

元数据

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

复盘概述

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

目标与实际产出对比

目标

• 实现符号表分析与 DTO 生成功能，包括符号表获取、结构解析、Java 代码生成
• 遵循 SSOT 流程，确保所有开发活动都有文档依据
• 生成符合项目规范的代码，包括异常处理、实体类、DTO 类、Parser 层、Generator 层、Manager 层、Service 层、Controller 层和单元测试

实际产出

• 成功实现了符号表分析与 DTO 生成功能，包括符号表获取、结构解析、Java 代码生成
• 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求文档、设计文档、决策记录、提示词文档、变更日志）
• 生成的代码符合项目规范，包含 22 个代码文件（异常处理类 3 个、实体类 5 个、DTO 类 3 个、Parser 层 2 个、Generator 层 1 个、Manager 层 1 个、Service 层 2 个、Controller 层 1 个、单元测试 4 个）
• 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. SSOT 流程的严格执行：从需求定义到变更记录的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据，提高了代码的可追溯性和可维护性。每个阶段都创建了相应的文档，包括需求文档、设计文档、决策记录、提示词文档、变更日志等。

2. 详细的提示词设计：阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。提示词引用了真源（需求文档、设计文档、决策记录），确保了代码生成的准确性。

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

4. 技术选型的合理性：阶段 3 选择 JavaPoet 作为模板引擎，考虑了类型安全、易于维护、性能优秀、社区活跃等因素，确保了代码生成的质量和可维护性。类型映射策略采用精确映射 + 降级处理，保留了强类型特性，对复杂类型降级，提高了代码的健壮性。

5. 代码规范的严格遵循：阶段 6 生成的代码严格遵循 Spring Boot 最佳实践、若依框架规范、Lombok、SLF4J，确保了代码的质量和可读性。代码使用了依赖注入、分层架构、异常处理、日志记录等最佳实践。

改进点

1. 阶段间的过渡可以更流畅：在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。例如，在进入阶段 5（提示词生成）时，可以更详细地解释提示词的作用和重要性。

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

3. API 文档的自动生成可以考虑：可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。目前 API 文档需要手动编写，可能存在与实际代码不一致的风险。

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

5. 代码生成的效率可以提高：目前代码生成是手动进行的，效率较低。可以考虑使用代码生成工具（如 MyBatis Generator、Lombok 等）自动生成部分代码，提高开发效率。

问题分析

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：探索使用代码生成工具自动生成部分代码，责任：项目团队，时间：下一个迭代
6. 针对问题 1：在后续的提示词设计中，增加更具体的异常处理规范要求，责任：AI Assistant，时间：立即执行
7. 针对问题 2：在每个阶段完成后立即更新会话记录，责任：AI Assistant，时间：立即执行
8. 针对问题 3：在代码生成时，统一使用相对路径，责任：AI Assistant，时间：立即执行

提取模式

有效的 Prompt 技巧

1. 具体的输出格式要求：在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。例如，在提示词中明确指定了异常处理类的路径、实体类的路径、DTO 类的路径等，确保了生成的代码文件的组织结构符合项目规范。

2. 引用真源：在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。例如，在提示词中引用了需求文档、设计文档、决策记录等真源，确保了代码生成的准确性。

3. 详细的代码规范要求：在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。例如，在提示词中明确指定了 Spring Boot 最佳实践、若依框架规范、Lombok、SLF4J 等代码规范要求，确保了生成的代码符合项目规范。

避免的坑

1. 不要使用模糊的描述：在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。本次提示词避免了模糊描述，使用了具体的输出格式要求和代码规范要求，确保了生成的代码符合预期。

2. 不要忽略测试要求：在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。本次提示词包含了详细的测试要求，包括单元测试覆盖率不低于 80%、测试用例包含正常场景、异常场景、边界场景等，确保了生成的代码包含完整的单元测试。

3. 不要违反项目规则：在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。本次代码生成严格遵循了项目规则，包括 Spring Boot 最佳实践、若依框架规范、Lombok、SLF4J 等，确保了生成的代码符合项目要求。

模板迭代

经过本次复盘，发现当前的提示词模板（docs/Prompt/0000-template.md）在异常处理规范方面可以更具体，特别是对于不同类型的异常（如符号表获取失败、类型映射失败、代码生成失败）的处理方式不够明确。计划在下一个迭代中更新提示词模板，增加更具体的异常处理规范要求，包括：

• 异常类型的定义和分类
• 异常消息的格式和内容
• 异常处理的方式和流程
• 异常日志的记录方式

相关文档

• 需求文档
• 设计文档
• 决策记录
• 提示词文档
• 变更日志
• 会话记录