267 lines
9.1 KiB
Markdown
267 lines
9.1 KiB
Markdown
# 变更记录 - 元数据拉取核心功能
|
|
|
|
## 变更信息
|
|
|
|
- **变更编号**: Change-016
|
|
- **变更日期**: 2026-01-18
|
|
- **变更类型**: 新增功能
|
|
- **变更版本**: 0.1.18
|
|
- **相关需求**: [REQ-010-6](../requirements/REQ-010-6.md) - 元数据拉取核心功能
|
|
- **相关决策**: [ADR-0015](../decisions/adr/0015-metadata-retrieve-core.md) - 元数据拉取核心功能架构决策
|
|
- **相关会话**: [Session-20260118-003](../sessions/20260118-metadata-retrieve-core.md) - 元数据拉取核心功能执行会话
|
|
|
|
## 变更摘要
|
|
|
|
实现了完整的 Salesforce 元数据拉取核心功能，包括手动触发拉取、异步拉取执行、状态监控、拉取历史记录、拉取进度查询、拉取取消功能。
|
|
|
|
## 变更详情
|
|
|
|
### 新增功能
|
|
|
|
#### 1. RetrieveStatus 枚举
|
|
|
|
**描述**: 创建 RetrieveStatus 枚举，定义拉取状态。
|
|
|
|
**实现内容**:
|
|
- Pending: 待处理
|
|
- Processing: 处理中
|
|
- Success: 成功
|
|
- Failed: 失败
|
|
- Partial_Success: 部分成功
|
|
- Cancelled: 已取消
|
|
|
|
**技术实现**:
|
|
- 使用 Java 枚举类型
|
|
- 使用 `@EnumValue` 注解映射数据库值
|
|
- 使用 `@JsonValue` 注解序列化为 JSON
|
|
|
|
#### 2. MetadataRetrieveController 控制器
|
|
|
|
**描述**: 创建 MetadataRetrieveController 控制器，提供 RESTful API 接口。
|
|
|
|
**实现内容**:
|
|
- POST /metadata/retrieve/trigger - 触发拉取
|
|
- GET /metadata/retrieve/progress/{jobId} - 查询拉取进度
|
|
- DELETE /metadata/retrieve/{jobId} - 取消拉取
|
|
- GET /metadata/retrieve/history - 查询拉取历史
|
|
|
|
**技术实现**:
|
|
- 使用 `@RestController` 和 `@RequestMapping` 注解标注控制器
|
|
- 使用 `@Valid` 注解进行参数验证
|
|
- 使用 Swagger 注解生成 API 文档
|
|
- 返回统一的 AjaxResult 对象
|
|
|
|
#### 3. IMetadataRetrieveService 服务接口
|
|
|
|
**描述**: 创建 IMetadataRetrieveService 服务接口，定义元数据拉取服务接口。
|
|
|
|
**实现内容**:
|
|
- triggerRetrieve: 触发拉取
|
|
- getRetrieveProgress: 查询拉取进度
|
|
- cancelRetrieve: 取消拉取
|
|
- getRetrieveHistory: 查询拉取历史
|
|
|
|
**技术实现**:
|
|
- 使用 Java 接口定义服务方法
|
|
- 使用 MyBatis Plus 的 IPage 对象实现分页
|
|
|
|
#### 4. MetadataRetrieveServiceImpl 服务实现
|
|
|
|
**描述**: 创建 MetadataRetrieveServiceImpl 服务实现，实现元数据拉取服务。
|
|
|
|
**实现内容**:
|
|
- triggerRetrieve: 触发拉取，创建作业执行记录，异步执行拉取
|
|
- getRetrieveProgress: 查询拉取进度，从缓存中获取进度信息
|
|
- cancelRetrieve: 取消拉取，调用 MetadataApiService 的 cancelJob() 方法
|
|
- getRetrieveHistory: 查询拉取历史，使用 MyBatis Plus 的分页查询
|
|
|
|
**技术实现**:
|
|
- 使用 `@Service` 注解标注服务类
|
|
- 使用 `@Async` 注解实现异步执行
|
|
- 使用 `@Transactional` 注解进行事务管理
|
|
- 使用 ConcurrentHashMap 缓存进度信息
|
|
- 使用 MyBatis Plus 的 QueryWrapper 构建查询条件
|
|
|
|
#### 5. DTO 类
|
|
|
|
**描述**: 创建 DTO 类，封装请求和响应数据。
|
|
|
|
**实现内容**:
|
|
- RetrieveTriggerRequest: 拉取触发请求
|
|
- RetrieveTriggerResponse: 拉取触发响应
|
|
- RetrieveProgressResponse: 拉取进度响应
|
|
- RetrieveHistoryResponse: 拉取历史响应
|
|
|
|
**技术实现**:
|
|
- 使用 `@Valid` 注解进行参数验证
|
|
- 使用 Swagger 注解生成 API 文档
|
|
- 使用 Lombok 的 `@Data` 注解简化代码
|
|
|
|
#### 6. 前端组件
|
|
|
|
**描述**: 创建 MetadataRetrieve.vue 前端组件，提供元数据拉取界面。
|
|
|
|
**实现内容**:
|
|
- 拉取触发界面
|
|
- 拉取进度查询界面
|
|
- 拉取取消界面
|
|
- 拉取历史记录界面
|
|
|
|
**技术实现**:
|
|
- 使用 Vue 3 和 Element Plus 进行开发
|
|
- 使用 Axios 调用后端 API
|
|
- 使用定时器轮询拉取进度
|
|
- 使用 Element Plus 的组件库
|
|
|
|
### 数据库变更
|
|
|
|
**无**: 本次变更不涉及数据库表结构的变更，使用现有的 datai_meta_job_execution 表。
|
|
|
|
### API 变更
|
|
|
|
#### 新增接口
|
|
|
|
1. **POST /metadata/retrieve/trigger** - 触发拉取
|
|
- 请求参数: taskId, orgConfigId, createdBy
|
|
- 响应: Result<RetrieveTriggerResponse>
|
|
- 描述: 触发 Salesforce 元数据拉取
|
|
|
|
2. **GET /metadata/retrieve/progress/{jobId}** - 查询拉取进度
|
|
- 请求参数: jobId (path)
|
|
- 响应: Result<RetrieveProgressResponse>
|
|
- 描述: 查询拉取任务进度
|
|
|
|
3. **DELETE /metadata/retrieve/{jobId}** - 取消拉取
|
|
- 请求参数: jobId (path)
|
|
- 响应: Result<Void>
|
|
- 描述: 取消拉取任务
|
|
|
|
4. **GET /metadata/retrieve/history** - 查询拉取历史
|
|
- 请求参数: pageNum, pageSize, taskId, orgConfigId, status
|
|
- 响应: Result<IPage<RetrieveHistoryResponse>>
|
|
- 描述: 查询拉取历史记录（支持分页和条件查询）
|
|
|
|
### 代码变更
|
|
|
|
#### 新增文件
|
|
|
|
**后端文件**:
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/enums/RetrieveStatus.java` - 拉取状态枚举
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataRetrieveController.java` - 元数据拉取控制器
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/service/IMetadataRetrieveService.java` - 元数据拉取服务接口
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/service/impl/MetadataRetrieveServiceImpl.java` - 元数据拉取服务实现
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/dto/RetrieveTriggerRequest.java` - 拉取触发请求
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/dto/RetrieveTriggerResponse.java` - 拉取触发响应
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/dto/RetrieveProgressResponse.java` - 拉取进度响应
|
|
- `datai-salesforce-metadata/src/main/java/com/datai/metadata/dto/RetrieveHistoryResponse.java` - 拉取历史响应
|
|
|
|
**前端文件**:
|
|
- `datai-salesforce-metadata/src/main/resources/views/MetadataRetrieve.vue` - 元数据拉取前端组件
|
|
|
|
**测试文件**:
|
|
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/service/MetadataRetrieveServiceImplTest.java` - 元数据拉取服务测试
|
|
- `datai-salesforce-metadata/src/test/java/com/datai/metadata/controller/MetadataRetrieveControllerTest.java` - 元数据拉取控制器测试
|
|
|
|
## 变更影响
|
|
|
|
### 对现有功能的影响
|
|
|
|
- **无影响**: 本次变更新增了独立的功能模块，不影响现有功能
|
|
|
|
### 对数据库的影响
|
|
|
|
- **无修改**: 未修改现有表结构，使用现有的 datai_meta_job_execution 表
|
|
|
|
### 对 API 的影响
|
|
|
|
- **新增接口**: 新增了 4 个 RESTful API 接口
|
|
- **无修改**: 未修改现有接口
|
|
|
|
### 对前端的影响
|
|
|
|
- **新增页面**: 新增了元数据拉取页面
|
|
- **无修改**: 未修改现有页面
|
|
|
|
## 测试结果
|
|
|
|
### 单元测试
|
|
|
|
- ✅ MetadataRetrieveServiceImpl - 所有测试通过
|
|
- ✅ MetadataRetrieveController - 所有测试通过
|
|
|
|
### 集成测试
|
|
|
|
- ✅ 手动触发拉取测试 - 所有测试通过
|
|
- ✅ 异步拉取执行测试 - 所有测试通过
|
|
- ✅ 状态监控测试 - 所有测试通过
|
|
- ✅ 拉取历史记录测试 - 所有测试通过
|
|
- ✅ 拉取进度查询测试 - 所有测试通过
|
|
- ✅ 拉取取消测试 - 所有测试通过
|
|
|
|
### 手动测试
|
|
|
|
- ✅ 触发拉取 - 测试通过
|
|
- ✅ 查询拉取进度 - 测试通过
|
|
- ✅ 取消拉取 - 测试通过
|
|
- ✅ 查询拉取历史 - 测试通过
|
|
|
|
## 部署说明
|
|
|
|
### 数据库部署
|
|
|
|
无需数据库部署，使用现有的 datai_meta_job_execution 表。
|
|
|
|
### 后端部署
|
|
|
|
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/enums/RetrieveStatus.java
|
|
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/MetadataRetrieveController.java
|
|
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/service/ 目录下的所有文件
|
|
- 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/dto/ 目录下的所有文件
|
|
|
|
2. **删除前端代码**:
|
|
- 删除 datai-salesforce-metadata/src/main/resources/views/MetadataRetrieve.vue
|
|
|
|
3. **删除测试代码**:
|
|
- 删除所有相关的测试文件
|
|
|
|
4. **重新部署**: 重新编译和部署项目
|
|
|
|
## 相关文档
|
|
|
|
- [REQ-010-6.md](../requirements/REQ-010-6.md) - 元数据拉取核心功能需求
|
|
- [ADR-0015.md](../decisions/adr/0015-metadata-retrieve-core.md) - 元数据拉取核心功能架构决策
|
|
- [Prompt-016.md](../prompts/016-metadata-retrieve-core.md) - 元数据拉取核心功能实现提示词
|
|
- [Session-20260118-003.md](../sessions/20260118-metadata-retrieve-core.md) - 元数据拉取核心功能执行会话
|
|
- [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 |
|