257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# 架构决策记录 - 元数据任务定义管理
|
||
|
||
## 背景
|
||
|
||
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 文档
|