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 任务配置

```sql
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](../integration/DataiIntegrationMetadataChangeController/0007-sync-to-local.md) - 同步单个元数据变更到本地数据库
- [syncBatchToLocalDatabase](../integration/DataiIntegrationMetadataChangeController/0008-sync-batch-to-local.md) - 批量同步元数据变更到本地数据库

## 相关文档

- [需求文档 - 元数据变更自动同步本地数据库](../../requirements/REQ-006.md)
- [架构决策 - 元数据变更自动同步本地数据库](../../decisions/adr/0006-metadata-change-auto-sync.md)
- [变更记录 - 元数据变更自动同步本地数据库](../../changelog/0016-metadata-change-auto-sync.md)

## 测试信息

### 测试环境

- **环境**: 开发环境
- **版本**: 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)` 执行同步
- 同步失败时，更新元数据变更的同步失败状态
- 记录详细的日志信息，便于问题排查
- 使用独立的条件判断方法，提高代码可读性和可维护性