datai/datai-scenes/datai-scene-salesforce/docs/changelog/20260118-task-definition-management.md

变更记录 - 元数据任务定义管理

变更信息

• 变更编号: Change-014
• 变更日期: 2026-01-18
• 变更类型: 新增功能
• 变更版本: 0.1.16
• 相关需求: REQ-010-4 - 元数据任务定义管理
• 相关决策: ADR-0013 - 元数据任务定义管理架构决策
• 相关会话: Session-20260118-001 - 元数据任务定义管理执行会话

变更摘要

实现了完整的元数据任务定义管理功能，包括任务 CRUD 操作、package.xml 配置、API 版本选择、调度类型选择、Cron 表达式配置和任务验证。

变更详情

新增功能

1. 任务定义 CRUD 功能

描述: 实现了元数据任务的增删改查功能，支持分页和条件查询。

实现内容:

• 创建任务接口: POST /metadata/task
• 更新任务接口: PUT /metadata/task/{id}
• 删除任务接口: DELETE /metadata/task/{id}
• 查询任务列表接口: GET /metadata/task/list
• 查询任务详情接口: GET /metadata/task/{id}

技术实现:

• 使用 MyBatis Plus 的 BaseMapper 实现 CRUD 操作
• 使用 @Valid 注解进行参数验证
• 使用 @Transactional 注解进行事务管理
• 支持按任务名称、任务类型、状态进行条件查询
• 支持分页查询，使用 MyBatis Plus 的 Page 对象

2. package.xml 内容配置

描述: 实现了 package.xml 内容的可视化编辑和验证功能。

实现内容:

• package.xml 内容编辑器（使用 Element Plus 的 Input 组件）
• package.xml 格式验证
• 元数据类型验证
• 通配符验证

技术实现:

• 使用 Java 的 DocumentBuilderFactory 和 DocumentBuilder 解析 XML
• 验证 package.xml 的根元素和 types 元素
• 验证元数据类型是否在支持的类型列表中
• 验证通配符使用是否正确
• 使用 TEXT 类型存储 package.xml 内容，避免 VARCHAR 长度限制

3. API 版本选择

描述: 实现了 API 版本的选择和验证功能。

实现内容:

• API 版本列表展示（58.0、57.0、56.0）
• API 版本选择
• API 版本验证

技术实现:

• 使用枚举类型管理 API 版本
• 使用配置文件管理支持的 API 版本列表
• 在创建和更新任务时验证 API 版本是否在支持的版本列表中

4. 调度类型选择

描述: 实现了调度类型的选择和验证功能。

实现内容:

• 调度类型选择（Manual/Cron）
• 调度类型验证
• 调度类型友好显示

技术实现:

• 使用 Java 枚举类型 ScheduleType 管理调度类型
• 使用 @EnumValue 注解映射数据库值
• 在创建和更新任务时验证调度类型是否正确

5. Cron 表达式配置

描述: 实现了 Cron 表达式的编辑、验证和预览功能。

实现内容:

• Cron 表达式编辑
• Cron 表达式验证
• Cron 表达式预览（显示下次执行时间）

技术实现:

• 使用 Quartz 的 CronExpression 验证 Cron 表达式格式
• 使用 CronExpression 的 getNextValidTimeAfter 方法计算下次执行时间
• 在创建和更新任务时验证 Cron 表达式是否正确
• 在前端显示 Cron 表达式的下次执行时间

6. 任务验证功能

描述: 实现了任务的验证功能，验证 package.xml 和调度配置。

实现内容:

• package.xml 格式验证
• Cron 表达式验证
• 验证失败返回详细错误信息

技术实现:

• 创建 PackageXmlValidator 验证器，验证 package.xml 格式和元数据类型
• 创建 CronExpressionValidator 验证器，验证 Cron 表达式格式和计算下次执行时间
• 在创建和更新任务时自动进行验证
• 提供 POST /metadata/task/{id}/validate 接口手动验证任务

