329 lines
9.5 KiB
Markdown
329 lines
9.5 KiB
Markdown
# 执行会话记录 - 元数据任务定义管理
|
||
|
||
## 会话信息
|
||
|
||
- **会话编号**: 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 |
|