# 架构决策记录 - 元数据任务定义管理 ## 背景 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 的具体节点或快照： - [Authentication.canvas](../../Authentication.canvas) - 相关架构图 - **具体节点**: [集成任务](node_integration_task) - 处理Salesforce的定时同步任务 ### Status - [x] Draft - [ ] Accepted - [ ] Superceded ## 参考资料 列出与该决策相关的参考资料，包括文档、文章或其他资源： - [REQ-010-4.md](../../requirements/REQ-010-4.md) - 元数据任务定义管理需求文档 - [REQ-010-1.md](../../requirements/REQ-010-1.md) - 数据库表结构设计和创建 - [REQ-010-2.md](../../requirements/REQ-010-2.md) - 基础实体类和Mapper创建 - [REQ-010-3.md](../../requirements/REQ-010-3.md) - Salesforce组织配置管理 - [Authentication.canvas](../../Authentication.canvas) - 项目架构视觉化展示 - [MyBatis Plus 官方文档](https://baomidou.com/) - MyBatis Plus 框架文档 - [Salesforce Metadata API 文档](https://developer.salesforce.com/docs/atlas.en-us.api_meta.meta/) - Salesforce Metadata API 文档