kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
develop
datai/docs/archive/decisions/adr/0013-metadata-task-management.md

11 KiB
Raw Permalink Blame History

架构决策记录 - 元数据任务定义管理

背景

REQ-010-4 需要实现元数据任务定义的完整管理功能，包括：

  1. 任务定义 CRUD 功能 - 支持分页查询、条件查询
  2. package.xml 内容配置 - 支持可视化编辑，符合 Salesforce Metadata API 规范
  3. API 版本选择 - 支持多种 API 版本
  4. 调度类型选择 - 支持 Manual/Cron 调度类型
  5. Cron 表达式配置 - 支持 Cron 表达式配置和验证
  6. 任务验证功能 - 验证 package.xml 和调度配置

这些功能需要基于现有的 Spring Boot 3 + Vue 3 技术栈，遵循 Authentication.canvas 中定义的架构和调用关系，使用 MyBatis Plus 作为持久层框架。

决策

1. 任务定义 CRUD 功能方案

决策: 使用 MyBatis Plus 的 BaseMapper 实现 CRUD，使用 @Valid 注解进行参数验证，使用 RESTful API 设计接口。

理由:

  • MyBatis Plus 的 BaseMapper 提供了基础的 CRUD 方法，简化了开发
  • @Valid 注解可以自动验证参数，提高代码质量和安全性
  • RESTful API 设计符合业界标准，易于使用和扩展
  • 支持分页查询和条件查询，满足业务需求

实现方案:

  • 使用 MyBatis Plus 的 BaseMapper 提供基础的 CRUD 方法
  • 使用 @Valid 注解进行参数验证
  • 使用 RESTful API 设计接口，包括 GET、POST、PUT、DELETE 方法
  • 使用 MyBatis Plus 的 QueryWrapper 实现条件查询
  • 使用 MyBatis Plus 的分页插件实现分页查询

2. package.xml 内容配置方案

决策: 使用 DOM 解析器处理 package.xml，实现可视化编辑器，支持多种元数据类型配置和通配符配置。

理由:

  • DOM 解析器是 Java 标准库的一部分，无需引入额外依赖
  • DOM 解析器可以灵活处理 XML 文件，支持增删改查操作
  • 可视化编辑器可以提高用户体验，降低使用门槛
  • 支持多种元数据类型配置和通配符配置，满足业务需求

实现方案:

  • 使用 Java DOM 解析器处理 package.xml
  • 创建 PackageXmlEditor 类，提供 package.xml 编辑功能
  • 实现可视化编辑器，支持元数据类型选择和通配符配置
  • 实现 package.xml 验证功能，验证 package.xml 格式是否符合 Salesforce Metadata API 规范
  • 实现 package.xml 预览功能，显示 package.xml 内容

3. API 版本选择方案

决策: 使用枚举类型管理 API 版本，使用配置文件管理支持的 API 版本列表。

理由:

  • 枚举类型可以提供类型安全，避免使用魔法值
  • 配置文件可以灵活管理支持的 API 版本列表，便于维护
  • 枚举类型可以提供友好的显示名称，提高用户体验

实现方案:

  • 创建 ApiVersion 枚举类，包含支持的 API 版本
  • 使用配置文件管理支持的 API 版本列表
  • 提供 getDisplayName() 方法，返回友好的显示名称
  • 提供 fromVersion() 方法，根据版本号转换为枚举类型

4. 调度类型选择方案

决策: 使用 Java 枚举类型管理调度类型，使用 @EnumValue 注解映射数据库值。

理由:

  • Java 枚举类型可以提供类型安全，避免使用魔法值
  • @EnumValue 注解可以自动映射枚举值和数据库值
  • 枚举类型可以提供友好的显示名称，提高用户体验

