# 定时任务模块使用指南

## 概述

本项目集成了GoFrame的gcron模块，提供了完整的定时任务管理功能。定时任务会在项目启动时自动启动，并在项目关闭时优雅停止。

## 功能特性

- ✅ 自动启动和停止定时任务
- ✅ 支持Cron表达式配置
- ✅ 任务执行日志记录
- ✅ 优雅关闭支持
- ✅ RESTful API管理接口
- ✅ 配置文件管理
- ✅ 任务状态监控

## 默认任务

项目启动时会自动注册以下默认任务：

### 1. 数据同步任务 (data_sync_hourly)
- **执行频率**: 每小时执行一次
- **Cron表达式**: `0 * * * *`
- **功能**: 从第三方网站同步数据到数据库

### 2. 数据清理任务 (data_cleanup_daily)
- **执行频率**: 每天凌晨2点执行
- **Cron表达式**: `0 2 * * *`
- **功能**: 清理过期的缓存数据和日志记录

### 3. 健康检查任务 (health_check)
- **执行频率**: 每5分钟执行一次
- **Cron表达式**: `*/5 * * * *`
- **功能**: 检查系统健康状态

### 4. 缓存刷新任务 (cache_refresh)
- **执行频率**: 每30分钟执行一次
- **Cron表达式**: `*/30 * * * *`
- **功能**: 刷新系统缓存

## API接口

### 获取任务列表
```http
GET /cron/jobs
```

### 添加新任务
```http
POST /cron/jobs
Content-Type: application/json

{
  "name": "custom_job",
  "cron": "0 12 * * *"
}
```

### 移除任务
```http
DELETE /cron/jobs/{name}
```

### 获取任务状态
```http
GET /cron/jobs/{name}/status
```

## Cron表达式说明

Cron表达式格式：`秒 分 时 日 月 周`

### 常用示例
- `0 * * * *` - 每小时执行
- `0 0 * * *` - 每天零点执行
- `0 0 0 * *` - 每月1号零点执行
- `0 0 0 * * 0` - 每周日零点执行
- `*/5 * * * *` - 每5分钟执行
- `0 0 12 * * 1-5` - 工作日中午12点执行

## 配置文件

定时任务配置位于 `manifest/config/cron.yaml`：

```yaml
cron:
  enabled: true
  jobs:
    data_sync_hourly:
      enabled: true
      cron: "0 * * * *"
      description: "每小时从第三方网站同步数据"
  execution:
    max_concurrent: 10
    timeout: 300
    retry_count: 3
    retry_interval: 60
```

## 添加自定义任务

### 1. 在代码中添加任务

```go
// 在 internal/logic/cron/cron.go 的 registerDefaultJobs 方法中添加
if err := l.AddJob(ctx, "my_custom_job", "0 8 * * *", func() {
    // 你的任务逻辑
    l.myCustomTask(ctx)
}); err != nil {
    return err
}
```

### 2. 实现任务逻辑

```go
func (l *Logic) myCustomTask(ctx context.Context) {
    g.Log().Info(ctx, "执行自定义任务...")
    
    // 1. 调用第三方API
    // 2. 处理数据
    // 3. 更新数据库
    // 4. 记录日志
}
```

### 3. 通过API动态添加

```bash
curl -X POST http://localhost:8283/cron/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dynamic_job",
    "cron": "0 9 * * *"
  }'
```

## 监控和日志

### 日志查看
定时任务的执行日志会记录在应用日志中，包含：
- 任务开始时间
- 任务执行时长
- 任务完成状态
- 错误信息（如果有）

### 日志示例
```
2024-01-01 10:00:00 [INFO] Starting job: data_sync_hourly at 2024-01-01 10:00:00
2024-01-01 10:00:05 [INFO] Completed job: data_sync_hourly, duration: 5.2s
```

## 最佳实践

### 1. 任务设计原则
- 任务应该是幂等的（可重复执行）
- 避免长时间运行的任务
- 合理设置超时时间
- 添加适当的错误处理

### 2. 性能优化
- 使用连接池
- 批量处理数据
- 合理使用缓存
- 避免在任务中执行耗时操作

### 3. 监控建议
- 定期检查任务执行状态
- 监控任务执行时间
- 设置告警机制
- 保留执行日志

## 故障排除

### 常见问题

1. **任务未执行**
   - 检查Cron表达式是否正确
   - 确认任务是否已注册
   - 查看应用日志

2. **任务执行失败**
   - 检查网络连接
   - 验证API接口可用性
   - 查看错误日志

3. **任务执行超时**
   - 优化任务逻辑
   - 增加超时时间
   - 考虑异步处理

### 调试方法

1. 启用调试日志
2. 使用API接口检查任务状态
3. 查看系统资源使用情况
4. 检查数据库连接状态

## 扩展功能

后续可以扩展的功能：
- 任务执行历史记录
- 任务依赖关系管理
- 分布式任务调度
- 任务执行统计
- Web界面管理
- 邮件/短信告警