149 lines
5.8 KiB
Markdown
149 lines
5.8 KiB
Markdown
# 定时任务文档
|
||
|
||
## 概述
|
||
|
||
本目录包含 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. 记录删除原因和影响范围
|