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