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

## 背景

根据需求 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) - 定时任务调度测试