datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-05-004-02-retro.md

# 复盘文档

## 元数据
- 需求编号：004-02
- 复盘时间：2026-02-05
- 创建人：AI Assistant
- 状态：已完成

## 复盘概述
本次复盘对 Tooling API 元数据操作功能（需求 004-02）的开发过程进行全面回顾，从需求定义到变更日志的每个阶段都进行了分析，总结了成功经验、改进点、问题分析和行动计划，旨在提高后续开发过程的效率和质量。

## 目标与实际产出对比

### 目标
- 实现 Tooling API 元数据操作功能，支持创建、查询、更新、删除 Salesforce 元数据
- 支持 5 种元数据类型的创建操作：CustomObject、CustomField、ApexClass、ApexTrigger、Flow
- 实现异步操作日志记录，避免影响主流程性能
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码

### 实际产出
- 成功实现了 Tooling API 元数据操作功能，包括创建、查询、更新、删除操作
- 支持 5 种元数据类型的创建操作：CustomObject、CustomField、ApexClass、ApexTrigger、Flow
- 实现了异步操作日志记录机制，使用 Spring @Async 异步记录操作日志
- 严格按照 SSOT 流程执行，每个阶段都有相应的文档（需求、设计、决策、SQL、提示词、变更日志）
- 生成了 18 个代码文件（8 个基础代码 + 10 个业务代码），符合项目规范
- 提供了 9 个 REST API 接口
- 定义了 11 个标准错误码，覆盖所有可能的错误场景

## 成功经验

### 1. SSOT 流程的严格执行
从需求定义到变更日志的每个阶段都严格按照项目规则执行，确保了所有开发活动都有文档依据。这种严格执行带来了以下好处：
- **可追溯性**：每个决策、每段代码都有文档依据，便于后续维护和问题排查
- **一致性**：所有文档采用统一的格式和结构，便于阅读和理解
- **完整性**：每个阶段都有明确的输出和验收标准，确保不遗漏关键内容

### 2. 详细的提示词设计
阶段 5 生成的提示词包含了详细的输出格式要求、代码规范要求和测试要求，确保了生成的代码符合项目规范和需求。具体做法包括：
- 明确指定需要生成的文件清单（18 个文件）
- 明确指定每个文件的包路径和类名
- 明确指定代码规范（继承关系、注解使用、异常处理等）
- 明确指定测试要求（单元测试覆盖率不低于 80%）

### 3. 异步日志记录机制
采用 Spring @Async 实现异步日志记录，避免了同步记录对主流程性能的影响。这种设计带来了以下好处：
- **性能优化**：主流程无需等待日志记录完成，提高了响应速度
- **可靠性**：即使日志记录失败，也不会影响主流程的执行
- **可配置性**：可以通过配置线程池参数来调整异步处理的性能

### 4. SoqlBuilder 的复用
复用现有的 SoqlBuilder 工具类构建 SOQL 查询语句，提高了代码复用性和可维护性。这种做法体现了：
- **DRY 原则**：避免重复造轮子，复用现有工具类
- **一致性**：使用统一的查询构建方式，便于维护和理解
- **可扩展性**：SoqlBuilder 支持动态构建复杂查询，满足各种查询需求

## 改进点

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

**具体建议**：
- 在进入每个阶段前，简要说明该阶段的目标和主要任务
- 提供该阶段的预期输出和时间估算
- 在阶段完成后，总结该阶段的成果和关键决策

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

**具体建议**：
- 在生成代码前，检查设计文档是否完整、准确
- 验证决策记录中的关键技术决策是否在代码中得到正确实现
- 检查提示词是否涵盖了所有必要的代码规范和要求

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

**具体建议**：
- 在代码中添加 Swagger 注解，自动生成 API 文档
- 使用 Swagger UI 提供在线 API 文档浏览和测试功能
- 定期更新 Swagger 注解，确保文档与代码同步

### 4. 单元测试的生成可以更早
单元测试的生成可以在代码生成阶段就进行，而不是作为后续任务。

