datai/datai-scenes/datai-scene-salesforce/docs/decisions/adr/0006-metadata-change-auto-sync.md

架构决策记录：元数据变更自动同步本地数据库

背景

根据需求 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 - 相关架构图
• 具体节点: DataiIntegrationMetadataChangeController - 对象元数据变更控制器
• 具体节点: DataiIntegrationMetadataChangeService - 对象元数据变更服务
• 具体节点: DataiIntegrationObject - 对象同步控制实体
• 具体节点: SysJob - 定时任务调度实体
• 具体节点: JobInvokeUtil - 任务执行工具

Status

• Draft
• Accepted
• Superceded

参考资料

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

• REQ-006 - 元数据变更自动同步本地数据库需求
• DataiIntegrationMetadataChangeController - 对象元数据变更控制器
• DataiIntegrationMetadataChange - 对象元数据变更实体
• DataiIntegrationObject - 对象同步控制实体
• ObjectSyncTask - 对象自动同步任务
• SysJob - 定时任务调度实体
• JobInvokeUtil - 任务执行工具
• RyTask - 定时任务调度测试