kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/changelog/20260118-metadata-retrieve-core.md

9.1 KiB
Raw Blame History

变更记录 - 元数据拉取核心功能

变更信息

  • 变更编号: Change-016
  • 变更日期: 2026-01-18
  • 变更类型: 新增功能
  • 变更版本: 0.1.18
  • 相关需求: REQ-010-6 - 元数据拉取核心功能
  • 相关决策: ADR-0015 - 元数据拉取核心功能架构决策
  • 相关会话: Session-20260118-003 - 元数据拉取核心功能执行会话

变更摘要

实现了完整的 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
    • 描述: 触发 Salesforce 元数据拉取

  2. GET /metadata/retrieve/progress/{jobId} - 查询拉取进度

    • 请求参数: jobId (path)
    • 响应: Result
    • 描述: 查询拉取任务进度

  3. DELETE /metadata/retrieve/{jobId} - 取消拉取

    • 请求参数: jobId (path)
    • 响应: Result
    • 描述: 取消拉取任务

  4. GET /metadata/retrieve/history - 查询拉取历史

    • 请求参数: pageNum, pageSize, taskId, orgConfigId, status
    • 响应: Result<IPage>
    • 描述: 查询拉取历史记录（支持分页和条件查询）

代码变更

新增文件

后端文件:

  • 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. 重新部署: 重新编译和部署项目

相关文档

审核记录

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

变更历史

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