# 架构决策记录 (ADR) - Metadata API客户端封装

## 背景

REQ-010-5 需要封装 Salesforce Metadata API 客户端，提供 retrieve() 和 deploy() 方法的调用接口，支持异步执行和状态轮询。当前系统已经完成了以下工作：

1. **数据库表结构设计和创建** (REQ-010-1): 已完成 9 张表的设计和创建
2. **基础实体类和 Mapper 创建** (REQ-010-2): 已完成基础实体类和 Mapper 的创建
3. **Salesforce 组织配置管理** (REQ-010-3): 已完成组织配置管理的实现
4. **元数据任务定义管理** (REQ-010-4): 已完成任务定义管理的实现

现在需要封装 Salesforce Metadata API 客户端，提供 retrieve() 和 deploy() 方法的调用接口，支持异步执行和状态轮询。

## 决策

### 1. 客户端封装方案

**决策**: 使用 Salesforce WSC (Web Service Connector) 库封装 Metadata API 客户端，创建 MetadataApiClient 类。

**理由**:
- Salesforce WSC 是官方推荐的 Java 客户端库，与 Metadata API 兼容性最好
- WSC 库已经包含了所有 Metadata API 的类型定义，无需额外定义
- WSC 库支持异步操作和状态轮询，符合需求要求
- 项目已经引入了 WSC 库依赖，无需额外引入其他库

**实现方案**:
- 创建 MetadataApiClient 类，封装 MetadataConnection
- 使用 SessionManager 进行会话管理和自动重新登录
- 提供 retrieve() 和 deploy() 方法，支持异步执行
- 提供状态轮询方法，检查任务执行状态
- 提供 Zip 文件下载和解压方法
- 提供部署结果解析方法
- 提供统一的错误处理机制

### 2. 异步执行方案

**决策**: 使用 Spring 的 @Async 注解和线程池实现异步执行。

**理由**:
- Spring 的 @Async 注解简单易用，无需额外配置
- Spring 提供了线程池管理，可以控制并发数和资源使用
- 异步执行不影响系统响应，提高用户体验
- 支持异步任务的状态跟踪和结果获取

**实现方案**:
- 创建 AsyncConfig 配置类，配置线程池
- 使用 @Async 注解标记异步方法
- 使用 CompletableFuture 返回异步结果
- 使用 ConcurrentHashMap 存储异步任务状态
- 提供任务取消和超时处理

### 3. 状态轮询方案

**决策**: 使用定时任务实现状态轮询，使用超时机制防止无限轮询。

**理由**:
- 定时任务简单易用，无需额外引入其他库
- 可以控制轮询频率，避免 API 限流
- 支持超时处理，防止无限轮询
- 支持取消轮询，提高灵活性

**实现方案**:
- 使用 @Scheduled 注解创建定时任务
- 使用 ConcurrentHashMap 存储轮询任务状态
- 设置合理的轮询频率（如每 5 秒轮询一次）
- 设置超时时间（如 30 分钟）
- 提供取消轮询的方法

### 4. Zip 文件处理方案

**决策**: 使用 ZipInputStream 处理 Zip 文件，使用流式处理避免内存溢出。

**理由**:
- Java 的 ZipInputStream 是标准库，无需额外引入其他库
- 流式处理可以避免内存溢出，支持大文件处理
- 可以逐条读取 Zip 文件中的条目，提高处理效率
- 支持解压到指定目录，便于后续处理

**实现方案**:
- 使用 ZipInputStream 读取 Zip 文件
- 使用 FileOutputStream 写入解压后的文件
- 使用流式处理，避免一次性加载整个 Zip 文件
- 提供进度跟踪，支持大文件处理
- 提供错误处理，处理损坏的 Zip 文件

### 5. 错误处理方案

**决策**: 使用统一的异常处理机制，使用重试机制处理网络异常。

**理由**:
- 统一的异常处理机制可以提高代码可维护性
- 重试机制可以处理网络异常等临时性错误
- 详细的错误信息可以帮助问题排查
- 支持多种异常类型，提高系统健壮性

**实现方案**:
- 创建自定义异常类，如 MetadataApiException
- 使用 @ControllerAdvice 统一处理异常
- 使用 @Retryable 注解实现重试机制
- 记录详细的错误日志
- 提供友好的错误信息返回

## 备选方案

### 备选方案1: 使用 Apache HttpClient 封装 Metadata API

**描述**: 使用 Apache HttpClient 直接调用 Metadata API 的 REST 端点。

**优点**:
- 更加灵活，可以自定义请求和响应处理
- 可以更好地控制请求超时和重试策略
- 不依赖 WSC 库，减少依赖

**缺点**:
- 需要手动处理 Metadata API 的类型定义
- 需要手动处理 SOAP 消息的序列化和反序列化
- 开发复杂度高，容易出错
- 与官方文档不一致，维护成本高

**结论**: 不采用，开发复杂度高，维护成本高。

### 备选方案2: 使用第三方库如 Force.com Toolkit

**描述**: 使用第三方库如 Force.com Toolkit for Java。

**优点**:
- 提供了更高级的抽象，简化了 API 调用
- 提供了更多功能，如批量操作、查询等
- 社区活跃，文档完善

**缺点**:
- 需要额外引入第三方库
- 可能与项目现有的技术栈不兼容
- 可能不支持最新的 Metadata API 功能
- 增加了项目的依赖复杂度

**结论**: 不采用，增加了项目的依赖复杂度，与项目现有的技术栈不兼容。

### 备选方案3: 使用消息队列实现异步执行

