datai/datai-scenes/datai-scene-salesforce/docs/api-docs/task/index.md

# 定时任务文档

## 概述

本目录包含 Salesforce 集成系统中所有定时任务的详细文档。定时任务通过 Quartz 框架调度执行，负责自动化的数据同步、插入、更新和系统维护操作。

## 定时任务列表

### 1. ObjectSyncTask - 对象自动同步任务
- **文档**: [ObjectSyncTask.md](ObjectSyncTask.md)
- **Bean 名称**: objectSyncTask
- **功能**: 自动扫描满足条件的对象，执行同步操作（存量同步或增量同步）
- **执行条件**:
  - isWork = true（启用同步）
  - syncStatus = false（当前没有正在执行的同步任务）
  - 对象配置完整（api、label 等关键字段不为空）

### 2. ObjectInsertTask - 对象自动插入任务
- **文档**: [ObjectInsertTask.md](ObjectInsertTask.md)
- **Bean 名称**: objectInsertTask
- **功能**: 自动扫描满足条件的对象，执行插入操作到目标系统
- **执行条件**:
  - isCreateable = true（可创建）
  - totalRows > 0（对象有本地数据）
  - 对象配置完整（api、label 等关键字段不为空）

### 3. ObjectUpdateTask - 对象自动更新任务
- **文档**: [ObjectUpdateTask.md](ObjectUpdateTask.md)
- **Bean 名称**: objectUpdateTask
- **功能**: 自动扫描满足条件的对象，执行更新操作到目标系统
- **执行条件**:
  - isUpdateable = true（可更新）
  - totalRows > 0（对象有本地数据）
  - 对象配置完整（api、label 等关键字段不为空）

### 4. MetadataChangeAutoSyncTask - 元数据变更自动同步任务
- **文档**: [MetadataChangeAutoSyncTask.md](MetadataChangeAutoSyncTask.md)
- **Bean 名称**: metadataChangeAutoSyncTask
- **功能**: 自动扫描未同步的元数据变更记录，执行同步操作到本地数据库
- **执行条件**:
  - syncStatus = false 或 null（未同步）
  - retryCount < 3（重试次数小于3次）
  - 对象配置完整且启用同步
  - 对象当前没有正在执行的同步任务

### 5. RateLimitResetTask - 每日限流重置任务
- **文档**: [RateLimitResetTask.md](RateLimitResetTask.md)
- **Bean 名称**: rateLimitResetTask
- **功能**: 重置所有每日限流配置的使用量、剩余值和重置时间
- **执行条件**: 无条件执行（每日定时执行）

## 定时任务配置

### Quartz 配置

定时任务通过 Quartz 框架进行调度管理，需要在 `sys_job` 表中配置以下信息：

| 字段 | 描述 | 示例 |
|------|------|------|
| job_name | 任务名称 | objectSyncTask |
| job_group | 任务组 | DEFAULT |
| invoke_target | 调用目标 | objectSyncTask.autoSyncObjects |
| cron_expression | Cron 表达式 | 0 0 2 * * ? |
| status | 状态 | 0（正常） |

### 推荐执行时间

| 任务名称 | 推荐执行时间 | 说明 |
|----------|--------------|------|
| ObjectSyncTask | 每天凌晨 2:00 | 避开业务高峰期 |
| ObjectInsertTask | 每天凌晨 3:00 | 在同步任务之后执行 |
| ObjectUpdateTask | 每天凌晨 4:00 | 在插入任务之后执行 |
| MetadataChangeAutoSyncTask | 每小时执行一次 | 及时同步元数据变更 |
| RateLimitResetTask | 每天凌晨 0:00 | 每日重置 |

## 监控和日志

### 日志级别

所有定时任务使用 `@Slf4j` 注解进行日志记录，日志级别如下：

- **INFO**: 任务开始、完成、成功/失败统计
- **DEBUG**: 跳过执行的对象详细信息
- **ERROR**: 任务执行失败、同步/插入/更新失败

### 日志示例

```
2026-01-16 02:00:00.000 INFO  [objectSyncTask] 开始执行对象自动同步任务
2026-01-16 02:00:00.100 INFO  [objectSyncTask] 开始同步对象数据，对象ID: 1, API: Account, 增量同步: true
2026-01-16 02:00:05.500 INFO  [objectSyncTask] 对象数据同步成功，对象ID: 1, API: Account
2026-01-16 02:00:10.000 INFO  [objectSyncTask] 对象自动同步任务完成，共扫描 10 个对象，成功同步 8 个，跳过 2 个，失败 0 个
```

## 故障排查

### 常见问题

1. **任务未执行**
   - 检查 Quartz 调度器是否启动
   - 检查任务状态是否为正常（status = 0）
   - 检查 Cron 表达式是否正确

2. **任务执行失败**
   - 查看日志中的错误信息
   - 检查数据库连接是否正常
   - 检查 Salesforce API 连接是否正常

3. **对象被跳过**
   - 检查对象配置是否完整
   - 检查对象是否启用同步（isWork = true）
   - 检查对象当前是否有正在执行的同步任务

## 相关文档

- [需求文档 - 定时任务自动同步、插入和更新对象数据](../requirements/REQ-005.md)
- [需求文档 - 元数据变更自动同步本地数据库](../requirements/REQ-006.md)
- [架构决策 - 定时任务自动同步、插入和更新对象数据](../decisions/adr/0005-scheduled-tasks-implementation.md)
- [架构决策 - 元数据变更自动同步本地数据库](../decisions/adr/0006-metadata-change-auto-sync.md)
- [变更记录 - 定时任务自动同步、插入和更新对象数据](../changelog/0015-scheduled-tasks-implementation.md)
- [变更记录 - 元数据变更自动同步本地数据库](../changelog/0016-metadata-change-auto-sync.md)

## 维护指南

### 添加新定时任务

1. 在 `task` 目录下创建新的任务类
2. 使用 `@Component` 注解，指定 bean 名称
3. 使用 `@Slf4j` 注解进行日志记录
4. 实现任务逻辑，包含详细的日志和异常处理
5. 在 `sys_job` 表中配置任务调度信息
6. 在本目录下创建对应的任务文档
7. 更新本索引文件

### 修改现有定时任务

1. 修改任务类代码
2. 更新对应的任务文档
3. 更新相关的需求文档、架构决策和变更记录
4. 在测试环境中充分验证

### 删除定时任务

1. 停用任务（在 `sys_job` 表中将 status 设置为 1）
2. 删除任务类代码
3. 删除对应的任务文档
4. 更新本索引文件
5. 记录删除原因和影响范围