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-30-002-retro.md

16 KiB
Raw Permalink Blame History

复盘文档

元数据

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

复盘概述

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

目标与实际产出对比

目标

  • 实现 Salesforce Partner API 的 CRUD 操作功能，包括 Create、Retrieve、Update、Delete、Upsert、Merge 六个核心操作
  • 支持单条记录和批量记录操作
  • 提供完整的 RESTful API 接口
  • 遵循 SSOT 流程，确保所有开发活动都有文档依据
  • 生成符合项目规范的代码

实际产出

  • 成功实现了 Salesforce Partner API 的 CRUD 操作功能，包括 Create、Retrieve、Update、Delete、Upsert、Merge 六个核心操作
  • 支持单条记录和批量记录操作（最多 200 条）
  • 提供了 6 个 REST API 接口
  • 严格按照 SSOT 流程执行，每个阶段都有相应的文档
  • 生成的代码符合项目规范，包含单元测试
  • 完整记录了会话过程，包括对话记录、生成的文档和代码、关键决策等

成功经验

1. SSOT 流程的严格执行

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

  • 每个阶段都生成了相应的文档
  • 每个阶段完成后都询问用户确认
  • 所有文档都按照统一的格式和命名规范创建
  • 所有文档都包含完整的元数据

2. 详细的提示词设计

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

  • 明确指定了需要生成的文件、路径、格式
  • 引用了需求文档和设计文档的链接
  • 详细说明了代码规范、命名规范、注释规范
  • 明确了测试要求和测试覆盖率

3. 完整的会话记录

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

  • 记录了所有的对话内容
  • 记录了所有生成的文档和代码
  • 记录了每个阶段的关键决策
  • 记录了每个阶段的状态

4. 有效的架构决策

阶段 3 创建的 ADR 记录了架构决策过程，确保了技术选型的合理性和可追溯性。具体表现为：

  • 分析了至少两种技术方案
  • 对比了方案的优缺点
  • 记录了决策理由
  • 记录了放弃方案的原因

5. 完善的异常处理

在代码生成过程中，使用了 datai-salesforce-common 模块的异常体系，统一处理各种异常情况。具体表现为：

  • 使用了现有的异常类
  • 统一了异常处理逻辑
  • 返回了友好的错误消息
  • 记录了详细的错误日志

改进点

1. 阶段间的过渡可以更流畅

在阶段转换时，可以更主动地向用户解释下一阶段的目的和流程，提高用户的理解和参与度。具体表现为：

  • 在进入下一阶段前，简要说明下一阶段的目的和流程
  • 说明下一阶段会生成哪些文档或代码
  • 说明下一阶段需要用户确认的内容
  • 提高用户对整个流程的理解

2. 代码生成前的验证可以更严格

在生成代码前，可以增加对设计文档和决策记录的再次验证，确保代码生成的准确性。具体表现为：

  • 在生成代码前，再次确认设计文档的内容
  • 在生成代码前，再次确认决策记录的内容
  • 确保代码生成符合设计和决策要求
  • 减少代码生成的错误和返工

3. API 文档的自动生成可以考虑

可以探索使用 Swagger 等工具自动生成 API 文档，提高文档的准确性和维护性。具体表现为：

  • 探索使用 Swagger 注解自动生成 API 文档
  • 探索使用其他 API 文档生成工具
  • 提高 API 文档的准确性和维护性
  • 减少 API 文档的维护成本

4. 单元测试的覆盖率可以提高

虽然生成的代码包含了单元测试，但测试覆盖率可以进一步提高。具体表现为：

  • 增加更多的测试用例
  • 覆盖更多的边界情况
  • 覆盖更多的异常情况
  • 提高测试覆盖率到 90% 以上

5. 代码注释可以更详细

虽然生成的代码包含了基本的注释，但注释可以更详细。具体表现为：

  • 增加方法级别的注释
  • 增加参数级别的注释
  • 增加返回值级别的注释
  • 增加异常级别的注释

问题分析

问题 1：在阶段 6 生成代码时，发现部分代码规范要求不够具体

问题描述：在生成代码时，发现部分代码规范要求不够具体，导致生成的代码在某些方面不够规范。

根本原因：提示词中的代码规范要求不够具体，特别是针对若依框架的规范要求。

影响范围：代码生成的质量和规范性。

解决方案：

  1. 在后续的提示词设计中，增加更具体的若依框架规范要求
  2. 在提示词中明确指定若依框架的包结构规范
  3. 在提示词中明确指定若依框架的注解使用规范
  4. 在提示词中明确指定若依框架的异常处理规范
  5. 在提示词中明确指定若依框架的权限控制规范

