# 变更记录 - Metadata API客户端封装

## 变更信息

- **变更编号**: Change-015
- **变更日期**: 2026-01-18
- **变更类型**: 新增功能
- **变更版本**: 0.1.17
- **相关需求**: [REQ-010-5](../requirements/REQ-010-5.md) - Metadata API客户端封装
- **相关决策**: [ADR-0014](../decisions/adr/0014-metadata-api-client.md) - Metadata API客户端封装架构决策
- **相关会话**: [Session-20260118-002](../sessions/20260118-metadata-api-client.md) - Metadata API客户端封装执行会话

## 变更摘要

实现了完整的 Salesforce Metadata API 客户端封装，包括 retrieve() 和 deploy() 方法的调用接口，支持异步执行和状态轮询。

## 变更详情

### 新增功能

#### 1. MetadataApiClient 客户端类

**描述**: 创建 MetadataApiClient 客户端类，封装 Salesforce Metadata API 调用。

**实现内容**:
- getMetadataConnection: 获取 Metadata 连接
- retrieve: 检索元数据
- deploy: 部署元数据
- checkRetrieveStatus: 检查检索状态
- checkDeployStatus: 检查部署状态

**技术实现**:
- 使用 Salesforce WSC (Web Service Connector) 库
- 使用 SessionManager 进行会话管理和自动重新登录
- 使用 ConnectorConfig 配置连接参数
- 使用 MetadataConnection 调用 Metadata API

#### 2. MetadataApiService 服务层

**描述**: 创建 MetadataApiService 服务层，提供异步检索和部署接口。

**实现内容**:
- retrieveAsync: 异步检索元数据
- deployAsync: 异步部署元数据
- cancelJob: 取消任务
- getJobStatus: 获取任务状态

**技术实现**:
- 使用 @Service 注解标注服务类
- 使用 @Async 注解实现异步执行
- 使用 CompletableFuture 返回异步结果
- 使用 ConcurrentHashMap 存储异步任务状态

#### 3. AsyncConfig 配置类

**描述**: 创建 AsyncConfig 配置类，配置线程池。

**实现内容**:
- 配置核心线程数: 5
- 配置最大线程数: 10
- 配置队列容量: 100
- 配置线程名称前缀: metadata-task-
- 配置拒绝策略: CallerRunsPolicy

**技术实现**:
- 使用 @Configuration 注解标注配置类
- 使用 @EnableAsync 注解启用异步支持
- 使用 ThreadPoolTaskExecutor 配置线程池

#### 4. 状态轮询机制

**描述**: 创建状态轮询机制，使用定时任务轮询任务状态。

**实现内容**:
- 定时轮询任务状态
- 支持超时处理
- 支持取消轮询
- 更新任务状态

**技术实现**:
- 使用 @Scheduled 注解创建定时任务
- 使用 ConcurrentHashMap 存储轮询任务状态
- 设置轮询频率: 每 5 秒轮询一次
- 设置超时时间: 30 分钟

#### 5. Zip 文件处理工具类

**描述**: 创建 ZipUtil 工具类，处理 Zip 文件。

**实现内容**:
- unzip: 解压 Zip 文件
- readZipFile: 读取 Zip 文件内容

**技术实现**:
- 使用 ZipInputStream 处理 Zip 文件
- 使用 FileOutputStream 写入解压后的文件
- 使用流式处理避免内存溢出
- 支持大文件处理

#### 6. MetadataApiUtil 工具类

**描述**: 创建 MetadataApiUtil 工具类，提供 Metadata API 工具方法。

**实现内容**:
- parsePackageXml: 解析 package.xml
- parseDeployResult: 解析部署结果
- extractErrorMessages: 提取错误信息
- extractCodeCoverage: 提取代码覆盖率

**技术实现**:
- 使用 XML 解析库解析 package.xml
- 使用 JSON 解析库处理 API 响应
- 使用正则表达式提取错误信息
- 使用正则表达式提取代码覆盖率

#### 7. 自定义异常类

**描述**: 创建 MetadataApiException 异常类，提供统一的异常处理机制。

**实现内容**:
- errorCode: 错误代码
- errorMessage: 错误信息
- cause: 原因

**技术实现**:
- 继承自 RuntimeException
- 提供多个构造函数
- 支持错误代码和错误信息

#### 8. 结果类

**描述**: 创建结果类，封装任务执行结果。

**实现内容**:
- RetrieveResult: 检索结果类
- DeployResult: 部署结果类
- JobStatus: 任务状态类

**技术实现**:
- 使用 Lombok 的 @Data 注解
- 包含任务ID、状态、错误信息等属性
- 提供友好的状态枚举

#### 9. MetadataApiController 控制器

**描述**: 创建 MetadataApiController 控制器，提供 RESTful API 接口。

**实现内容**:
- POST /metadata/retrieve - 检索元数据
- POST /metadata/deploy - 部署元数据
- GET /metadata/job/{jobId}/status - 获取任务状态
- DELETE /metadata/job/{jobId} - 取消任务

**技术实现**:
- 使用 @RestController 和 @RequestMapping 注解标注控制器
- 使用 @Valid 注解进行参数验证
- 使用 @ControllerAdvice 统一处理异常
- 返回统一的 Result 对象

#### 10. MetadataManager 前端组件

**描述**: 创建 MetadataManager 前端组件，提供元数据管理界面。

**实现内容**:
- 元数据检索界面
- 元数据部署界面
- 任务状态查询界面
- 任务取消界面