**描述**: 使用消息队列（如 RabbitMQ、Kafka）实现异步执行。

**优点**:
- 可以更好地控制并发数和资源使用
- 支持任务持久化，避免任务丢失
- 支持任务优先级和调度
- 可以分布式部署，提高可扩展性

**缺点**:
- 需要额外引入消息队列，增加了系统复杂度
- 需要额外的运维成本
- 对于简单的异步任务，过度设计
- 增加了项目的依赖复杂度

**结论**: 不采用，对于简单的异步任务，过度设计，增加了系统复杂度。

## 影响

### 对系统架构的影响

1. **新增模块**: 在 datai-salesforce-metadata 模块下新增 MetadataApiClient 类
2. **依赖关系**: 依赖于 SessionManager 进行会话管理和自动重新登录
3. **异步执行**: 使用 Spring 的 @Async 注解和线程池实现异步执行
4. **状态轮询**: 使用定时任务实现状态轮询

### 对开发流程的影响

1. **开发复杂度**: 需要理解 Salesforce Metadata API 的调用规范
2. **测试复杂度**: 需要模拟 Metadata API 的响应，测试复杂度高
3. **文档需求**: 需要编写详细的 API 文档和使用示例

### 对运维管理的影响

1. **监控需求**: 需要监控异步任务的执行状态和性能
2. **日志需求**: 需要记录详细的日志，便于问题排查
3. **配置需求**: 需要配置线程池参数和轮询参数

## 风险

### 技术风险

1. **WSC 库版本风险**: WSC 库版本兼容性问题，可能不支持最新的 Metadata API 功能
   - **缓解措施**: 选择稳定的 WSC 库版本，定期更新

2. **异步执行风险**: 异步执行机制复杂可能导致状态管理困难
   - **缓解措施**: 使用 ConcurrentHashMap 存储异步任务状态，提供任务取消和超时处理

3. **状态轮询风险**: 状态轮询频率不当可能导致 API 限流
   - **缓解措施**: 设置合理的轮询频率（如每 5 秒轮询一次），使用超时机制防止无限轮询

4. **Zip 文件处理风险**: Zip 文件处理不当可能导致内存溢出
   - **缓解措施**: 使用流式处理，避免一次性加载整个 Zip 文件，支持大文件处理

5. **错误处理风险**: 错误处理不完善可能导致任务失败无法恢复
   - **缓解措施**: 使用统一的异常处理机制，使用重试机制处理网络异常

### 业务风险

1. **API 限流风险**: Metadata API 有调用次数限制，可能导致任务失败
   - **缓解措施**: 实现请求限流机制，避免短时间内大量请求

2. **数据一致性风险**: 异步执行可能导致数据不一致
   - **缓解措施**: 使用事务机制，确保数据一致性

### 实施风险

1. **开发周期风险**: 开发复杂度高，可能延长开发周期
   - **缓解措施**: 分阶段实施，先实现核心功能，再实现辅助功能

2. **测试风险**: 测试复杂度高，可能遗漏边界情况
   - **缓解措施**: 编写详细的测试用例，覆盖各种边界情况

## 回滚策略

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

1. **回滚代码**: 删除 MetadataApiClient 类和相关代码
2. **回滚配置**: 删除 AsyncConfig 配置类和相关配置
3. **回滚数据库**: 删除相关的数据库表（如果有的话）
4. **回滚文档**: 删除相关的文档和记录

回滚后，可以考虑以下替代方案：
- 使用 Apache HttpClient 封装 Metadata API
- 使用第三方库如 Force.com Toolkit
- 使用消息队列实现异步执行

## 验收标准

### 功能验收标准

1. **MetadataApiClient 创建成功**: MetadataApiClient 类创建成功，使用 Salesforce WSC 库
2. **retrieve() 方法实现成功**: retrieve() 方法调用成功，支持异步执行、Job ID 获取、状态轮询、Zip 文件下载
3. **deploy() 方法实现成功**: deploy() 方法调用成功，支持异步执行、Job ID 获取、状态轮询、部署结果解析
4. **状态轮询机制正常工作**: 状态轮询机制正常工作，轮询频率合理，支持超时处理和取消轮询
5. **Zip 文件处理正常工作**: Zip 文件下载成功，解压成功，支持大文件处理，内存使用合理
6. **部署结果解析正常工作**: 部署结果解析成功，错误信息提取正确，代码覆盖率提取正确，支持多种部署状态
7. **错误处理机制正常工作**: 错误处理机制正常工作，支持多种异常类型，错误信息详细，支持错误重试

### 性能验收标准

1. **异步执行不影响系统响应**: 异步执行不影响系统响应，系统响应时间在可接受范围内
2. **轮询频率合理**: 轮询频率合理，不会导致 API 限流
3. **内存使用合理**: Zip 文件处理时内存使用合理，不会导致内存溢出

### 代码质量验收标准

1. **代码符合项目编码规范**: 代码符合项目编码规范，有清晰的注释
2. **代码结构清晰**: 代码结构清晰，易于扩展和维护
3. **代码易于测试**: 代码易于单元测试和集成测试

## 视觉锚点

### Visual Reference

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

### Status

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

## 参考资料

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

1. [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求
2. [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
3. [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档
4. [Salesforce Metadata API 开发者指南](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/api_meta/)
5. [Salesforce WSC (Web Service Connector) 文档](https://github.com/forcedotcom/wsc)
6. [Spring @Async 文档](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-annotation-support-async)
7. [Spring @Scheduled 文档](https://docs.spring.io/spring-framework/docs/current/reference/html/integration.html#scheduling-annotation-support-scheduled)