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

## 变更信息

- **变更编号**: Change-014
- **变更日期**: 2026-01-18
- **变更类型**: 新增功能
- **变更版本**: 0.1.16
- **相关需求**: [REQ-010-4](../requirements/REQ-010-4.md) - 元数据任务定义管理
- **相关决策**: [ADR-0013](../decisions/adr/0013-task-definition-management.md) - 元数据任务定义管理架构决策
- **相关会话**: [Session-20260118-001](../sessions/20260118-task-definition-management.md) - 元数据任务定义管理执行会话

## 变更摘要

实现了完整的元数据任务定义管理功能，包括任务 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

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

**索引设计**:
- idx_org_config_id: 加速按组织配置ID查询任务
- idx_task_type: 加速按任务类型查询任务
- idx_status: 加速按状态查询任务

### API 变更

#### 新增接口

1. **POST /metadata/task** - 创建任务
   - 请求参数: DataiMetaTask
   - 响应: Result<Long>
   - 描述: 创建元数据任务

2. **PUT /metadata/task/{id}** - 更新任务
   - 请求参数: id (path), DataiMetaTask (body)
   - 响应: Result<Void>
   - 描述: 更新元数据任务

3. **DELETE /metadata/task/{id}** - 删除任务
   - 请求参数: id (path)
   - 响应: Result<Void>
   - 描述: 删除元数据任务

4. **GET /metadata/task/list** - 查询任务列表
   - 请求参数: pageNum, pageSize, taskName, taskType, status
   - 响应: Result<IPage<DataiMetaTask>>
   - 描述: 查询元数据任务列表（支持分页和条件查询）

5. **GET /metadata/task/{id}** - 查询任务详情
   - 请求参数: id (path)
   - 响应: Result<DataiMetaTask>
   - 描述: 查询元数据任务详情

6. **POST /metadata/task/{id}/validate** - 验证任务
   - 请求参数: id (path)
   - 响应: Result<ValidationResult>
   - 描述: 验证元数据任务（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 创建表：

```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. **删除数据库表**:
   ```sql
   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](../requirements/REQ-010-4.md) - 元数据任务定义管理需求
- [ADR-0013.md](../decisions/adr/0013-task-definition-management.md) - 元数据任务定义管理架构决策
- [Prompt-014.md](../prompts/014-task-definition-management.md) - 元数据任务定义管理实现提示词
- [Session-20260118-001.md](../sessions/20260118-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 |