**技术实现**:
- 使用 Vue 3 和 Element Plus 进行开发
- 使用 Axios 调用后端 API
- 使用 WebSocket 实时更新任务状态
- 使用 Element Plus 的组件库

### 数据库变更

**无**: 本次变更不涉及数据库表结构的变更。

### API 变更

#### 新增接口

1. **POST /metadata/retrieve** - 检索元数据
   - 请求参数: orgConfigId, packageXml, apiVersion
   - 响应: Result<RetrieveResult>
   - 描述: 检索 Salesforce 元数据

2. **POST /metadata/deploy** - 部署元数据
   - 请求参数: orgConfigId, zipFile, options
   - 响应: Result<DeployResult>
   - 描述: 部署 Salesforce 元数据

3. **GET /metadata/job/{jobId}/status** - 获取任务状态
   - 请求参数: jobId (path)
   - 响应: Result<JobStatus>
   - 描述: 获取任务执行状态

4. **DELETE /metadata/job/{jobId}** - 取消任务
   - 请求参数: jobId (path)
   - 响应: Result<Void>
   - 描述: 取消任务执行

### 代码变更

#### 新增文件

**后端文件**:
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/client/MetadataApiClient.java` - Metadata API 客户端类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/client/MetadataApiException.java` - Metadata API 异常类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/client/RetrieveResult.java` - 检索结果类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/client/DeployResult.java` - 部署结果类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/client/JobStatus.java` - 任务状态类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/config/AsyncConfig.java` - 异步配置类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/service/IMetadataApiService.java` - Metadata API 服务接口
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/service/impl/MetadataApiServiceImpl.java` - Metadata API 服务实现
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/task/MetadataPollingTask.java` - Metadata 轮询任务
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/util/ZipUtil.java` - Zip 文件处理工具类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/util/MetadataApiUtil.java` - Metadata API 工具类
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataApiController.java` - Metadata API 控制器

**前端文件**:
- `datai-salesforce-metadata/src/main/resources/views/MetadataManager.vue` - 元数据管理前端组件

**测试文件**:
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/client/MetadataApiClientTest.java` - Metadata API 客户端测试
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/service/MetadataApiServiceImplTest.java` - Metadata API 服务测试
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/util/ZipUtilTest.java` - Zip 文件处理工具测试
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/util/MetadataApiUtilTest.java` - Metadata API 工具测试
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/controller/MetadataApiControllerTest.java` - Metadata API 控制器测试

## 变更影响

### 对现有功能的影响

- **无影响**: 本次变更新增了独立的功能模块，不影响现有功能

### 对数据库的影响

- **无修改**: 未修改现有表结构

### 对 API 的影响

- **新增接口**: 新增了 4 个 RESTful API 接口
- **无修改**: 未修改现有接口

### 对前端的影响

- **新增页面**: 新增了元数据管理页面
- **无修改**: 未修改现有页面

## 测试结果

### 单元测试

- ✅ MetadataApiClient - 所有测试通过
- ✅ MetadataApiServiceImpl - 所有测试通过
- ✅ ZipUtil - 所有测试通过
- ✅ MetadataApiUtil - 所有测试通过
- ✅ MetadataApiController - 所有测试通过

### 集成测试

- ✅ Metadata API 客户端调用测试 - 所有测试通过
- ✅ 异步执行测试 - 所有测试通过
- ✅ 状态轮询测试 - 所有测试通过
- ✅ Zip 文件处理测试 - 所有测试通过
- ✅ 错误处理测试 - 所有测试通过

### 手动测试

- ✅ 检索元数据 - 测试通过
- ✅ 部署元数据 - 测试通过
- ✅ 查询任务状态 - 测试通过
- ✅ 取消任务 - 测试通过

## 部署说明

### 数据库部署

无需数据库部署。

### 后端部署

1. 编译项目：`mvn clean package`
2. 部署 JAR 包到服务器
3. 启动应用：`java -jar datai-salesforce-metadata.jar`

### 前端部署

1. 构建前端项目：`npm run build`
2. 部署 dist 目录到 Web 服务器

### 配置更新

无需额外配置更新。

## 回滚方案

如果需要回滚本次变更，执行以下步骤：

1. **删除后端代码**:
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/client/ 目录下的所有文件
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/config/AsyncConfig.java
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/service/ 目录下的所有文件
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/task/MetadataPollingTask.java
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/util/ 目录下的所有文件
   - 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataApiController.java

2. **删除前端代码**:
   - 删除 datai-salesforce-metadata/src/main/resources/views/MetadataManager.vue

3. **删除测试代码**:
   - 删除所有相关的测试文件

4. **重新部署**: 重新编译和部署项目

## 相关文档

- [REQ-010-5.md](../requirements/REQ-010-5.md) - Metadata API客户端封装需求
- [ADR-0014.md](../decisions/adr/0014-metadata-api-client.md) - Metadata API客户端封装架构决策
- [Prompt-015.md](../prompts/015-metadata-api-client.md) - Metadata API客户端封装实现提示词
- [Session-20260118-002.md](../sessions/20260118-metadata-api-client.md) - Metadata API客户端封装执行会话
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
- [index.md](../reference-code/com/docs/index.md) - Salesforce SOAP API Java 客户端参考文档

## 审核记录

| 日期 | 审核人 | 审核结果 | 审核意见 |
|------|--------|----------|----------|
| 2026-01-18 | Datai Team | 已通过 | 变更完整，符合需求 |

## 变更历史

| 日期 | 版本 | 变更内容 | 变更人 |
|------|------|---------|--------|
| 2026-01-18 | v1.0.0 | 初始版本 | Datai Team |