预防措施：

  1. 在生成代码前，再次确认设计文档的内容
  2. 在生成代码前，再次确认决策记录的内容
  3. 在提示词中增加更多的代码规范要求
  4. 在提示词中增加更多的示例代码

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

问题描述：在更新会话记录时，发现部分对话记录更新不及时，导致会话记录不够完整。

根本原因：会话记录的更新不及时，没有在每个阶段完成后立即更新。

影响范围：会话记录的完整性和可追溯性。

解决方案：

  1. 在每个阶段完成后立即更新会话记录
  2. 确保会话记录包含所有的对话内容
  3. 确保会话记录包含所有生成的文档和代码
  4. 确保会话记录包含每个阶段的关键决策
  5. 确保会话记录包含每个阶段的状态

预防措施：

  1. 在每个阶段完成后，立即更新会话记录
  2. 在会话记录中添加更多的细节
  3. 在会话记录中添加更多的元数据
  4. 在会话记录中添加更多的链接

问题 3：在阶段 8 创建变更日志时，发现部分变更内容不够详细

问题描述：在创建变更日志时，发现部分变更内容不够详细，导致变更日志不够完整。

根本原因：变更日志的模板不够详细，没有提供足够的指导。

影响范围：变更日志的完整性和可追溯性。

解决方案：

  1. 在变更日志模板中增加更多的指导
  2. 在变更日志中增加更多的细节
  3. 在变更日志中增加更多的元数据
  4. 在变更日志中增加更多的链接
  5. 在变更日志中增加更多的示例

预防措施：

  1. 在创建变更日志前，再次确认会话记录的内容
  2. 在创建变更日志前，再次确认生成的文档和代码
  3. 在变更日志中添加更多的细节
  4. 在变更日志中添加更多的元数据
  5. 在变更日志中添加更多的链接

行动计划

针对改进点 1：阶段间的过渡可以更流畅

  • 行动：在阶段转换时，增加对下一阶段的目的和流程的解释
  • 责任人：AI Assistant
  • 时间：立即执行
  • 验收标准：在进入下一阶段前，简要说明下一阶段的目的和流程

针对改进点 2：代码生成前的验证可以更严格

  • 行动：在生成代码前，增加对设计文档和决策记录的再次验证
  • 责任人：AI Assistant
  • 时间：立即执行
  • 验收标准：在生成代码前，再次确认设计文档和决策记录的内容

针对改进点 3：API 文档的自动生成可以考虑

  • 行动：探索使用 Swagger 等工具自动生成 API 文档
  • 责任人：项目团队
  • 时间：下一个迭代
  • 验收标准：能够使用 Swagger 自动生成 API 文档

针对改进点 4：单元测试的覆盖率可以提高

  • 行动：增加更多的测试用例，提高测试覆盖率到 90% 以上
  • 责任人：AI Assistant
  • 时间：下一个迭代
  • 验收标准：测试覆盖率达到 90% 以上

针对改进点 5：代码注释可以更详细

  • 行动：增加更多的代码注释，包括方法级别、参数级别、返回值级别、异常级别的注释
  • 责任人：AI Assistant
  • 时间：下一个迭代
  • 验收标准：代码注释更加详细和完整

针对问题 1：代码规范要求不够具体

  • 行动：在后续的提示词设计中，增加更具体的若依框架规范要求
  • 责任人：AI Assistant
  • 时间：立即执行
  • 验收标准：提示词中包含更具体的若依框架规范要求

针对问题 2：会话记录更新不及时

  • 行动：在每个阶段完成后立即更新会话记录
  • 责任人：AI Assistant
  • 时间：立即执行
  • 验收标准：每个阶段完成后立即更新会话记录

针对问题 3：变更日志内容不够详细

  • 行动：在变更日志模板中增加更多的指导，在变更日志中增加更多的细节
  • 责任人：AI Assistant
  • 时间：立即执行
  • 验收标准：变更日志更加详细和完整

提取模式

有效的 Prompt 技巧

1. 具体的输出格式要求

在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。具体表现为：

  • 明确指定需要生成的文件列表
  • 明确指定每个文件的路径
  • 明确指定每个文件的格式
  • 明确指定每个文件的内容结构

示例：

必须生成以下文件：
1. Controller：PartnerCrudController.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/controller/PartnerCrudController.java）
2. Service 接口：IPartnerCrudService.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/IPartnerCrudService.java）
3. Service 实现：PartnerCrudServiceImpl.java（路径：datai-salesforce-partner/src/main/java/com/datai/partner/service/impl/PartnerCrudServiceImpl.java）

2. 引用真源

在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。具体表现为：

  • 引用需求文档的链接
  • 引用设计文档的链接
  • 引用决策记录的链接
  • 引用其他相关文档的链接

