datai/docs/archive/decisions/adr/0015-metadata-retrieve-core.md

# 架构决策记录 - 元数据拉取核心功能

## 背景

REQ-010-6 需要实现 Salesforce 元数据拉取的核心功能，包括手动触发拉取、异步拉取执行、状态监控、拉取历史记录、拉取进度查询、拉取取消功能等。

当前项目已经完成了数据库表结构设计、基础实体类和 Mapper 创建、Salesforce 组织配置管理、元数据任务定义管理、Metadata API 客户端封装等功能，现在需要实现元数据拉取核心功能，为用户提供完整的元数据拉取服务。

## 决策

### 1. 手动触发拉取功能方案

**决策**: 使用 MetadataApiClient 调用 retrieve() 方法，使用异步线程池执行拉取任务，使用 RESTful API 设计接口。

**理由**:
- MetadataApiClient 已经封装了 Salesforce Metadata API 的 retrieve() 方法，可以直接使用
- 异步线程池可以避免阻塞主线程，提高系统响应速度
- RESTful API 设计符合业界标准，易于使用和扩展
- 支持选择任务 ID 和组织配置，满足业务需求

**实现方案**:
- 使用 MetadataApiClient 的 retrieve() 方法执行拉取操作
- 使用 Spring 的 @Async 注解实现异步执行
- 使用 ThreadPoolTaskExecutor 配置线程池
- 使用 RESTful API 设计接口，包括 POST 方法触发拉取
- 使用 MyBatis Plus 的 QueryWrapper 实现条件查询

### 2. 异步拉取执行方案

**决策**: 使用 Spring 的 @Async 注解实现异步执行，使用 ThreadPoolTaskExecutor 配置线程池，使用 CompletableFuture 支持异步结果。

**理由**:
- Spring 的 @Async 注解可以简化异步编程，提高开发效率
- ThreadPoolTaskExecutor 可以配置线程池，管理异步任务
- CompletableFuture 可以支持异步结果，提高代码可读性
- 支持并发拉取，满足业务需求

**实现方案**:
- 使用 Spring 的 @Async 注解实现异步执行
- 使用 ThreadPoolTaskExecutor 配置线程池
- 使用 CompletableFuture 支持异步结果
- 使用 Future 接口支持取消操作
- 使用 @Retryable 注解实现重试机制

### 3. 状态监控方案

**决策**: 使用状态机管理拉取状态，使用轮询机制检查拉取状态，使用枚举类定义拉取状态。

**理由**:
- 状态机可以清晰定义状态转换逻辑，提高代码可读性
- 轮询机制可以及时获取拉取状态，支持超时处理
- 枚举类可以定义拉取状态，提高代码可维护性
- 支持状态查询，满足业务需求

**实现方案**:
- 使用枚举类定义拉取状态（Pending/Processing/Success/Failed/Partial_Success）
- 使用状态机管理拉取状态转换逻辑
- 使用轮询机制检查拉取状态
- 使用 ScheduledExecutorService 实现定时任务
- 使用 TimeoutException 处理超时情况

### 4. 拉取历史记录方案

**决策**: 使用 MyBatis Plus 的 BaseMapper 实现历史记录查询，使用分页插件实现分页查询，使用条件查询支持多条件查询。

**理由**:
- MyBatis Plus 的 BaseMapper 提供了基础的 CRUD 方法，简化了开发
- 分页插件可以实现分页查询，提高查询性能
- 条件查询可以支持多条件查询，满足业务需求
- 历史记录完整，方便用户查询

**实现方案**:
- 使用 MyBatis Plus 的 BaseMapper 提供基础的 CRUD 方法
- 使用 MyBatis Plus 的分页插件实现分页查询
- 使用 MyBatis Plus 的 QueryWrapper 实现条件查询
- 使用 @Valid 注解进行参数验证
- 使用 RESTful API 设计接口，包括 GET 方法查询历史记录

### 5. 拉取进度查询方案

**决策**: 使用轮询机制获取进度，使用缓存提高查询性能，使用百分比显示进度。

**理由**:
- 轮询机制可以及时获取进度，支持实时进度查询
- 缓存可以提高查询性能，减少数据库查询
- 百分比显示进度，提高用户体验
- 进度信息准确，满足业务需求

