340 lines
13 KiB
Markdown
340 lines
13 KiB
Markdown
# 变更记录 - 元数据任务定义管理
|
||
|
||
## 变更信息
|
||
|
||
- **变更编号**: 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 |
|