datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-01-30-002-retro.md

# 复盘文档

## 元数据
- 需求编号：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())`

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-001-02-CRUD操作.md)
- [设计文档](../design/2026-01-30-002-CRUD操作-设计.md)
- [决策记录](../decisions/2026-01-30-002-ADR-CRUD操作技术选型.md)
- [提示词](../prompts/2026-01-30-002-prompt-CRUD操作.md)
- [变更日志](../changelog/2026-01-30-002-changelog.md)
- [会话记录](../sessions/2026-01-28-001-session.md)