**具体建议**：
- 在提示词中明确要求生成单元测试
- 在代码生成阶段就生成完整的单元测试代码
- 确保单元测试覆盖正常和异常场景

## 问题分析

### 问题 1：代码生成器生成的基础代码需要手动调整
**现象**：代码生成器生成的 Entity、Mapper、Service 等基础代码虽然功能完整，但在命名规范和包结构上需要手动调整以符合项目规范。

**根因**：
- 代码生成器的模板与项目规范存在差异
- 表名前缀 `datai_` 导致生成的类名包含 `Datai` 前缀，与项目命名规范不完全一致

**解决方案**：
- 在代码生成后，手动调整类名和包结构
- 考虑优化代码生成器模板，使其更符合项目规范
- 在提示词中明确指定命名规范，减少手动调整的工作量

### 问题 2：会话记录中的对话记录不够详细
**现象**：在阶段 7 更新会话记录时，发现部分对话记录缺失或不够详细。

**根因**：
- 会话记录的更新不及时，部分对话内容被遗忘
- 对话记录的格式不够规范，导致信息丢失

**解决方案**：
- 在每个阶段完成后立即更新会话记录，确保对话记录的完整性
- 采用统一的对话记录格式（时间、用户/AI、内容）
- 使用工具辅助记录对话，减少人工遗漏

### 问题 3：错误码体系的设计需要更多考虑
**现象**：在定义错误码时，部分错误场景的错误码不够明确，存在重叠或遗漏。

**根因**：
- 错误码的设计缺乏系统性规划
- 对 Salesforce 异常场景的分析不够全面

**解决方案**：
- 在设计阶段就进行全面的错误场景分析
- 建立错误码分类体系（如认证错误、操作错误、系统错误等）
- 定期审查和优化错误码体系

## 行动计划

| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|------|--------|--------|----------|--------|
| 1 | 在阶段转换时增加对下一阶段的目的和流程的解释 | AI Assistant | 立即执行 | 高 |
| 2 | 在生成代码前增加对设计文档和决策记录的再次验证 | AI Assistant | 立即执行 | 高 |
| 3 | 探索使用 Swagger 等工具自动生成 API 文档 | 项目团队 | 下一个迭代 | 中 |
| 4 | 在提示词中明确要求生成单元测试 | AI Assistant | 立即执行 | 高 |
| 5 | 优化代码生成器模板，使其更符合项目规范 | 项目团队 | 下一个迭代 | 中 |
| 6 | 在每个阶段完成后立即更新会话记录 | AI Assistant | 立即执行 | 高 |
| 7 | 建立错误码分类体系，定期审查和优化 | 项目团队 | 下一个迭代 | 中 |

## 提取模式

### 有效的 Prompt 技巧

#### 1. 具体的输出格式要求
在提示词中明确指定需要生成的文件、路径、格式等，可以提高生成代码的准确性和规范性。

**示例**：
```
必须生成以下文件：
1. Controller：ToolingMetadataController.java，路径：com.datai.salesforce.tooling.controller
2. Service 接口：IToolingMetadataService.java，路径：com.datai.salesforce.tooling.service
3. Service 实现：ToolingMetadataServiceImpl.java，路径：com.datai.salesforce.tooling.service.impl
```

#### 2. 引用真源
在提示词开头引用需求文档和设计文档的链接，可以确保生成的代码符合需求和设计要求。

**示例**：
```
基于以下文档生成代码：
- 需求文档：[004-02-元数据操作需求文档](../requirements/sub/2026-01-28-004-02-元数据操作.md)
- 设计文档：[004-02-元数据操作设计文档](../design/2026-02-03-004-02-元数据操作-设计.md)
```

#### 3. 详细的代码规范要求
在提示词中明确指定代码规范、命名规范、注释规范等，可以提高生成代码的质量和可读性。