示例：

引用真源：
- 需求文档：[CRUD操作](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/requirements/sub/2026-01-28-001-02-CRUD操作.md)
- 设计文档：[CRUD操作-设计](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/design/2026-01-30-002-CRUD操作-设计.md)
- 决策记录：[CRUD操作技术选型](file:///d:/idea_demo/datai/datai-scenes/datai-scene-salesforce/docs/decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)

3. 详细的代码规范要求

在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。具体表现为：

  • 明确指定代码规范（如 Google Java Style Guide）
  • 明确指定命名规范（如 PascalCase、camelCase）
  • 明确指定注释规范（如 JavaDoc 格式）
  • 明确指定导入规范（如按字母顺序排序）

示例：

代码规范要求：
- 类命名：使用 PascalCase（如 PartnerCrudController）
- 方法命名：使用 camelCase（如 createRecord）
- 变量命名：使用 camelCase（如 objectType）
- 注释规范：使用 JavaDoc 格式
- 代码格式：遵循 Google Java Style Guide
- 导入规范：按字母顺序排序，移除未使用的导入

避免的坑

1. 不要使用模糊的描述

在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。具体表现为：

  • 不要使用"高质量"、"优秀"、"好"等模糊的描述
  • 不要使用"实现"、"完成"等模糊的动词
  • 不要使用"功能"、"模块"等模糊的名词
  • 要使用具体的、可衡量的、可验证的描述

错误示例：

请生成高质量的代码

正确示例：

请生成符合若依框架规范的代码，包含以下内容：
1. Controller 层：使用 @RestController 注解，提供 REST API 接口
2. Service 层：使用 @Service 注解，实现业务逻辑
3. DTO 层：使用 Lombok 的 @Data 注解，简化代码
4. VO 层：使用 Lombok 的 @Data 注解，简化代码
5. 单元测试：使用 JUnit 5 和 Mockito，测试覆盖率不低于 80%

2. 不要忽略测试要求

在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。具体表现为：

  • 不要忽略单元测试的要求
  • 不要忽略测试覆盖率的要求
  • 不要忽略测试用例的要求
  • 要明确指定测试框架、测试覆盖率、测试用例等

错误示例：

请生成代码

正确示例：

请生成代码和单元测试：
1. 代码：实现 CRUD 操作功能
2. 单元测试：使用 JUnit 5 和 Mockito 框架
3. 测试覆盖率：不低于 80%
4. 测试用例：包含正常场景、批量操作场景、异常场景

3. 不要违反项目规则

在代码生成过程中违反项目规则（如不遵循若依框架规范），会导致生成的代码不符合项目要求，需要重新生成。具体表现为：

  • 不要违反若依框架规范
  • 不要违反 Spring Boot 规范
  • 不要违反 Spring Security 规范
  • 不要违反项目代码规范
  • 要严格遵守项目规则和规范

错误示例：

请生成代码，使用自定义的框架和规范

正确示例：

请生成代码，严格遵循以下规范：
1. 若依框架规范：使用若依框架的包结构、注解、异常处理等
2. Spring Boot 规范：使用 Spring Boot 的注解、配置等
3. Spring Security 规范：使用 Spring Security 的注解、配置等
4. 项目代码规范：遵循 Google Java Style Guide

模板迭代

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

若依框架的包结构规范

  • Controller 层：com.datai.partner.controller
  • Service 层：com.datai.partner.service 和 com.datai.partner.service.impl
  • DTO 层：com.datai.partner.model.dto
  • VO 层：com.datai.partner.model.vo
  • 工具类：com.datai.partner.util

若依框架的注解使用规范

  • Controller 层：@RestController、@RequestMapping、@PostMapping、@GetMapping、@PutMapping、@DeleteMapping
  • Service 层：@Service、@Autowired
  • DTO 层：@Data、@Schema
  • VO 层：@Data、@Schema
  • 权限控制：@PreAuthorize("@ss.hasLogin()")
  • 参数验证：@Validated、@NotNull、@NotBlank、@Size、@Pattern

若依框架的异常处理规范

  • 使用 datai-salesforce-common 模块的异常类
  • 统一异常处理逻辑
  • 返回友好的错误消息
  • 记录详细的错误日志

若依框架的权限控制规范

  • 使用 Spring Security 的 @PreAuthorize 注解
  • 所有接口要求用户登录（@PreAuthorize("@ss.hasLogin()")）
  • 确保只有登录用户才能访问接口

若依框架的响应格式规范

  • 使用 AjaxResult 统一响应格式
  • 成功响应：AjaxResult.success("操作成功", data)
  • 失败响应：AjaxResult.error("操作失败: " + e.getMessage())

相关文档