实现方案:

  • 创建 ScheduleType 枚举类，包含 MANUAL 和 CRON 两个值
  • 使用 @EnumValue 注解映射枚举值和数据库值
  • 提供 getDisplayName() 方法，返回友好的显示名称
  • 提供 fromCode() 方法，根据数据库值转换为枚举类型

5. Cron 表达式配置方案

决策: 使用 Cron 表达式解析库验证 Cron 表达式，实现 Cron 表达式预览功能。

理由:

  • Cron 表达式解析库可以准确验证 Cron 表达式，避免验证错误
  • Cron 表达式预览功能可以提高用户体验，帮助用户理解 Cron 表达式
  • Cron 表达式解析库支持多种 Cron 表达式格式，提高兼容性

实现方案:

  • 使用 Cron 表达式解析库验证 Cron 表达式
  • 创建 CronExpressionValidator 类，提供 Cron 表达式验证功能
  • 实现 Cron 表达式预览功能，显示 Cron 表达式的执行时间
  • 提供详细的验证错误信息，包括错误类型和错误位置

6. 任务验证功能方案

决策: 使用 DOM 解析器验证 package.xml，使用 Cron 表达式解析库验证 Cron 表达式，提供详细的验证错误信息。

理由:

  • DOM 解析器可以准确验证 package.xml 格式，避免验证错误
  • Cron 表达式解析库可以准确验证 Cron 表达式，避免验证错误
  • 详细的验证错误信息可以帮助用户快速定位和解决问题

实现方案:

  • 使用 DOM 解析器验证 package.xml 格式
  • 使用 Cron 表达式解析库验证 Cron 表达式
  • 创建 TaskValidator 类，提供任务验证功能
  • 提供详细的验证错误信息，包括错误类型和错误位置

备选方案

1. package.xml 内容配置备选方案

方案 A: 使用 SAX 解析器处理 package.xml

  • 优点: SAX 解析器内存占用低，适合处理大文件
  • 缺点: SAX 解析器不支持随机访问，不适合编辑操作
  • 不选择原因: package.xml 文件较小，DOM 解析器足够，DOM 解析器支持随机访问，适合编辑操作

方案 B: 使用 StAX 解析器处理 package.xml

  • 优点: StAX 解析器内存占用低，支持流式处理
  • 缺点: StAX 解析器不支持随机访问，不适合编辑操作
  • 不选择原因: package.xml 文件较小，DOM 解析器足够，DOM 解析器支持随机访问，适合编辑操作

2. Cron 表达式配置备选方案

方案 A: 使用正则表达式验证 Cron 表达式

  • 优点: 正则表达式可以灵活验证 Cron 表达式
  • 缺点: 正则表达式验证不准确，可能验证错误的 Cron 表达式
  • 不选择原因: Cron 表达式解析库可以准确验证 Cron 表达式，避免验证错误

方案 B: 使用自定义 Cron 表达式解析器

  • 优点: 自定义 Cron 表达式解析器可以灵活定制功能
  • 缺点: 自定义 Cron 表达式解析器开发成本高，维护成本高
  • 不选择原因: Cron 表达式解析库已经足够，无需自定义

影响

系统架构影响

  • 新增 PackageXmlEditor 类，提供 package.xml 编辑功能
  • 新增 ApiVersion 枚举类，管理 API 版本
  • 新增 ScheduleType 枚举类，管理调度类型
  • 新增 CronExpressionValidator 类，提供 Cron 表达式验证功能
  • 新增 TaskValidator 类，提供任务验证功能
  • 新增 MetadataTaskController 控制器，提供 RESTful API 接口
  • 新增 IMetadataTaskService 服务接口，定义元数据任务服务接口
  • 新增 MetadataTaskServiceImpl 服务实现，实现元数据任务服务
  • 新增 IPackageXmlService 服务接口，定义 package.xml 服务接口
  • 新增 PackageXmlServiceImpl 服务实现，实现 package.xml 服务
  • 新增 ITaskValidationService 服务接口，定义任务验证服务接口
  • 新增 TaskValidationServiceImpl 服务实现，实现任务验证服务

