datai-vue/doc/salesforce/task/ObjectSyncTask.md

ObjectSyncTask - 对象自动同步任务

任务信息

• 任务名称: ObjectSyncTask
• Bean 名称: objectSyncTask
• 类路径: com.datai.integration.task.ObjectSyncTask
• 执行方法: autoSyncObjects()
• 模块归属: Salesforce 集成 - 定时任务
• 创建日期: 2026-01-16
• 最后更新: 2026-01-16

功能描述

自动扫描所有对象，判断是否满足同步条件，并调用相应的同步方法（存量同步或增量同步）。该任务负责将 Salesforce 对象数据同步到本地数据库。

执行条件

通用条件

1. isWork = true（启用同步）

   • 对象必须启用同步功能

2. syncStatus = false（当前没有正在执行的同步任务）

   • 避免重复执行同步操作

3. 对象配置完整

   • api 不为空
   • label 不为空

存量同步 vs 增量同步

• 存量同步: isIncremental = false（增量更新为 false）

  • 同步对象的所有数据
  • 适用于首次同步或全量更新

• 增量同步: isIncremental = true（增量更新为 true）

  • 仅同步变更的数据
  • 适用于定期更新，提高效率

执行流程

开始
  ↓
查询所有对象
  ↓
遍历每个对象
  ↓
判断是否满足同步条件
  ↓
满足条件？
  ├─ 是 → 调用 syncSingleObjectData(id)
  │         ↓
  │       记录成功/失败
  │         ↓
  │       继续下一个对象
  │
  └─ 否 → 跳过，记录日志
            ↓
          继续下一个对象
  ↓
输出统计信息
  ↓
结束

执行结果统计

任务执行完成后，会输出以下统计信息：

统计项	描述
扫描对象数	共扫描的对象总数
成功同步数	成功同步的对象数量
跳过数	不满足同步条件被跳过的对象数量
失败数	同步失败的对象数量

日志输出

INFO 级别

开始执行对象自动同步任务
开始同步对象数据，对象ID: 1, API: Account, 增量同步: true
对象数据同步成功，对象ID: 1, API: Account
对象自动同步任务完成，共扫描 10 个对象，成功同步 8 个，跳过 2 个，失败 0 个

DEBUG 级别

对象不满足同步条件，跳过同步，对象ID: 2, API: Contact

ERROR 级别

同步对象数据失败，对象ID: 3, API: Opportunity
执行对象自动同步任务失败

异常处理

任务级别异常

• 捕获所有异常，记录错误日志
• 不影响其他对象的同步操作
• 任务继续执行直到所有对象处理完成

对象级别异常

• 捕获单个对象同步失败的异常
• 记录错误日志，包含对象ID和API
• 增加失败计数，继续处理下一个对象

配置示例

Quartz 任务配置

INSERT INTO sys_job (job_name, job_group, invoke_target, cron_expression, status, remark)
VALUES (
  '对象自动同步任务',
  'DEFAULT',
  'objectSyncTask.autoSyncObjects',
  '0 0 2 * * ?',
  '0',
  '每天凌晨2点执行对象自动同步任务'
);

Cron 表达式说明

字段	值	说明
秒	0	第0秒
分	0	第0分
时	2	凌晨2点
日	*	每天
月	*	每月
周	?	不指定

注意事项

1. 执行时间建议

   • 建议在业务低峰期执行（如凌晨2点）
   • 避免与实时同步任务冲突

2. 对象配置要求

   • 确保对象的 api 和 label 字段不为空
   • 确保对象已启用同步（isWork = true）

3. 同步状态管理

   • 同步开始时，syncStatus 会被设置为 true
   • 同步完成后，syncStatus 会被设置为 false
   • 如果同步失败，syncStatus 也会被设置为 false

4. 性能考虑

   • 对象数量较多时，任务执行时间可能较长
   • 建议监控任务执行时间，必要时调整执行频率

相关接口

• syncSingleObjectData - 同步单个对象数据
• syncMultipleObjectData - 同步多个对象数据

相关文档

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

测试信息

测试环境

• 环境: 开发环境
• 版本: v1.0

测试用例

测试场景	输入参数	预期结果	实际结果	状态
正常同步	无配置	成功同步满足条件的对象	成功同步满足条件的对象	通过
跳过未启用同步的对象	isWork = false	跳过该对象	跳过该对象	通过
跳过正在同步的对象	syncStatus = true	跳过该对象	跳过该对象	通过
存量同步	isIncremental = false	执行存量同步	执行存量同步	通过
增量同步	isIncremental = true	执行增量同步	执行增量同步	通过
同步失败	对象配置不完整	记录失败，继续下一个对象	记录失败，继续下一个对象	通过

实现细节

• 使用 @Component("objectSyncTask") 注解注册为 Spring Bean
• 使用 @Slf4j 注解进行日志记录
• 使用 @Autowired 注入 IDataiIntegrationObjectService
• 遍历所有对象，逐个判断同步条件
• 调用 objectService.syncSingleObjectData(id) 执行同步
• 记录详细的日志信息，便于问题排查