schoolNews/schoolNewsServ/crontab/README.md

# 定时任务模块 (Crontab Module)

## 模块简介

定时任务模块是基于Spring Boot和Quartz框架实现的动态定时任务管理系统，支持任务的动态创建、修改、启动、暂停和删除，并提供完整的任务执行日志记录功能。

## 主要功能

### 1. 任务管理
- **创建任务**: 动态创建定时任务，支持Cron表达式
- **更新任务**: 修改任务配置，自动重新调度
- **删除任务**: 删除任务并停止调度
- **启动/暂停**: 控制任务的运行状态
- **立即执行**: 手动触发任务执行一次

### 2. 任务配置
- **Bean名称和方法名**: 指定要执行的Spring Bean和方法
- **Cron表达式**: 灵活的时间调度配置
- **并发控制**: 支持控制任务是否允许并发执行
- **错过执行策略**: 配置任务错过执行时间后的处理策略

### 3. 日志记录
- **执行记录**: 记录每次任务执行的详细信息
- **执行时长**: 统计任务执行耗时
- **异常信息**: 详细记录执行失败的异常堆栈
- **日志清理**: 支持定期清理过期日志

## 数据库表结构

### tb_crontab_task (定时任务配置表)
```sql
- id: 主键ID
- task_id: 任务ID
- task_name: 任务名称
- task_group: 任务分组
- bean_name: Bean名称
- method_name: 方法名称
- method_params: 方法参数
- cron_expression: Cron表达式
- status: 任务状态（0:暂停 1:运行中）
- description: 任务描述
- concurrent: 是否允许并发执行
- misfire_policy: 错过执行策略
- creator: 创建者
- updater: 更新者
- create_time: 创建时间
- update_time: 更新时间
- delete_time: 删除时间
- deleted: 是否删除
```

### tb_crontab_log (定时任务执行日志表)
```sql
- id: 主键ID
- task_id: 任务ID
- task_name: 任务名称
- task_group: 任务分组
- bean_name: Bean名称
- method_name: 方法名称
- method_params: 方法参数
- execute_status: 执行状态（0:失败 1:成功）
- execute_message: 执行结果信息
- exception_info: 异常信息
- start_time: 开始时间
- end_time: 结束时间
- execute_duration: 执行时长（毫秒）
- create_time: 创建时间
- update_time: 更新时间
- delete_time: 删除时间
- deleted: 是否删除
```

## API接口

### 任务管理接口

#### 1. 创建定时任务
```
POST /crontab/task
Body: TbCrontabTask对象
```

#### 2. 更新定时任务
```
PUT /crontab/task
Body: TbCrontabTask对象
```

#### 3. 删除定时任务
```
DELETE /crontab/task
Body: TbCrontabTask对象
```

#### 4. 查询任务详情
```
GET /crontab/task/{taskId}
```

#### 5. 查询任务列表
```
POST /crontab/task/list
Body: 过滤条件
```

#### 6. 分页查询任务
```
POST /crontab/task/page
Body: PageRequest<TbCrontabTask>
```

#### 7. 启动任务
```
POST /crontab/task/start/{taskId}
```

#### 8. 暂停任务
```
POST /crontab/task/pause/{taskId}
```

#### 9. 立即执行任务
```
POST /crontab/task/execute/{taskId}
```

#### 10. 验证Cron表达式
```
GET /crontab/task/validate?cronExpression={expression}
```

### 日志管理接口

#### 1. 根据任务ID查询日志
```
GET /crontab/log/task/{taskId}
```

#### 2. 查询日志列表
```
POST /crontab/log/list
Body: 过滤条件
```

#### 3. 分页查询日志
```
POST /crontab/log/page
Body: PageRequest<TbCrontabLog>
```

#### 4. 查询日志详情
```
GET /crontab/log/{logId}
```

#### 5. 清理过期日志
```
DELETE /crontab/log/clean/{days}
```

#### 6. 删除日志
```
DELETE /crontab/log
Body: TbCrontabLog对象
```

## 示例任务

模块内置了三个示例任务：

### 1. SystemStatisticsTask (系统数据统计任务)
- Bean名称: `systemStatisticsTask`
- 方法名称: `execute`
- 功能: 执行系统数据统计

### 2. LogCleanTask (清理过期日志任务)
- Bean名称: `logCleanTask`
- 方法名称: `execute`
- 功能: 清理指定天数之前的日志
- 参数: 天数（默认30天）

### 3. DataBackupTask (数据备份任务)
- Bean名称: `dataBackupTask`
- 方法名称: `execute`
- 功能: 执行数据备份
- 参数: 备份类型（full-全量，incremental-增量）

## 自定义任务

要创建自定义任务，按照以下步骤：

1. 创建一个Spring Bean类
```java
@Component("myCustomTask")
public class MyCustomTask {
    
    public void execute() {
        // 任务执行逻辑
    }
    
    public void execute(String params) {
        // 带参数的任务执行逻辑
    }
}
```

2. 在数据库中添加任务配置
```sql
INSERT INTO tb_crontab_task (id, task_id, task_name, bean_name, method_name, cron_expression, status)
VALUES ('xxx', 'xxx', '我的自定义任务', 'myCustomTask', 'execute', '0 0 * * * ?', 1);
```

3. 或通过API接口创建任务

## Cron表达式示例

```
0 0 1 * * ?     每天凌晨1点执行
0 */5 * * * ?   每5分钟执行一次
0 0 0 1 * ?     每月1号凌晨执行
0 0 9-18 * * ?  每天9点到18点，每小时执行
0 0 * * * ?     每小时执行
```

## 注意事项

1. **Cron表达式格式**: 使用Spring的Cron表达式格式（6位或7位）
2. **并发控制**: 设置`concurrent=0`可防止同一任务并发执行
3. **异常处理**: 任务执行失败会记录详细的异常信息到日志表
4. **任务初始化**: 系统启动时会自动加载所有状态为"运行中"的任务
5. **线程池配置**: 默认线程池大小为10，可在`SchedulerConfig`中调整

## 技术栈

- Spring Boot 3.5.6
- Spring Scheduling
- MyBatis Plus 3.5.14
- MySQL 9.4.0
- Java 21

## 作者

yslg @ xyzh

## 更新日期

2025-10-25