datai/datai-scenes/datai-scene-salesforce/docs/api-docs/task/index.md

定时任务文档

概述

本目录包含 Salesforce 集成系统中所有定时任务的详细文档。定时任务通过 Quartz 框架调度执行，负责自动化的数据同步、插入、更新和系统维护操作。

定时任务列表

1. ObjectSyncTask - 对象自动同步任务

• 文档: ObjectSyncTask.md
• Bean 名称: objectSyncTask
• 功能: 自动扫描满足条件的对象，执行同步操作（存量同步或增量同步）
• 执行条件:
  • isWork = true（启用同步）
  • syncStatus = false（当前没有正在执行的同步任务）
  • 对象配置完整（api、label 等关键字段不为空）

2. ObjectInsertTask - 对象自动插入任务

• 文档: ObjectInsertTask.md
• Bean 名称: objectInsertTask
• 功能: 自动扫描满足条件的对象，执行插入操作到目标系统
• 执行条件:
  • isCreateable = true（可创建）
  • totalRows > 0（对象有本地数据）
  • 对象配置完整（api、label 等关键字段不为空）

3. ObjectUpdateTask - 对象自动更新任务

• 文档: ObjectUpdateTask.md
• Bean 名称: objectUpdateTask
• 功能: 自动扫描满足条件的对象，执行更新操作到目标系统
• 执行条件:
  • isUpdateable = true（可更新）
  • totalRows > 0（对象有本地数据）
  • 对象配置完整（api、label 等关键字段不为空）

4. MetadataChangeAutoSyncTask - 元数据变更自动同步任务

• 文档: MetadataChangeAutoSyncTask.md
• Bean 名称: metadataChangeAutoSyncTask
• 功能: 自动扫描未同步的元数据变更记录，执行同步操作到本地数据库
• 执行条件:
  • syncStatus = false 或 null（未同步）
  • retryCount < 3（重试次数小于3次）
  • 对象配置完整且启用同步
  • 对象当前没有正在执行的同步任务

5. RateLimitResetTask - 每日限流重置任务

• 文档: RateLimitResetTask.md
• Bean 名称: rateLimitResetTask
• 功能: 重置所有每日限流配置的使用量、剩余值和重置时间
• 执行条件: 无条件执行（每日定时执行）

定时任务配置

Quartz 配置

定时任务通过 Quartz 框架进行调度管理，需要在 sys_job 表中配置以下信息：

字段	描述	示例
job_name	任务名称	objectSyncTask
job_group	任务组	DEFAULT
invoke_target	调用目标	objectSyncTask.autoSyncObjects
cron_expression	Cron 表达式	0 0 2 * * ?
status	状态	0（正常）

推荐执行时间

任务名称	推荐执行时间	说明
ObjectSyncTask	每天凌晨 2:00	避开业务高峰期
ObjectInsertTask	每天凌晨 3:00	在同步任务之后执行
ObjectUpdateTask	每天凌晨 4:00	在插入任务之后执行
MetadataChangeAutoSyncTask	每小时执行一次	及时同步元数据变更
RateLimitResetTask	每天凌晨 0:00	每日重置

监控和日志

日志级别

所有定时任务使用 @Slf4j 注解进行日志记录，日志级别如下：

• INFO: 任务开始、完成、成功/失败统计
• DEBUG: 跳过执行的对象详细信息
• ERROR: 任务执行失败、同步/插入/更新失败

日志示例

2026-01-16 02:00:00.000 INFO  [objectSyncTask] 开始执行对象自动同步任务
2026-01-16 02:00:00.100 INFO  [objectSyncTask] 开始同步对象数据，对象ID: 1, API: Account, 增量同步: true
2026-01-16 02:00:05.500 INFO  [objectSyncTask] 对象数据同步成功，对象ID: 1, API: Account
2026-01-16 02:00:10.000 INFO  [objectSyncTask] 对象自动同步任务完成，共扫描 10 个对象，成功同步 8 个，跳过 2 个，失败 0 个

故障排查

常见问题

1. 任务未执行

   • 检查 Quartz 调度器是否启动
   • 检查任务状态是否为正常（status = 0）
   • 检查 Cron 表达式是否正确

2. 任务执行失败

   • 查看日志中的错误信息
   • 检查数据库连接是否正常
   • 检查 Salesforce API 连接是否正常

3. 对象被跳过

   • 检查对象配置是否完整
   • 检查对象是否启用同步（isWork = true）
   • 检查对象当前是否有正在执行的同步任务

相关文档

• 需求文档 - 定时任务自动同步、插入和更新对象数据
• 需求文档 - 元数据变更自动同步本地数据库
• 架构决策 - 定时任务自动同步、插入和更新对象数据
• 架构决策 - 元数据变更自动同步本地数据库
• 变更记录 - 定时任务自动同步、插入和更新对象数据
• 变更记录 - 元数据变更自动同步本地数据库

维护指南

添加新定时任务

1. 在 task 目录下创建新的任务类
2. 使用 @Component 注解，指定 bean 名称
3. 使用 @Slf4j 注解进行日志记录
4. 实现任务逻辑，包含详细的日志和异常处理
5. 在 sys_job 表中配置任务调度信息
6. 在本目录下创建对应的任务文档
7. 更新本索引文件

修改现有定时任务

1. 修改任务类代码
2. 更新对应的任务文档
3. 更新相关的需求文档、架构决策和变更记录
4. 在测试环境中充分验证

删除定时任务

1. 停用任务（在 sys_job 表中将 status 设置为 1）
2. 删除任务类代码
3. 删除对应的任务文档
4. 更新本索引文件
5. 记录删除原因和影响范围