开发流程影响

  • 需要编写单元测试，测试 package.xml 编辑功能
  • 需要编写单元测试，测试 Cron 表达式验证功能
  • 需要编写单元测试，测试任务验证功能
  • 需要编写集成测试，测试元数据任务 CRUD 功能
  • 需要编写集成测试，测试任务验证功能

运维管理影响

  • 需要在配置文件中配置支持的 API 版本列表
  • 需要定期更新支持的 API 版本列表，确保兼容性
  • 需要监控任务执行情况，及时发现任务问题
  • 需要定期清理无效的任务，避免任务过多

风险

技术风险

  • package.xml 验证风险: package.xml 格式验证复杂可能导致验证不准确

    • 缓解措施: 使用 DOM 解析器验证 package.xml，编写详细的单元测试，覆盖各种验证场景

  • Cron 表达式解析风险: Cron 表达式解析错误可能导致任务调度失败

    • 缓解措施: 使用 Cron 表达式解析库验证 Cron 表达式，编写详细的单元测试，覆盖各种验证场景

  • 任务验证风险: 任务验证逻辑复杂可能导致验证不准确

    • 缓解措施: 编写详细的单元测试，覆盖各种验证场景，定期审查验证逻辑

业务风险

  • 多任务管理风险: 多任务管理复杂可能导致任务冲突

    • 缓解措施: 提供清晰的任务管理界面，支持任务分组和标签，定期清理无效任务

  • 任务调度风险: 任务调度不当可能导致任务执行失败

    • 缓解措施: 提供任务预览功能，帮助用户理解任务调度，提供任务执行日志

实施风险

  • 开发周期延长风险: 功能复杂可能导致开发周期延长
    • 缓解措施: 分阶段实施，优先实现核心功能，逐步完善辅助功能

回滚策略

如果决策实施后出现问题，可以采取以下回滚策略：

  1. package.xml 配置功能回滚: 如果 package.xml 配置功能出现问题，可以暂时关闭 package.xml 配置功能，使用文本编辑器编辑 package.xml，待问题解决后再启用 package.xml 配置功能

  2. Cron 表达式配置功能回滚: 如果 Cron 表达式配置功能出现问题，可以暂时关闭 Cron 表达式配置功能，使用固定时间调度，待问题解决后再启用 Cron 表达式配置功能

  3. 任务验证功能回滚: 如果任务验证功能出现问题，可以暂时关闭任务验证功能，待问题解决后再启用任务验证功能

  4. 整体回滚: 如果整个功能出现问题，可以删除新增的代码和文档，恢复到功能实现前的状态

验收标准

功能验收标准

  • 任务定义 CRUD 功能正常工作，能够成功创建、编辑、删除、查询元数据任务
  • package.xml 内容配置正常工作，能够正确配置和验证 package.xml
  • API 版本选择正常工作，能够正确选择和显示 API 版本
  • 调度类型选择正常工作，能够正确选择和显示调度类型
  • Cron 表达式配置正常工作，能够正确配置和验证 Cron 表达式
  • 任务验证功能正常工作，能够正确验证 package.xml 和调度配置

代码质量验收标准

  • 代码符合项目编码规范，有清晰的注释
  • 单元测试覆盖率不低于 80%
  • 集成测试覆盖率不低于 60%
  • 代码审查通过，没有严重的问题

性能验收标准

  • 元数据任务 CRUD 操作响应时间不超过 500ms
  • package.xml 配置操作响应时间不超过 1s
  • Cron 表达式验证操作响应时间不超过 500ms
  • 任务验证操作响应时间不超过 1s

视觉锚点

Visual Reference

引用 Canvas 的具体节点或快照：

Status

  • Draft
  • Accepted
  • Superceded

参考资料

列出与该决策相关的参考资料，包括文档、文章或其他资源：