200 lines
5.7 KiB
Markdown
200 lines
5.7 KiB
Markdown
|
# 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 任务配置
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
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](../integration/DataiIntegrationObjectController/0008-sync-single-object-data.md) - 同步单个对象数据
|
|||
|
|
- [syncMultipleObjectData](../integration/DataiIntegrationObjectController/0009-sync-multiple-object-data.md) - 同步多个对象数据
|
|||
|
|
|
|||
|
|
## 相关文档
|
|||
|
|
|
|||
|
|
- [需求文档 - 定时任务自动同步、插入和更新对象数据](../../requirements/REQ-005.md)
|
|||
|
|
- [架构决策 - 定时任务自动同步、插入和更新对象数据](../../decisions/adr/0005-scheduled-tasks-implementation.md)
|
|||
|
|
- [变更记录 - 定时任务自动同步、插入和更新对象数据](../../changelog/0015-scheduled-tasks-implementation.md)
|
|||
|
|
|
|||
|
|
## 测试信息
|
|||
|
|
|
|||
|
|
### 测试环境
|
|||
|
|
|
|||
|
|
- **环境**: 开发环境
|
|||
|
|
- **版本**: v1.0
|
|||
|
|
|
|||
|
|
### 测试用例
|
|||
|
|
|
|||
|
|
| 测试场景 | 输入参数 | 预期结果 | 实际结果 | 状态 |
|
|||
|
|
|----------|----------|----------|----------|------|
|
|||
|
|
| 正常同步 | 无配置 | 成功同步满足条件的对象 | 成功同步满足条件的对象 | 通过 |
|
|||
|
|
| 跳过未启用同步的对象 | isWork = false | 跳过该对象 | 跳过该对象 | 通过 |
|
|||
|
|
| 跳过正在同步的对象 | syncStatus = true | 跳过该对象 | 跳过该对象 | 通过 |
|
|||
|
|
| 存量同步 | isIncremental = false | 执行存量同步 | 执行存量同步 | 通过 |
|
|||
|
|
| 增量同步 | isIncremental = true | 执行增量同步 | 执行增量同步 | 通过 |
|
|||
|
|
| 同步失败 | 对象配置不完整 | 记录失败，继续下一个对象 | 记录失败，继续下一个对象 | 通过 |
|
|||
|
|
|
|||
|
|
## 实现细节
|
|||
|
|
|
|||
|
|
- 使用 `@Component("objectSyncTask")` 注解注册为 Spring Bean
|
|||
|
|
- 使用 `@Slf4j` 注解进行日志记录
|
|||
|
|
- 使用 `@Autowired` 注入 `IDataiIntegrationObjectService`
|
|||
|
|
- 遍历所有对象，逐个判断同步条件
|
|||
|
|
- 调用 `objectService.syncSingleObjectData(id)` 执行同步
|
|||
|
|
- 记录详细的日志信息，便于问题排查
|