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 - 项目架构视觉化展示
• 相关节点: 集成核心 - 提供与Salesforce的各种连接方式
• 相关节点: SessionManager - 会话管理，提供登录服务

Status

• Draft
• Accepted
• Superceded

参考资料

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

• REQ-010-6.md - 元数据拉取核心功能需求文档
• REQ-010-1.md - 数据库表结构设计和创建
• REQ-010-2.md - 基础实体类和Mapper创建
• REQ-010-3.md - Salesforce组织配置管理
• REQ-010-4.md - 元数据任务定义管理
• REQ-010-5.md - Metadata API客户端封装
• Salesforce Metadata API Developer Guide - Salesforce Metadata API 官方文档
• Spring Async Documentation - Spring 异步支持文档
• MyBatis Plus Documentation - MyBatis Plus 官方文档