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

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

## 会话信息

- **会话编号**: Session-20260118-001
- **创建日期**: 2026-01-18
- **相关需求**: [REQ-010-4](../requirements/REQ-010-4.md) - 元数据任务定义管理
- **相关决策**: [ADR-0013](../decisions/adr/0013-task-definition-management.md) - 元数据任务定义管理架构决策
- **相关提示词**: [Prompt-014](../prompts/014-task-definition-management.md) - 元数据任务定义管理实现提示词

## 现状

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

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. 创建数据库表

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

### 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](../requirements/REQ-010-4.md) - 元数据任务定义管理需求
- [ADR-0013.md](../decisions/adr/0013-task-definition-management.md) - 元数据任务定义管理架构决策
- [Prompt-014.md](../prompts/014-task-definition-management.md) - 元数据任务定义管理实现提示词
- [metadata-module.md](../reference-code/com/docs/metadata-module.md) - Salesforce Metadata API 模块说明
- [file/index.md](../api-docs/file/index.md) - 文件模块 API 文档索引

## 审核记录

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

## 变更历史

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