**实现方案**:
- 使用轮询机制获取进度
- 使用 Redis 缓存提高查询性能
- 使用百分比显示进度
- 使用 RESTful API 设计接口，包括 GET 方法查询进度
- 使用 @Cacheable 注解实现缓存

### 6. 拉取取消功能方案

**决策**: 使用 Future.cancel() 取消异步任务，使用状态机管理取消状态，使用异常处理机制处理取消异常。

**理由**:
- Future.cancel() 可以取消异步任务，释放资源
- 状态机可以管理取消状态，提高代码可读性
- 异常处理机制可以处理取消异常，提高系统稳定性
- 取消后资源正确释放，满足业务需求

**实现方案**:
- 使用 Future.cancel() 取消异步任务
- 使用状态机管理取消状态
- 使用自定义异常类处理取消异常
- 使用 @Transactional 注解保证事务一致性
- 使用 Slf4j 记录取消日志

## 备选方案

### 1. 手动触发拉取功能备选方案

**备选方案 1**: 使用消息队列实现手动触发拉取

**优点**:
- 消息队列可以解耦任务提交和任务执行
- 支持任务持久化和重试

**缺点**:
- 消息队列增加了系统复杂度
- 需要引入额外的依赖

**备选方案 2**: 使用定时任务实现手动触发拉取

**优点**:
- 定时任务可以实现定时拉取
- 实现简单

**缺点**:
- 定时任务不支持手动触发
- 不支持实时拉取

### 2. 异步拉取执行备选方案

**备选方案 1**: 使用消息队列实现异步拉取执行

**优点**:
- 消息队列可以解耦任务提交和任务执行
- 支持任务持久化和重试

**缺点**:
- 消息队列增加了系统复杂度
- 需要引入额外的依赖

**备选方案 2**: 使用线程池实现异步拉取执行

**优点**:
- 线程池可以管理异步任务
- 实现简单

**缺点**:
- 线程池不支持异步结果
- 不支持取消操作

### 3. 状态监控备选方案

**备选方案 1**: 使用回调机制实现状态监控

**优点**:
- 回调机制可以及时获取状态
- 不需要定时任务，实现简单

**缺点**:
- Salesforce Metadata API 不支持回调机制
- 需要使用 Webhook，增加系统复杂度

**备选方案 2**: 使用 WebSocket 实现状态监控

**优点**:
- WebSocket 可以实时推送状态
- 用户体验好

**缺点**:
- WebSocket 增加了系统复杂度
- 需要引入额外的依赖

### 4. 拉取历史记录备选方案

**备选方案 1**: 使用缓存实现拉取历史记录

**优点**:
- 缓存可以提高查询性能
- 减少数据库查询

**缺点**:
- 缓存可能导致数据不一致
- 缓存容量有限

**备选方案 2**: 使用文件存储实现拉取历史记录

**优点**:
- 文件存储可以持久化历史记录
- 实现简单

**缺点**:
- 文件存储查询性能差
- 不支持条件查询

### 5. 拉取进度查询备选方案

**备选方案 1**: 使用数据库查询实现拉取进度查询

**优点**:
- 数据库查询可以实时获取进度
- 实现简单

**缺点**:
- 数据库查询性能差
- 可能影响系统性能

**备选方案 2**: 使用消息推送实现拉取进度查询

**优点**:
- 消息推送可以实时推送进度
- 用户体验好

**缺点**:
- 消息推送增加了系统复杂度
- 需要引入额外的依赖

### 6. 拉取取消功能备选方案

**备选方案 1**: 使用标志位实现拉取取消

**优点**:
- 标志位实现简单
- 不需要额外的依赖

**缺点**:
- 标志位不能真正取消任务
- 资源可能无法释放

**备选方案 2**: 使用中断机制实现拉取取消

**优点**:
- 中断机制可以中断任务
- 实现简单

**缺点**:
- 中断机制可能导致资源泄漏
- 不支持优雅取消

## 影响

### 系统架构影响

