datai/docs/archive/api-docs/task/MetadataChangeAutoSyncTask.md

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

任务信息

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

功能描述

自动扫描所有未同步的元数据变更记录，判断是否满足自动同步条件，并调用相应的同步方法，将元数据变更同步到本地数据库。该任务负责及时同步 Salesforce 中的对象和字段变更。

执行条件

通用条件

1. syncStatus = false 或 null（未同步）

   • 元数据变更尚未同步到本地数据库

2. retryCount < 3（重试次数小于3次）

   • 避免无限重试失败的元数据变更

对象变更条件（changeType = OBJECT）

1. 对象配置完整

   • objectApi 不为空
   • objectLabel 不为空

2. 对象启用同步

   • DataiIntegrationObject.isWork = true

3. 对象当前没有正在执行的同步任务

   • DataiIntegrationObject.syncStatus = false

4. 根据操作类型判断

   • CREATE：总是允许自动同步
   • UPDATE：总是允许自动同步
   • DELETE：总是允许自动同步

字段变更条件（changeType = FIELD）

1. 字段配置完整

   • objectApi 不为空
   • fieldApi 不为空
   • fieldLabel 不为空

2. 对象启用同步

   • DataiIntegrationObject.isWork = true

3. 对象当前没有正在执行的同步任务

   • DataiIntegrationObject.syncStatus = false

4. 根据操作类型判断

   • CREATE：总是允许自动同步
   • UPDATE：总是允许自动同步
   • DELETE：总是允许自动同步

执行流程

开始
  ↓
查询所有未同步的元数据变更记录（syncStatus = false 或 null）
  ↓
遍历每个元数据变更记录
  ↓
判断是否满足自动同步条件
  ↓
满足条件？
  ├─ 是 → 调用 syncToLocalDatabase(id)
  │         ↓
  │       记录成功/失败
  │         ↓
  │       继续下一个元数据变更
  │
  └─ 否 → 跳过，记录日志
            ↓
          继续下一个元数据变更
  ↓
输出统计信息
  ↓
结束

执行结果统计

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

统计项	描述
扫描记录数	共扫描的元数据变更记录总数
成功同步数	成功同步的元数据变更记录数量
跳过数	不满足同步条件被跳过的元数据变更记录数量
失败数	同步失败的元数据变更记录数量

日志输出

INFO 级别

开始执行元数据变更自动同步任务
查询到 5 条未同步的元数据变更记录
开始同步元数据变更，变更ID: 1, 变更类型: OBJECT, 操作类型: CREATE, 对象API: Account
元数据变更同步成功，变更ID: 1
元数据变更自动同步任务完成，共扫描 5 条记录，成功同步 4 条，跳过 1 条，失败 0 条

DEBUG 级别

元数据变更不满足同步条件，跳过同步，变更ID: 2, 变更类型: FIELD, 操作类型: UPDATE

WARN 级别

未找到对象配置，对象API: CustomObject__c

ERROR 级别

元数据变更同步失败，变更ID: 3
更新元数据变更同步失败状态时发生异常，变更ID: 3
执行元数据变更自动同步任务失败

异常处理

任务级别异常

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

元数据变更级别异常

• 捕获单个元数据变更同步失败的异常
• 记录错误日志，包含变更ID、变更类型和操作类型
• 增加失败计数，继续处理下一个元数据变更

同步失败状态更新

• 同步失败时，更新元数据变更的同步失败状态：
  • syncErrorMessage: 记录错误信息
  • retryCount: 重试次数加1
  • lastRetryTime: 记录最后重试时间

配置示例

Quartz 任务配置

INSERT INTO sys_job (job_name, job_group, invoke_target, cron_expression, status, remark)
VALUES (
  '元数据变更自动同步任务',
  'DEFAULT',
  'metadataChangeAutoSyncTask.autoSyncMetadataChanges',
  '0 0 * * * ?',
  '0',
  '每小时执行一次元数据变更自动同步任务'
);

Cron 表达式说明

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

注意事项

1. 执行频率建议

   • 建议每小时执行一次
   • 及时同步元数据变更，确保本地数据库与 Salesforce 保持一致
   • 避免在业务高峰期执行

2. 对象配置要求

   • 确保元数据变更的对象配置完整
   • 确保对象已启用同步（isWork = true）
   • 确保对象当前没有正在执行的同步任务

3. 重试机制

   • 失败的元数据变更会自动重试，最多重试3次
   • 超过3次重试后，元数据变更将不再自动同步
   • 需要手动处理重试次数超过3次的元数据变更

4. 性能考虑

   • 元数据变更数量较多时，任务执行时间可能较长
   • 建议监控任务执行时间，必要时调整执行频率
   • 考虑分批处理以避免长时间占用资源

5. 数据一致性

   • 同步前确保元数据变更信息完整
   • 建议在同步前进行数据校验
   • 记录同步失败的记录，便于后续处理

6. 变更类型处理

   • 对象变更（OBJECT）：处理对象的创建、更新、删除
   • 字段变更（FIELD）：处理字段的创建、更新、删除
   • 其他变更类型：不处理，记录日志

相关接口

• syncToLocalDatabase - 同步单个元数据变更到本地数据库
• syncBatchToLocalDatabase - 批量同步元数据变更到本地数据库

相关文档

• 需求文档 - 元数据变更自动同步本地数据库
• 架构决策 - 元数据变更自动同步本地数据库
• 变更记录 - 元数据变更自动同步本地数据库

测试信息

测试环境

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

测试用例

测试场景	输入参数	预期结果	实际结果	状态
正常同步对象变更	changeType = OBJECT, operationType = CREATE	成功同步对象变更	成功同步对象变更	通过
正步同步字段变更	changeType = FIELD, operationType = UPDATE	成步同步字段变更	成步同步字段变更	通过
跳过已同步的变更	syncStatus = true	跳过该变更	跳过该变更	通过
跳过重试次数超限的变更	retryCount = 3	跳过该变更	跳过该变更	通过
跳过对象未启用同步的变更	isWork = false	跳过该变更	跳过该变更	通过
跳过对象正在同步的变更	syncStatus = true	跳过该变更	跳过该变更	通过
同步失败	对象配置不完整	记录失败，更新重试次数	记录失败，更新重试次数	通过

实现细节

• 使用 @Component("metadataChangeAutoSyncTask") 注解注册为 Spring Bean
• 使用 @Slf4j 注解进行日志记录
• 使用 @Autowired 注入 IDataiIntegrationMetadataChangeService 和 IDataiIntegrationObjectService
• 查询所有未同步的元数据变更记录
• 遍历每个元数据变更，逐个判断同步条件
• 调用 metadataChangeService.syncToLocalDatabase(id) 执行同步
• 同步失败时，更新元数据变更的同步失败状态
• 记录详细的日志信息，便于问题排查
• 使用独立的条件判断方法，提高代码可读性和可维护性