234 lines
7.0 KiB
Markdown
234 lines
7.0 KiB
Markdown
# ObjectUpdateTask - 对象自动更新任务
|
||
|
||
## 任务信息
|
||
|
||
- **任务名称**: ObjectUpdateTask
|
||
- **Bean 名称**: objectUpdateTask
|
||
- **类路径**: `com.datai.integration.task.ObjectUpdateTask`
|
||
- **执行方法**: `autoUpdateObjects(String targetOrgType)` 或 `autoUpdateObjects()`
|
||
- **模块归属**: Salesforce 集成 - 定时任务
|
||
- **创建日期**: 2026-01-16
|
||
- **最后更新**: 2026-01-16
|
||
|
||
## 功能描述
|
||
|
||
自动扫描所有对象，判断是否满足更新条件，并调用相应的更新方法，将本地数据库中的对象数据更新到目标系统（如 Sandbox 环境或生产环境）。
|
||
|
||
## 执行条件
|
||
|
||
### 更新条件
|
||
|
||
1. **isUpdateable = true**（可更新）
|
||
- 对象必须在 Salesforce 中可更新
|
||
|
||
2. **totalRows > 0**（对象有本地数据）
|
||
- 对象在本地数据库中有数据需要更新
|
||
|
||
3. **对象配置完整**
|
||
- `api` 不为空
|
||
- `label` 不为空
|
||
|
||
## 方法参数
|
||
|
||
### autoUpdateObjects(String targetOrgType)
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 | 示例 | 默认值 |
|
||
|--------|------|------|------|------|--------|
|
||
| targetOrgType | String | 否 | 目标ORG类型 | "Sandbox", "Production" | "Sandbox" |
|
||
|
||
### autoUpdateObjects()
|
||
|
||
无参数，使用默认目标ORG类型 "Sandbox"。
|
||
|
||
## 执行流程
|
||
|
||
```
|
||
开始
|
||
↓
|
||
检查 targetOrgType 参数
|
||
↓
|
||
参数为空？
|
||
├─ 是 → 使用默认值 "Sandbox"
|
||
│
|
||
└─ 否 → 使用传入的参数值
|
||
↓
|
||
查询所有对象
|
||
↓
|
||
遍历每个对象
|
||
↓
|
||
判断是否满足更新条件
|
||
↓
|
||
满足条件？
|
||
├─ 是 → 调用 updateObjectDataToTarget(id, targetOrgType)
|
||
│ ↓
|
||
│ 记录成功/失败
|
||
│ ↓
|
||
│ 继续下一个对象
|
||
│
|
||
└─ 否 → 跳过，记录日志
|
||
↓
|
||
继续下一个对象
|
||
↓
|
||
输出统计信息
|
||
↓
|
||
结束
|
||
```
|
||
|
||
## 执行结果统计
|
||
|
||
任务执行完成后，会输出以下统计信息：
|
||
|
||
| 统计项 | 描述 |
|
||
|--------|------|
|
||
| 扫描对象数 | 共扫描的对象总数 |
|
||
| 成功更新数 | 成功更新的对象数量 |
|
||
| 跳过数 | 不满足更新条件被跳过的对象数量 |
|
||
| 失败数 | 更新失败的对象数量 |
|
||
|
||
## 日志输出
|
||
|
||
### INFO 级别
|
||
|
||
```
|
||
开始执行对象自动更新任务，目标ORG类型: Sandbox
|
||
目标ORG类型为空，使用默认值: Sandbox
|
||
开始更新对象数据到目标系统，对象ID: 1, API: Account, 目标ORG类型: Sandbox
|
||
对象数据更新成功，对象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',
|
||
'objectUpdateTask.autoUpdateObjects',
|
||
'0 0 4 * * ?',
|
||
'0',
|
||
'每天凌晨4点执行对象自动更新任务（使用默认目标ORG类型：Sandbox）'
|
||
);
|
||
```
|
||
|
||
### 使用自定义目标ORG类型
|
||
|
||
如果需要更新到不同的目标ORG，可以修改 `invoke_target` 字段：
|
||
|
||
```sql
|
||
UPDATE sys_job
|
||
SET invoke_target = 'objectUpdateTask.autoUpdateObjects("Production")'
|
||
WHERE job_name = '对象自动更新任务';
|
||
```
|
||
|
||
### Cron 表达式说明
|
||
|
||
| 字段 | 值 | 说明 |
|
||
|------|-----|------|
|
||
| 秒 | 0 | 第0秒 |
|
||
| 分 | 0 | 第0分 |
|
||
| 时 | 4 | 凌晨4点 |
|
||
| 日 | * | 每天 |
|
||
| 月 | * | 每月 |
|
||
| 周 | ? | 不指定 |
|
||
|
||
## 注意事项
|
||
|
||
1. **执行时间建议**
|
||
- 建议在对象插入任务之后执行（如凌晨4点）
|
||
- 确保本地数据库已有最新数据
|
||
- 避免与实时同步任务冲突
|
||
|
||
2. **目标ORG类型**
|
||
- 默认使用 "Sandbox" 环境
|
||
- 更新到生产环境前，务必在 Sandbox 环境充分测试
|
||
- 可以通过参数指定不同的目标ORG类型
|
||
|
||
3. **对象配置要求**
|
||
- 确保对象的 api 和 label 字段不为空
|
||
- 确保对象可更新（isUpdateable = true）
|
||
- 确保对象有本地数据（totalRows > 0）
|
||
|
||
4. **性能考虑**
|
||
- 对象数量较多时，任务执行时间可能较长
|
||
- 建议监控任务执行时间，必要时调整执行频率
|
||
- 考虑分批更新以避免API限流
|
||
|
||
5. **数据一致性**
|
||
- 更新前确保本地数据与目标系统数据一致
|
||
- 建议在更新前进行数据校验
|
||
- 记录更新失败的记录，便于后续处理
|
||
- 注意更新操作可能会覆盖目标系统中的数据
|
||
|
||
6. **更新策略**
|
||
- 建议先在 Sandbox 环境测试更新逻辑
|
||
- 确认更新结果无误后再执行到生产环境
|
||
- 考虑使用增量更新策略，只更新变更的数据
|
||
|
||
## 相关接口
|
||
|
||
- [updateObjectDataToTarget](../integration/DataiIntegrationObjectController/0014-query-update-progress.md) - 更新单个对象数据到目标系统
|
||
- [updateMultipleObjectDataToTarget](../integration/DataiIntegrationObjectController/0017-update-multiple-object-data-to-target.md) - 更新多个对象数据到目标系统
|
||
|
||
## 相关文档
|
||
|
||
- [需求文档 - 定时任务自动同步、插入和更新对象数据](../../requirements/REQ-005.md)
|
||
- [架构决策 - 定时任务自动同步、插入和更新对象数据](../../decisions/adr/0005-scheduled-tasks-implementation.md)
|
||
- [变更记录 - 定时任务自动同步、插入和更新对象数据](../../changelog/0015-scheduled-tasks-implementation.md)
|
||
|
||
## 测试信息
|
||
|
||
### 测试环境
|
||
|
||
- **环境**: 开发环境
|
||
- **版本**: v1.0
|
||
|
||
### 测试用例
|
||
|
||
| 测试场景 | 输入参数 | 预期结果 | 实际结果 | 状态 |
|
||
|----------|----------|----------|----------|------|
|
||
| 正常更新（默认ORG） | 无参数 | 成功更新满足条件的对象到Sandbox | 成功更新满足条件的对象到Sandbox | 通过 |
|
||
| 正常更新（自定义ORG） | "Production" | 成功更新满足条件的对象到Production | 成功更新满足条件的对象到Production | 通过 |
|
||
| 跳过不可更新的对象 | isUpdateable = false | 跳过该对象 | 跳过该对象 | 通过 |
|
||
| 跳过无数据的对象 | totalRows = 0 | 跳过该对象 | 跳过该对象 | 通过 |
|
||
| 更新失败 | 目标系统不可用 | 记录失败，继续下一个对象 | 记录失败，继续下一个对象 | 通过 |
|
||
|
||
## 实现细节
|
||
|
||
- 使用 `@Component("objectUpdateTask")` 注解注册为 Spring Bean
|
||
- 使用 `@Slf4j` 注解进行日志记录
|
||
- 使用 `@Autowired` 注入 `IDataiIntegrationObjectService`
|
||
- 提供两个重载方法：无参方法使用默认目标ORG类型，有参方法使用指定的目标ORG类型
|
||
- 遍历所有对象，逐个判断更新条件
|
||
- 调用 `objectService.updateObjectDataToTarget(id, targetOrgType)` 执行更新
|
||
- 记录详细的日志信息，便于问题排查
|