datai/datai-scenes/datai-scene-salesforce/docs/retros/2026-02-06-003-07-retro.md

# 复盘文档 - 检查部署和检索状态

## 元数据
- 需求编号：003-07
- 需求名称：检查部署和检索状态
- 创建时间：2026-02-06
- 创建人：AI Assistant
- 状态：已完成

## 复盘概述
本次复盘对"检查部署和检索状态"功能的开发过程进行了全面回顾。该功能是 Metadata API 模块的重要组成部分，为异步操作提供完整的状态监控能力。通过复盘，我们总结了成功经验、识别了改进点、分析了问题，并制定了行动计划，旨在提高后续开发过程的效率和质量。

## 目标与实际产出对比

### 目标
- 实现 Salesforce Metadata API 部署和检索状态检查功能
- 支持单次状态查询、轮询监控和历史记录查询
- 遵循 SSOT 流程，确保所有开发活动都有文档依据
- 生成符合项目规范的代码，包含单元测试

### 实际产出
- ✅ 成功实现了 5 个核心功能（部署状态检查、检索状态检查、轮询部署状态、轮询检索状态、历史查询）
- ✅ 提供了 5 个 REST API 接口，支持灵活的参数配置
- ✅ 创建了 1 个数据库表（datai_metadata_status_check），包含 6 个索引
- ✅ 生成了 14 个代码文件（8 个代码生成器生成 + 4 个手动实现 + 2 个单元测试）
- ✅ 定义了 9 个标准错误码，覆盖各种异常场景
- ✅ 严格按照 SSOT 流程执行，完成了阶段 1-8 的所有文档
- ✅ 编写了 14 个单元测试用例，覆盖成功、失败和边界场景

## 成功经验

### 1. 代码生成器与手动实现的良好结合
**经验描述**：本次开发充分利用了代码生成器生成基础代码（Entity、Mapper、基础 Service），同时针对业务逻辑编写了手动实现的 Service 和 Controller。这种结合方式既提高了开发效率，又保证了业务逻辑的灵活性。

**具体案例**：
- 代码生成器生成了 `DataiMetadataStatusCheck` 相关的 8 个基础文件
- 手动实现了 `IMetadataStatusService` 接口和 `MetadataStatusServiceImpl`，包含复杂的业务逻辑（调用 Metadata API、事务管理、异步记录）
- 手动实现了 `MetadataStatusController`，提供 5 个 REST API 接口

**推广建议**：对于涉及外部 API 调用的功能，建议采用"代码生成器生成基础代码 + 手动实现业务逻辑"的模式。

### 2. 异步审计日志的设计
**经验描述**：状态检查历史采用异步方式写入数据库，避免了阻塞主流程，提高了系统响应速度。

**具体案例**：
```java
@Async("threadPoolTaskExecutor")
public void recordStatusCheck(String asyncId, String operationType, String status, String errorMessage) {
    // 异步记录状态检查历史
}
```

**推广建议**：对于非关键路径的日志记录操作，建议使用异步方式执行，提高系统性能。

### 3. 关联表状态同步机制
**经验描述**：在检查状态的同时，自动更新关联表（datai_metadata_deploy_log 和 datai_metadata_retrieve）的状态字段，确保数据一致性。

**具体案例**：
```java
private void updateDeployHistory(String asyncId, DeployResult result) {
    // 更新部署日志表的状态
}

private void updateRetrieveHistory(String asyncId, RetrieveResult result) {
    // 更新检索记录表的状态
}
```

**推广建议**：对于有关联关系的数据操作，建议在主操作完成后自动同步关联表的状态，避免数据不一致。

### 4. 完善的错误码体系
**经验描述**：定义了 9 个标准错误码，覆盖会话过期、未授权、无效 ID、操作未找到、检查失败、超时、中断、远程调用失败等各种异常场景。

**具体案例**：
- `STATUS_001` - 会话已过期
- `STATUS_003` - 无效的异步操作 ID
- `STATUS_006` - 轮询超时

**推广建议**：为每个功能模块定义独立的错误码体系，便于问题定位和错误处理。

### 5. 轮询策略的灵活配置
**经验描述**：轮询功能支持自定义轮询间隔和超时时间，默认间隔 2000ms，默认超时 300000ms（5分钟），满足不同场景的需求。

**具体案例**：
```java
public DeployResult pollDeployStatus(String asyncId, long interval, long timeout) {
    long pollInterval = interval > 0 ? interval : DEFAULT_POLL_INTERVAL;
    long pollTimeout = timeout > 0 ? timeout : DEFAULT_POLL_TIMEOUT;
    // 轮询逻辑
}
```

**推广建议**：对于需要等待外部操作完成的功能，建议提供可配置的轮询参数，提高灵活性。

## 改进点

### 1. Mapper 引用的前期调研不足
**问题描述**：在编写 `MetadataStatusServiceImpl` 时，最初使用了不存在的 `DataiMetadataDeployMapper`，实际应该使用 `DataiMetadataDeployLogMapper`。

**影响**：需要返工修改代码，增加了开发时间。

**改进措施**：
- 在编写业务代码前，先确认相关的 Mapper 和实体类是否存在
- 建立数据库表和代码文件的映射关系文档

**责任人**：AI Assistant
**时间节点**：立即执行

### 2. 单元测试的边界场景覆盖可以更全面
**问题描述**：虽然编写了 14 个测试用例，但对于某些边界场景（如网络超时、Salesforce 服务不可用）的测试覆盖不足。

**影响**：可能导致某些异常场景在生产环境中出现问题。

**改进措施**：
- 增加对网络异常、服务不可用等边界场景的测试
- 使用 Mockito 模拟各种异常场景