**示例**：
```
代码规范要求：
1. 类名使用大驼峰命名法（PascalCase）
2. 方法名使用小驼峰命名法（camelCase）
3. 常量使用全大写，单词间用下划线分隔
4. 使用 Slf4j 日志框架，使用 log.info()、log.error() 等方法记录日志
5. 使用 Swagger 注解（@Api、@ApiOperation、@ApiParam 等）标注 API 接口
```

### 避免的坑

#### 1. 不要使用模糊的描述
在提示词中使用模糊的描述（如"请生成高质量的代码"），会导致生成的代码不符合预期。

**错误示例**：
```
请生成高质量的代码，确保代码符合项目规范。
```

**正确示例**：
```
代码必须遵循以下规范：
1. 使用若依框架的 R 类统一返回结果
2. 使用 @PreAuthorize("@ss.hasLogin()") 进行权限控制
3. 使用自定义异常 SalesforceAuthException 处理认证异常
4. 单元测试覆盖率不低于 80%
```

#### 2. 不要忽略测试要求
在提示词中忽略测试要求，会导致生成的代码缺少单元测试，降低代码的质量和可靠性。

**错误示例**：
```
生成 Service 层代码。
```

**正确示例**：
```
生成 Service 层代码，并生成对应的单元测试类。
单元测试要求：
1. 使用 JUnit 5 和 Mockito 进行测试
2. 覆盖正常场景和异常场景
3. 测试覆盖率不低于 80%
4. 使用 @Mock 和 @InjectMocks 进行依赖注入模拟
```

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

**错误示例**：
```
生成 Controller 代码，使用自定义的返回结果类。
```

**正确示例**：
```
生成 Controller 代码，使用若依框架的 R 类统一返回结果：
- 成功时返回 R.ok(data)
- 失败时返回 R.fail(errorCode, errorMessage)
- 分页查询时返回 R.ok(pageResult)
```

## 模板迭代

经过本次复盘，发现当前的提示词模板在以下方面可以优化：

### 1. 增加代码生成后的验证要求
在提示词中增加代码生成后的验证要求，确保生成的代码符合项目规范。

**建议添加**：
```
代码生成后，必须进行以下验证：
1. 检查类名和包路径是否符合规范
2. 检查是否使用了正确的继承关系和注解
3. 检查是否处理了所有必要的异常场景
4. 检查是否生成了对应的单元测试
```

### 2. 增加错误码设计的指导
在提示词中增加错误码设计的指导，确保错误码体系的完整性和一致性。

**建议添加**：
```
错误码设计规范：
1. 错误码格式：TOOLING_META_XXX（XXX 为 3 位数字）
2. 错误码分类：
   - 001-099：认证和会话相关错误
   - 100-199：创建操作相关错误
   - 200-299：查询操作相关错误
   - 300-399：更新操作相关错误
   - 400-499：删除操作相关错误
   - 500-599：系统错误
3. 每个错误码必须有明确的错误消息和说明
```

### 3. 增加异步处理的规范要求
在提示词中增加异步处理的规范要求，确保异步操作的正确性和可靠性。

**建议添加**：
```
异步处理规范：
1. 使用 Spring @Async 注解标记异步方法
2. 异步方法必须返回 void 或 Future 类型
3. 异步方法必须捕获所有异常，避免异常丢失
4. 异步操作失败时，必须记录错误日志
5. 考虑使用 @Async 的线程池配置，避免资源耗尽
```

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-004-02-元数据操作.md)
- [设计文档](../design/2026-02-03-004-02-元数据操作-设计.md)
- [决策文档](../decisions/2026-02-03-004-02-ADR-元数据操作技术选型.md)
- [SQL 脚本](../sql/2026-02-03-004-02-元数据操作日志.sql)
- [提示词文档](../prompts/2026-02-05-004-02-prompt-元数据操作.md)
- [变更日志](../changelog/2026-02-05-004-02-changelog.md)
- [会话记录](../sessions/2026-02-03-004-02-session.md)
- [API 文档](../api-docs/2026-02-05-004-02-api.md)