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

执行会话记录 - 元数据任务定义管理

会话信息

• 会话编号: Session-20260118-001
• 创建日期: 2026-01-18
• 相关需求: REQ-010-4 - 元数据任务定义管理
• 相关决策: ADR-0013 - 元数据任务定义管理架构决策
• 相关提示词: Prompt-014 - 元数据任务定义管理实现提示词

现状

当前系统已经完成了以下工作：

1. 数据库表结构设计: 已完成 9 张表的设计和创建（REQ-010-1）
2. 基础实体类和 Mapper 创建: 已完成基础实体类和 Mapper 的创建（REQ-010-2）
3. Salesforce 组织配置管理: 已完成组织配置管理的实现（REQ-010-3）
4. 元数据任务定义管理需求: 已完成需求文档的编写（REQ-010-4）
5. 架构决策: 已完成元数据任务定义管理的架构决策（ADR-0013）
6. 提示词资产化: 已完成元数据任务定义管理的提示词编写（Prompt-014）

目标

实现元数据任务定义管理功能，包括：

1. 任务定义 CRUD 功能

   • 创建元数据任务
   • 编辑元数据任务
   • 删除元数据任务
   • 查询元数据任务列表（支持分页和条件查询）

2. package.xml 内容配置

   • 可视化编辑 package.xml 内容
   • package.xml 格式验证
   • 支持多种元数据类型配置
   • 支持通配符配置

3. API 版本选择

   • API 版本列表展示
   • API 版本验证
   • API 版本友好显示

4. 调度类型选择

   • 支持 Manual 和 Cron 两种调度类型
   • 调度类型验证
   • 调度类型友好显示

5. Cron 表达式配置

   • Cron 表达式编辑
   • Cron 表达式验证
   • Cron 表达式预览

6. 任务验证功能

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

执行过程

步骤1：创建实体类

操作

创建 DataiMetaTask 实体类，包含以下字段：

• id: 任务ID
• taskName: 任务名称
• taskType: 任务类型（retrieve/deploy）
• orgConfigId: 组织配置ID
• packageXml: package.xml内容
• apiVersion: API版本
• scheduleType: 调度类型（Manual/Cron）
• cronExpression: Cron表达式
• status: 任务状态（Active/Inactive）
• description: 任务描述
• createdBy: 创建人
• createdTime: 创建时间
• updatedBy: 更新人
• updatedTime: 更新时间

结果

实体类创建成功，使用 MyBatis Plus 的注解进行映射。

步骤2：创建 Mapper 接口

操作

创建 DataiMetaTaskMapper 接口，继承 BaseMapper<DataiMetaTask>，并添加以下方法：

• selectTaskPage: 查询任务列表（支持分页和条件查询）
• selectByOrgConfigId: 根据组织配置ID查询任务

结果

Mapper 接口创建成功，使用 MyBatis Plus 的 @Mapper 注解进行标注。

步骤3：创建 Service 层

操作

创建 IDataiMetaTaskService 接口和 DataiMetaTaskServiceImpl 实现类，实现以下方法：

• createTask: 创建任务
• updateTask: 更新任务
• deleteTask: 删除任务
• selectTaskPage: 查询任务列表
• validateTask: 验证任务

结果

Service 层创建成功，使用 @Service 注解进行标注，使用 @Transactional 注解进行事务管理。

步骤4：创建 Controller 层

操作

创建 DataiMetaTaskController 控制器，实现以下接口：

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

结果

Controller 层创建成功，使用 @RestController 和 @RequestMapping 注解进行标注。

步骤5：创建 package.xml 验证器

操作

创建 PackageXmlValidator 验证器，实现以下功能：

• 解析 XML 格式
• 验证根元素
• 验证元数据类型
• 验证通配符

结果

package.xml 验证器创建成功，使用 @Component 注解进行标注。

步骤6：创建 Cron 表达式验证器

操作

创建 CronExpressionValidator 验证器，实现以下功能：

• 验证 Cron 表达式格式
• 解析 Cron 表达式
• 计算下次执行时间

结果

Cron 表达式验证器创建成功，使用 @Component 注解进行标注。

步骤7：创建前端组件

操作

创建 TaskManager.vue 前端组件，实现以下功能：

• 任务列表展示
• 创建任务对话框
• 编辑任务对话框
• 删除任务确认
• 任务验证功能

结果

前端组件创建成功，使用 Vue 3 和 Element Plus 进行开发。

AI 质疑和替代方案

质疑1：package.xml 存储方式

AI 质疑: 为什么选择直接存储 XML 字符串，而不是解析为结构化数据？

回答: 根据 ADR-0013 的决策，选择直接存储 XML 字符串是因为：

1. 符合 Salesforce Metadata API 规范，避免转换错误
2. 实现简单，开发周期短
3. 验证准确，可以直接使用 XML 解析库验证

替代方案: 如果未来需要更复杂的查询和管理，可以考虑解析为结构化数据存储。

质疑2：Cron 表达式验证库选择

AI 质疑: 为什么选择 Quartz 的 CronExpression 进行验证，而不是其他库？

回答: 选择 Quartz 的 CronExpression 是因为：

1. Quartz 是成熟的调度框架，CronExpression 验证准确
2. 项目已经引入了 Quartz 依赖，无需额外引入其他库
3. 支持标准的 Cron 表达式格式

替代方案: 可以考虑使用 Spring 的 CronSequenceGenerator 进行验证。

质疑3：任务验证时机

AI 质疑: 为什么在创建和更新任务时进行验证，而不是在执行任务时验证？

回答: 在创建和更新任务时进行验证是因为：

1. 提前发现配置错误，避免执行时失败
2. 提供更好的用户体验，及时反馈错误信息
3. 减少执行时的错误处理逻辑

替代方案: 可以在执行任务时再次验证，确保配置没有变更。

最终复现步骤

1. 创建数据库表

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='元数据任务定义表';

2. 创建实体类

创建 DataiMetaTask.java 实体类。

3. 创建 Mapper 接口

创建 DataiMetaTaskMapper.java Mapper 接口和 DataiMetaTaskMapper.xml XML 文件。

4. 创建 Service 层

创建 IDataiMetaTaskService.java 接口和 DataiMetaTaskServiceImpl.java 实现类。

5. 创建 Controller 层

创建 DataiMetaTaskController.java 控制器。

6. 创建验证器

创建 PackageXmlValidator.java 和 CronExpressionValidator.java 验证器。

7. 创建前端组件

创建 TaskManager.vue 前端组件。

8. 编写单元测试

为以下类编写单元测试：

• DataiMetaTaskServiceImpl
• PackageXmlValidator
• CronExpressionValidator
• DataiMetaTaskController

9. 编写集成测试

编写以下集成测试：

• 任务 CRUD 操作
• package.xml 验证
• Cron 表达式验证
• API 接口测试

10. 编写 API 文档

为以下接口编写 API 文档：

• POST /metadata/task - 创建任务
• PUT /metadata/task/{id} - 更新任务
• DELETE /metadata/task/{id} - 删除任务
• GET /metadata/task/list - 查询任务列表
• GET /metadata/task/{id} - 查询任务详情
• POST /metadata/task/{id}/validate - 验证任务

执行结果

成功实现的功能

1. ✅ 任务定义 CRUD 功能
2. ✅ package.xml 内容配置
3. ✅ API 版本选择
4. ✅ 调度类型选择
5. ✅ Cron 表达式配置
6. ✅ 任务验证功能

未实现的功能

无

遇到的问题

无

相关文档

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

审核记录

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

变更历史

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