# 架构决策记录：定时任务自动同步、插入和更新对象数据

## 背景

根据需求 REQ-005，需要在 task 目录下创建定时任务，去调用 DataiIntegrationObjectController.java 中的方法，实现所有满足条件的对象数据自动同步（存量/增量）和所有满足条件的对象数据自动插入和所有满足条件的对象数据自动更新。

当前项目中已经存在 datai-quartz 模块，提供了完整的定时任务管理功能，包括：
- SysJob 实体：定时任务配置
- SysJobLog 实体：定时任务执行日志
- JobInvokeUtil 工具：任务执行工具，支持通过反射调用 Spring Bean 方法
- ScheduleUtils 工具：定时任务调度工具
- SysJobController：定时任务管理接口
- RyTask 示例：定时任务示例类

此外，项目中已经有 RateLimitResetTask 这样的定时任务实现，可以作为参考。

## 决策

**采用现有的 Quartz 框架（datai-quartz 模块）来实现定时任务功能**

具体实现方案：
1. 在 task 目录下创建三个定时任务类：
   - `ObjectSyncTask`：对象自动同步任务
   - `ObjectInsertTask`：对象自动插入任务
   - `ObjectUpdateTask`：对象自动更新任务

2. 每个定时任务类参考 RateLimitResetTask 的写法：
   - 使用 `@Component` 注解，指定 bean 名称
   - 使用 `@Slf4j` 注解进行日志记录
   - 使用 `@Autowired` 注入 DataiIntegrationObjectService
   - 定义公共方法作为定时任务的执行方法
   - 方法内部有 try-catch 异常处理
   - 记录详细的日志信息

3. 定时任务方法实现逻辑：
   - 扫描所有对象，判断是否满足执行条件
   - 根据条件调用相应的服务方法
   - 记录执行结果和异常信息

4. 通过 datai-quartz 模块的 SysJob 实体配置定时任务的执行时间、启用状态等

## 备选方案

### 方案 1：使用现有的 Quartz 框架（datai-quartz 模块）

**优点**：
- 项目中已经存在完整的 Quartz 框架，无需额外依赖
- 提供了可视化的定时任务管理界面（SysJobController）
- 支持动态配置定时任务的执行时间、启用/禁用状态
- 提供了完整的定时任务执行日志（SysJobLog）
- 支持通过反射调用 Spring Bean 方法（JobInvokeUtil）
- 有现成的实现示例（RateLimitResetTask、RyTask）

**缺点**：
- 需要学习 Quartz 框架的使用方式
- 需要配置定时任务的 Cron 表达式

### 方案 2：使用 Spring Task（@Scheduled 注解）

**优点**：
- 简单易用，无需额外依赖
- 只需要在方法上添加 @Scheduled 注解即可
- 不需要配置 Cron 表达式（可以使用 fixedRate、fixedDelay）

**缺点**：
- 功能相对简单，不支持动态配置执行时间
- 不支持可视化的定时任务管理界面
- 不支持定时任务的启用/禁用状态切换
- 不支持定时任务执行日志的持久化
- 无法动态修改定时任务的执行时间

### 方案 3：使用 XXL-Job

**优点**：
- 功能强大，支持分布式
- 有可视化的定时任务管理界面
- 支持定时任务执行日志的持久化
- 支持动态配置定时任务

**缺点**：
- 需要部署调度中心，增加系统复杂度
- 需要额外的依赖和配置
- 项目中已经存在 Quartz 框架，引入 XXL-Job 会造成重复

## 影响

### 系统架构影响
- 在 task 目录下新增三个定时任务类
- 复用现有的 datai-quartz 模块，无需修改现有代码
- 通过 SysJob 实体配置定时任务，无需修改代码即可调整执行时间

### 开发流程影响
- 开发人员需要学习 Quartz 框架的使用方式
- 需要配置定时任务的 Cron 表达式
- 需要在数据库中配置定时任务记录

### 运维管理影响
- 可以通过 SysJobController 可视化管理定时任务
- 可以动态调整定时任务的执行时间
- 可以查看定时任务的执行日志
- 可以启用/禁用定时任务

## 风险

### 技术风险
- 定时任务执行时间可能与业务高峰期冲突，影响系统性能
- 定时任务执行失败可能导致数据不一致
- 条件判断逻辑可能存在错误，导致对象被错误地执行或遗漏

### 业务风险
- 定时任务执行时间配置不当，可能影响业务数据的及时性
- 定时任务执行失败，可能影响数据同步的及时性

### 实施风险
- 开发人员对 Quartz 框架不熟悉，可能需要一定的学习时间
- 定时任务的 Cron 表达式配置错误，可能导致任务不按预期执行

## 回滚策略

如果定时任务实现后出现问题，可以采取以下回滚策略：
1. 通过 SysJobController 禁用定时任务
2. 修改定时任务的 Cron 表达式，调整执行时间
3. 删除定时任务的数据库记录
4. 删除定时任务的 Java 类文件

## 验收标准

1. 能够正确扫描所有对象，判断是否满足执行条件
2. 能够根据对象的字段判断执行存量同步还是增量同步
3. 能够正确调用 DataiIntegrationObjectService 的方法
4. 能够记录定时任务的执行日志
5. 能够正确处理定时任务的异常情况
6. 能够通过 SysJobController 配置定时任务的执行时间
7. 能够通过 SysJobController 启用/禁用定时任务
8. 能够通过 SysJobLogController 查看定时任务的执行日志

## 视觉锚点

### Visual Reference

引用 Canvas 的具体节点或快照：
- [Authentication.canvas](../../Authentication.canvas) - 相关架构图
- **具体节点**: DataiIntegrationObjectController - 对象同步控制接口
- **具体节点**: DataiIntegrationObjectService - 对象同步服务
- **具体节点**: SysJob - 定时任务调度实体
- **具体节点**: JobInvokeUtil - 任务执行工具

### Status

- [x] Draft
- [x] Accepted
- [ ] Superceded

## 参考资料

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

- [REQ-005](../requirements/REQ-005.md) - 定时任务自动同步、插入和更新对象数据需求
- [RateLimitResetTask](../../datai-salesforce-integration/src/main/java/com/datai/integration/task/RateLimitResetTask.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) - 定时任务调度测试
- [DataiIntegrationObjectController](../../datai-salesforce-integration/src/main/java/com/datai/integration/controller/DataiIntegrationObjectController.java) - 对象同步控制接口
- [DataiIntegrationObject](../../datai-salesforce-integration/src/main/java/com/datai/integration/model/domain/DataiIntegrationObject.java) - 对象同步控制实体