- 新增手动触发拉取功能，支持用户手动触发拉取
- 新增异步拉取执行，支持异步执行和并发拉取
- 新增状态监控，支持状态查询和状态转换
- 新增拉取历史记录，支持分页查询和条件查询
- 新增拉取进度查询，支持实时进度查询和缓存
- 新增拉取取消功能，支持取消异步任务和资源释放

### 开发流程影响

- 需要配置异步线程池
- 需要配置 Redis 缓存
- 需要编写单元测试和集成测试
- 需要编写使用文档

### 运维管理影响

- 需要监控异步线程池的使用情况
- 需要监控状态轮询的频率
- 需要监控 Redis 缓存的使用情况
- 需要监控拉取任务的执行情况

## 风险

### 技术风险

- **异步执行风险**: 异步执行机制复杂可能导致状态管理困难
- **状态轮询风险**: 状态轮询频率不当可能导致 API 限流
- **拉取取消风险**: 拉取取消功能复杂可能导致资源泄漏
- **历史记录风险**: 拉取历史记录过多可能影响查询性能
- **进度查询风险**: 进度查询不准确可能导致用户体验差

### 业务风险

- **拉取失败风险**: 拉取失败可能导致元数据丢失
- **状态不一致风险**: 状态不一致可能导致用户困惑
- **进度不准确风险**: 进度不准确可能导致用户体验差
- **取消失败风险**: 取消失败可能导致资源泄漏

### 实施风险

- **开发时间风险**: 开发时间可能超出预期
- **测试时间风险**: 测试时间可能超出预期
- **上线时间风险**: 上线时间可能超出预期

## 回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

1. **禁用异步执行**: 如果异步执行机制有问题，可以禁用异步执行，使用同步方式
2. **调整轮询频率**: 如果状态轮询频率有问题，可以调整轮询频率
3. **简化取消功能**: 如果拉取取消功能有问题，可以简化取消功能，使用标志位
4. **禁用缓存**: 如果缓存有问题，可以禁用缓存，使用数据库查询
5. **优化历史记录查询**: 如果历史记录查询性能有问题，可以优化查询，使用索引

## 验收标准

定义验证该决策有效性的具体标准和测试方法：

1. **手动触发拉取功能验收标准**:
   - 手动触发拉取成功
   - 支持选择任务 ID
   - 支持选择组织配置
   - 触发成功返回 Job ID
   - API 接口符合 RESTful 规范

2. **异步拉取执行验收标准**:
   - 异步拉取执行正常工作
   - 使用线程池管理异步任务
   - 支持并发拉取
   - 拉取任务不阻塞系统响应

3. **状态监控验收标准**:
   - 状态监控正常工作
   - 使用状态机管理拉取状态
   - 支持状态查询
   - 状态更新及时

4. **拉取历史记录验收标准**:
   - 拉取历史记录成功
   - 支持分页查询
   - 支持条件查询
   - 历史记录完整

5. **拉取进度查询验收标准**:
   - 拉取进度查询成功
   - 支持实时进度查询
   - 进度信息准确
   - 支持进度百分比显示

6. **拉取取消功能验收标准**:
   - 拉取取消功能正常工作
   - 支持取消正在进行的拉取任务
   - 取消后资源正确释放
   - 取消状态更新及时

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示
- **相关节点**: [集成核心](node_integration_core) - 提供与Salesforce的各种连接方式
- **相关节点**: [SessionManager](node_session_manager_detail) - 会话管理，提供登录服务

### Status

- [x] Draft
- [ ] Accepted
- [ ] Superceded

## 参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：

- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求文档
- [REQ-010-1.md](../requirements/REQ-010-1.md) - 数据库表结构设计和创建
- [REQ-010-2.md](../requirements/REQ-010-2.md) - 基础实体类和Mapper创建
- [REQ-010-3.md](../requirements/REQ-010-3.md) - Salesforce组织配置管理
- [REQ-010-4.md](../requirements/REQ-010-4.md) - 元数据任务定义管理
- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装
- [Salesforce Metadata API Developer Guide](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/) - Salesforce Metadata API 官方文档
- [Spring Async Documentation](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-annotation-support-async) - Spring 异步支持文档
- [MyBatis Plus Documentation](https://baomidou.com/) - MyBatis Plus 官方文档