数据库变更

新增表：datai_meta_task

CREATE TABLE `datai_meta_task` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '任务ID',
  `task_name` varchar(255) NOT NULL COMMENT '任务名称',
  `task_type` varchar(50) NOT NULL COMMENT '任务类型（retrieve/deploy）',
  `org_config_id` bigint NOT NULL COMMENT '组织配置ID',
  `package_xml` longtext COMMENT 'package.xml内容',
  `api_version` varchar(20) NOT NULL COMMENT 'API版本',
  `schedule_type` varchar(20) NOT NULL COMMENT '调度类型（Manual/Cron）',
  `cron_expression` varchar(100) COMMENT 'Cron表达式',
  `status` varchar(20) NOT NULL COMMENT '任务状态（Active/Inactive）',
  `description` varchar(500) COMMENT '任务描述',
  `created_by` varchar(100) COMMENT '创建人',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_by` varchar(100) COMMENT '更新人',
  `updated_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_org_config_id` (`org_config_id`),
  KEY `idx_task_type` (`task_type`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='元数据任务定义表';

索引设计:

• idx_org_config_id: 加速按组织配置ID查询任务
• idx_task_type: 加速按任务类型查询任务
• idx_status: 加速按状态查询任务

API 变更

新增接口

1. POST /metadata/task - 创建任务

   • 请求参数: DataiMetaTask
   • 响应: Result
   • 描述: 创建元数据任务

2. PUT /metadata/task/{id} - 更新任务

   • 请求参数: id (path), DataiMetaTask (body)
   • 响应: Result
   • 描述: 更新元数据任务

3. DELETE /metadata/task/{id} - 删除任务

   • 请求参数: id (path)
   • 响应: Result
   • 描述: 删除元数据任务

4. GET /metadata/task/list - 查询任务列表

   • 请求参数: pageNum, pageSize, taskName, taskType, status
   • 响应: Result<IPage>
   • 描述: 查询元数据任务列表（支持分页和条件查询）

5. GET /metadata/task/{id} - 查询任务详情

   • 请求参数: id (path)
   • 响应: Result
   • 描述: 查询元数据任务详情

6. POST /metadata/task/{id}/validate - 验证任务

   • 请求参数: id (path)
   • 响应: Result
   • 描述: 验证元数据任务（package.xml 和 Cron 表达式）

代码变更

新增文件

后端文件:

• datai-salesforce-metadata/src/main/java/com/datai/metadata/entity/DataiMetaTask.java - 任务实体类
• datai-salesforce-metadata/src/main/java/com/datai/metadata/mapper/DataiMetaTaskMapper.java - 任务 Mapper 接口
• datai-salesforce-metadata/src/main/resources/mapper/DataiMetaTaskMapper.xml - 任务 Mapper XML
• datai-salesforce-metadata/src/main/java/com/datai/metadata/service/IDataiMetaTaskService.java - 任务 Service 接口
• datai-salesforce-metadata/src/main/java/com/datai/metadata/service/impl/DataiMetaTaskServiceImpl.java - 任务 Service 实现
• datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/DataiMetaTaskController.java - 任务 Controller
• datai-salesforce-metadata/src/main/java/com/datai/metadata/validator/PackageXmlValidator.java - package.xml 验证器
• datai-salesforce-metadata/src/main/java/com/datai/metadata/validator/CronExpressionValidator.java - Cron 表达式验证器

前端文件:

• datai-salesforce-metadata/src/main/resources/views/TaskManager.vue - 任务管理前端组件

测试文件:

• datai-salesforce-metadata/src/test/java/com/datai/metadata/service/DataiMetaTaskServiceImplTest.java - 任务 Service 测试
• datai-salesforce-metadata/src/test/java/com/datai/metadata/validator/PackageXmlValidatorTest.java - package.xml 验证器测试
• datai-salesforce-metadata/src/test/java/com/datai/metadata/validator/CronExpressionValidatorTest.java - Cron 表达式验证器测试
• datai-salesforce-metadata/src/test/java/com/datai/metadata/controller/DataiMetaTaskControllerTest.java - 任务 Controller 测试

变更影响

对现有功能的影响

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

对数据库的影响

• 新增表: 新增了 datai_meta_task 表
• 无修改: 未修改现有表结构

对 API 的影响

• 新增接口: 新增了 6 个 RESTful API 接口
• 无修改: 未修改现有接口

对前端的影响

• 新增页面: 新增了任务管理页面
• 无修改: 未修改现有页面

测试结果

单元测试

• ✅ DataiMetaTaskServiceImpl - 所有测试通过
• ✅ PackageXmlValidator - 所有测试通过
• ✅ CronExpressionValidator - 所有测试通过
• ✅ DataiMetaTaskController - 所有测试通过

集成测试

• ✅ 任务 CRUD 操作 - 所有测试通过
• ✅ package.xml 验证 - 所有测试通过
• ✅ Cron 表达式验证 - 所有测试通过
• ✅ API 接口测试 - 所有测试通过

手动测试

• ✅ 创建任务 - 测试通过
• ✅ 编辑任务 - 测试通过
• ✅ 删除任务 - 测试通过
• ✅ 查询任务列表 - 测试通过
• ✅ 查询任务详情 - 测试通过
• ✅ 验证任务 - 测试通过

部署说明

数据库部署

执行以下 SQL 创建表：

CREATE TABLE `datai_meta_task` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '任务ID',
  `task_name` varchar(255) NOT NULL COMMENT '任务名称',
  `task_type` varchar(50) NOT NULL COMMENT '任务类型（retrieve/deploy）',
  `org_config_id` bigint NOT NULL COMMENT '组织配置ID',
  `package_xml` longtext COMMENT 'package.xml内容',
  `api_version` varchar(20) NOT NULL COMMENT 'API版本',
  `schedule_type` varchar(20) NOT NULL COMMENT '调度类型（Manual/Cron）',
  `cron_expression` varchar(100) COMMENT 'Cron表达式',
  `status` varchar(20) NOT NULL COMMENT '任务状态（Active/Inactive）',
  `description` varchar(500) COMMENT '任务描述',
  `created_by` varchar(100) COMMENT '创建人',
  `created_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_by` varchar(100) COMMENT '更新人',
  `updated_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_org_config_id` (`org_config_id`),
  KEY `idx_task_type` (`task_type`),
  KEY `idx_status` (`status`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='元数据任务定义表';

后端部署

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

前端部署

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

配置更新

无需额外配置更新。

回滚方案

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

1. 删除数据库表:

   DROP TABLE datai_meta_task;
   

2. 删除后端代码:

   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/entity/DataiMetaTask.java
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/mapper/DataiMetaTaskMapper.java
   • 删除 datai-salesforce-metadata/src/main/resources/mapper/DataiMetaTaskMapper.xml
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/service/IDataiMetaTaskService.java
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/service/impl/DataiMetaTaskServiceImpl.java
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/controller/DataiMetaTaskController.java
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/validator/PackageXmlValidator.java
   • 删除 datai-salesforce-metadata/src/main/java/com/datai/metadata/validator/CronExpressionValidator.java

3. 删除前端代码:

   • 删除 datai-salesforce-metadata/src/main/resources/views/TaskManager.vue

4. 删除测试代码:

   • 删除所有相关的测试文件

5. 重新部署: 重新编译和部署项目

相关文档

• REQ-010-4.md - 元数据任务定义管理需求
• ADR-0013.md - 元数据任务定义管理架构决策
• Prompt-014.md - 元数据任务定义管理实现提示词
• Session-20260118-001.md - 元数据任务定义管理执行会话
• metadata-module.md - Salesforce Metadata API 模块说明
• file/index.md - 文件模块 API 文档索引

审核记录

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

变更历史

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