176 lines
8.0 KiB
Markdown
176 lines
8.0 KiB
Markdown
# 架构决策记录：元数据变更自动同步本地数据库
|
||
|
||
## 背景
|
||
|
||
根据需求 REQ-006，需要在 task 目录下创建定时任务，实现元数据变更自动同步到本地数据库的功能。定时任务会扫描所有未同步的元数据变更记录，根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步，并调用 DataiIntegrationMetadataChangeService 的方法执行同步操作。
|
||
|
||
当前项目中已经存在 datai-quartz 模块，提供了完整的定时任务管理功能，包括：
|
||
- SysJob 实体：定时任务配置
|
||
- SysJobLog 实体：定时任务执行日志
|
||
- JobInvokeUtil 工具：任务执行工具，支持通过反射调用 Spring Bean 方法
|
||
- ScheduleUtils 工具：定时任务调度工具
|
||
- SysJobController：定时任务管理接口
|
||
- RyTask 示例：定时任务示例类
|
||
|
||
此外，项目中已经有 RateLimitResetTask、ObjectSyncTask、ObjectInsertTask、ObjectUpdateTask 等定时任务实现，可以作为参考。
|
||
|
||
DataiIntegrationMetadataChangeController 提供了以下同步方法：
|
||
- syncToLocalDatabase(Long id)：同步单个元数据变更到本地数据库
|
||
- syncBatchToLocalDatabase(Long[] ids)：批量同步元数据变更到本地数据库
|
||
- pullAllMetadataChanges()：全对象元数据变更拉取
|
||
|
||
## 决策
|
||
|
||
**采用现有的 Quartz 框架（datai-quartz 模块）来实现元数据变更自动同步功能**
|
||
|
||
具体实现方案：
|
||
1. 在 task 目录下创建定时任务类：
|
||
- `MetadataChangeAutoSyncTask`：元数据变更自动同步任务
|
||
|
||
2. 定时任务类参考 ObjectSyncTask 的写法：
|
||
- 使用 `@Component` 注解，指定 bean 名称
|
||
- 使用 `@Slf4j` 注解进行日志记录
|
||
- 使用 `@Autowired` 注入 DataiIntegrationMetadataChangeService 和 DataiIntegrationObjectService
|
||
- 定义公共方法作为定时任务的执行方法
|
||
- 方法内部有 try-catch 异常处理
|
||
- 记录详细的日志信息
|
||
|
||
3. 定时任务方法实现逻辑：
|
||
- 查询所有未同步的元数据变更记录（syncStatus = false 或 null）
|
||
- 遍历每个元数据变更记录，判断是否满足自动同步条件
|
||
- 对于满足条件的元数据变更记录，调用相应的同步方法
|
||
- 记录执行结果和异常信息
|
||
|
||
4. 通过 datai-quartz 模块的 SysJob 实体配置定时任务的执行时间、启用状态等
|
||
|
||
## 备选方案
|
||
|
||
### 方案 1：使用现有的 Quartz 框架（datai-quartz 模块）
|
||
|
||
**优点**：
|
||
- 项目中已经存在完整的 Quartz 框架，无需额外依赖
|
||
- 提供了可视化的定时任务管理界面（SysJobController）
|
||
- 支持动态配置定时任务的执行时间、启用/禁用状态
|
||
- 提供了完整的定时任务执行日志（SysJobLog）
|
||
- 支持通过反射调用 Spring Bean 方法（JobInvokeUtil）
|
||
- 有现成的实现示例（RateLimitResetTask、ObjectSyncTask 等）
|
||
|
||
**缺点**：
|
||
- 需要学习 Quartz 框架的使用方式
|
||
- 需要配置定时任务的 Cron 表达式
|
||
|
||
### 方案 2：使用 Spring Task（@Scheduled 注解）
|
||
|
||
**优点**：
|
||
- 简单易用，无需额外依赖
|
||
- 只需要在方法上添加 @Scheduled 注解即可
|
||
- 不需要配置 Cron 表达式（可以使用 fixedRate、fixedDelay）
|
||
|
||
**缺点**：
|
||
- 功能相对简单，不支持动态配置执行时间
|
||
- 不支持可视化的定时任务管理界面
|
||
- 不支持定时任务的启用/禁用状态切换
|
||
- 不支持定时任务执行日志的持久化
|
||
- 无法动态修改定时任务的执行时间
|
||
|
||
### 方案 3：使用 XXL-Job
|
||
|
||
**优点**：
|
||
- 功能强大，支持分布式
|
||
- 有可视化的定时任务管理界面
|
||
- 支持定时任务执行日志的持久化
|
||
- 支持动态配置定时任务
|
||
|
||
**缺点**：
|
||
- 需要部署调度中心，增加系统复杂度
|
||
- 需要额外的依赖和配置
|
||
- 项目中已经存在 Quartz 框架，引入 XXL-Job 会造成重复
|
||
|
||
## 影响
|
||
|
||
### 系统架构影响
|
||
- 在 task 目录下新增一个定时任务类
|
||
- 复用现有的 datai-quartz 模块，无需修改现有代码
|
||
- 通过 SysJob 实体配置定时任务，无需修改代码即可调整执行时间
|
||
|
||
### 开发流程影响
|
||
- 开发人员需要学习 Quartz 框架的使用方式
|
||
- 需要配置定时任务的 Cron 表达式
|
||
- 需要在数据库中配置定时任务记录
|
||
|
||
### 运维管理影响
|
||
- 可以通过 SysJobController 可视化管理定时任务
|
||
- 可以动态调整定时任务的执行时间
|
||
- 可以查看定时任务的执行日志
|
||
- 可以启用/禁用定时任务
|
||
|
||
## 风险
|
||
|
||
### 技术风险
|
||
- 定时任务执行时间可能与业务高峰期冲突，影响系统性能
|
||
- 元数据变更同步失败可能导致数据不一致
|
||
- 条件判断逻辑可能存在错误，导致元数据变更被错误地同步或遗漏
|
||
- 元数据变更同步可能影响后续的数据同步操作
|
||
|
||
### 业务风险
|
||
- 定时任务执行时间配置不当，可能影响元数据同步的及时性
|
||
- 元数据变更同步失败，可能影响后续的数据同步操作
|
||
- 自动同步的元数据变更可能不符合业务需求
|
||
|
||
### 实施风险
|
||
- 开发人员对元数据变更同步逻辑不熟悉，可能需要一定的学习时间
|
||
- 定时任务的 Cron 表达式配置错误，可能导致任务不按预期执行
|
||
- 条件判断逻辑复杂，可能存在边界情况未考虑
|
||
|
||
## 回滚策略
|
||
|
||
如果定时任务实现后出现问题，可以采取以下回滚策略：
|
||
1. 通过 SysJobController 禁用定时任务
|
||
2. 修改定时任务的 Cron 表达式，调整执行时间
|
||
3. 删除定时任务的数据库记录
|
||
4. 删除定时任务的 Java 类文件
|
||
|
||
## 验收标准
|
||
|
||
1. 能够正确扫描所有未同步的元数据变更记录（syncStatus = false 或 null）
|
||
2. 能够根据元数据变更的类型、操作类型、对象配置等信息判断是否应该自动同步
|
||
3. 能够正确调用 DataiIntegrationMetadataChangeService 的方法
|
||
4. 能够记录定时任务的执行日志
|
||
5. 能够正确处理定时任务的异常情况
|
||
6. 能够通过 SysJobController 配置定时任务的执行时间
|
||
7. 能够通过 SysJobController 启用/禁用定时任务
|
||
8. 能够通过 SysJobLogController 查看定时任务的执行日志
|
||
9. 单个元数据变更同步失败不影响其他元数据变更的同步
|
||
10. 能够正确处理同步失败的情况，更新重试次数和错误信息
|
||
|
||
## 视觉锚点
|
||
|
||
### Visual Reference
|
||
|
||
引用 Canvas 的具体节点或快照：
|
||
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
|
||
- **具体节点**: DataiIntegrationMetadataChangeController - 对象元数据变更控制器
|
||
- **具体节点**: DataiIntegrationMetadataChangeService - 对象元数据变更服务
|
||
- **具体节点**: DataiIntegrationObject - 对象同步控制实体
|
||
- **具体节点**: SysJob - 定时任务调度实体
|
||
- **具体节点**: JobInvokeUtil - 任务执行工具
|
||
|
||
### Status
|
||
|
||
- [x] Draft
|
||
- [x] Accepted
|
||
- [ ] Superceded
|
||
|
||
## 参考资料
|
||
|
||
列出与该决策相关的参考资料，包括文档、文章或其他资源。
|
||
|
||
- [REQ-006](../requirements/REQ-006.md) - 元数据变更自动同步本地数据库需求
|
||
- [DataiIntegrationMetadataChangeController](../../datai-salesforce-integration/src/main/java/com/datai/integration/controller/DataiIntegrationMetadataChangeController.java) - 对象元数据变更控制器
|
||
- [DataiIntegrationMetadataChange](../../datai-salesforce-integration/src/main/java/com/datai/integration/model/domain/DataiIntegrationMetadataChange.java) - 对象元数据变更实体
|
||
- [DataiIntegrationObject](../../datai-salesforce-integration/src/main/java/com/datai/integration/model/domain/DataiIntegrationObject.java) - 对象同步控制实体
|
||
- [ObjectSyncTask](../../datai-salesforce-integration/src/main/java/com/datai/integration/task/ObjectSyncTask.java) - 对象自动同步任务
|
||
- [SysJob](../../../../../datai-models/datai-quartz/src/main/java/com/datai/quartz/domain/SysJob.java) - 定时任务调度实体
|
||
- [JobInvokeUtil](../../../../../datai-models/datai-quartz/src/main/java/com/datai/quartz/util/JobInvokeUtil.java) - 任务执行工具
|
||
- [RyTask](../../../../../datai-models/datai-quartz/src/main/java/com/datai/quartz/task/RyTask.java) - 定时任务调度测试
|