**责任人**：AI Assistant
**时间节点**：下一个迭代

### 3. API 文档的示例可以更详细
**问题描述**：API 文档中的请求和响应示例相对简单，缺少复杂的嵌套对象示例。

**影响**：前端开发人员可能需要额外沟通才能理解复杂的响应结构。

**改进措施**：
- 在 API 文档中增加更详细的示例，包括复杂的嵌套对象
- 提供完整的请求和响应示例

**责任人**：AI Assistant
**时间节点**：立即执行

## 问题分析

### 问题 1：部署表结构的理解偏差
**问题描述**：最初以为部署操作使用 `DataiMetadataDeploy` 表，实际使用的是 `DataiMetadataDeployLog` 表。

**根因分析**：
- 对现有表结构了解不够深入
- 没有仔细查看已有的部署相关代码

**解决方案**：
- 在开发前详细查看相关的现有代码和表结构
- 建立表结构和业务功能的映射文档

**预防措施**：
- 开发前进行代码走查，了解相关模块的表结构
- 维护一份数据库表结构文档

### 问题 2：单元测试中的 Mock 对象配置复杂
**问题描述**：由于 `MetadataStatusServiceImpl` 依赖多个 Mapper 和 ConnectionFactory，单元测试中的 Mock 配置较为复杂。

**根因分析**：
- Service 层的依赖较多
- 没有使用依赖注入的最佳实践

**解决方案**：
- 考虑使用构造函数注入，便于单元测试
- 使用 @MockBean 简化 Mock 配置

**预防措施**：
- 在设计阶段考虑可测试性
- 遵循依赖注入的最佳实践

## 行动计划

| 序号 | 行动项 | 责任人 | 时间节点 | 优先级 |
|------|--------|--------|----------|--------|
| 1 | 建立数据库表和代码文件的映射关系文档 | AI Assistant | 2026-02-07 | 高 |
| 2 | 增加单元测试的边界场景覆盖 | AI Assistant | 2026-02-10 | 中 |
| 3 | 完善 API 文档的示例 | AI Assistant | 2026-02-07 | 高 |
| 4 | 优化 Service 层的依赖注入方式 | AI Assistant | 2026-02-10 | 中 |
| 5 | 维护数据库表结构文档 | 项目团队 | 持续进行 | 低 |

## 提取模式

### 有效的 Prompt 技巧

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

**应用案例**：在阶段 5 的提示词中，明确指定了：
- 文件路径：`datai-salesforce-metadata/src/main/java/com/datai/metadata/...`
- 命名规范：`DataiMetadataStatusCheck`（大驼峰命名）
- 包结构：`com.datai.metadata.service`

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

**应用案例**：
```markdown
基于以下真源文档：
- [需求文档](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
```

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

**应用案例**：
- 使用 Lombok 的 `@Data` 注解简化实体类
- 使用 Swagger 的 `@Schema` 注解进行 API 文档标注
- 使用 SLF4J 进行日志记录

### 避免的坑

#### 1. 不要假设表结构
**坑描述**：在编写业务代码时，假设某个表存在或具有某些字段，实际可能不存在或字段不同。

**避免方法**：
- 编写代码前，先查看数据库表结构和现有代码
- 使用 `Glob` 工具搜索相关的实体类和 Mapper

#### 2. 不要忽略现有代码的复用
**坑描述**：在编写新功能时，忽略现有代码的复用，导致重复造轮子。

**避免方法**：
- 开发前搜索相关的现有代码
- 查看类似功能的实现方式

#### 3. 不要省略单元测试的异常场景
**坑描述**：只编写正常流程的单元测试，忽略异常场景的测试。

**避免方法**：
- 为每个方法编写至少 3 个测试用例：成功场景、失败场景、边界场景
- 使用 Mockito 模拟各种异常

## 模板迭代

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

### 1. 增加表结构确认环节
在提示词中增加一个环节，要求确认相关的数据库表结构和 Mapper 文件：
```markdown
## 表结构确认
在编写业务代码前，请确认以下表结构和 Mapper 文件：
1. 使用 `Glob` 工具搜索相关的实体类（如 `*Deploy*.java`）
2. 使用 `Read` 工具查看实体类的字段
3. 确认 Mapper 接口的方法名
```

### 2. 增加可测试性要求
在提示词中增加对可测试性的要求：
```markdown
## 可测试性要求
1. 使用构造函数注入或 Setter 注入，便于单元测试
2. 避免在方法中直接创建依赖对象
3. 为每个公共方法编写单元测试
```

### 3. 增加 API 文档示例要求
在提示词中增加对 API 文档示例的要求：
```markdown
## API 文档要求
1. 提供完整的请求示例，包括所有字段
2. 提供完整的响应示例，包括嵌套对象
3. 提供错误响应示例
```

## 相关文档
- [需求文档](../requirements/sub/2026-01-28-003-07-检查部署和检索状态.md)
- [设计文档](../design/2026-02-03-003-07-检查部署和检索状态-设计.md)
- [决策记录](../decisions/2026-02-03-003-07-ADR-检查部署和检索状态技术选型.md)
- [变更日志](../changelog/2026-02-06-003-07-changelog.md)
- [API 文档](../api-docs/2026-02-06-003-07-api.md)
- [会话记录](../sessions/2026-02-03-003-07-session.md)

## 总结
本次"检查部署和检索状态"功能的开发总体顺利，成功实现了所有目标功能，并生成了完整的文档和代码。通过复盘，我们识别了改进点并制定了行动计划，特别是加强了对现有表结构的调研和单元测试的覆盖。这些经验将应用到后续的开发工作中，持续提高开发效率和代码质量。