# 定时任务调度服务 - API文档

## 概述

分布式定时任务调度服务，支持：
- 定时任务CRUD
- Cron表达式配置
- 任务执行记录
- 任务调度管理
- 失败重试机制
- 任务监控告警
- XXL-Job兼容接口

## 基础信息

- 基础路径: `http://localhost:8088`
- Swagger UI: `http://localhost:8088/swagger-ui.html`
- API文档: `http://localhost:8088/v3/api-docs`

## 认证

本服务暂未实现认证，生产环境请添加JWT或其他认证机制。

---

## 定时任务管理

### 创建任务

**POST** `/api/task`

**请求体:**
```json
{
  "taskName": "数据同步任务",
  "description": "每日凌晨同步业务数据",
  "taskGroup": "sync",
  "cronExpression": "0 0 2 * * ?",
  "taskClass": "dataSyncTask",
  "methodName": "execute",
  "taskParams": "{\"source\":\"erp\",\"target\":\"bi\"}",
  "taskType": "BEAN",
  "concurrent": true,
  "maxRetries": 3,
  "retryInterval": 60,
  "timeout": 3600,
  "alertEnabled": true,
  "alertEmails": "admin@example.com",
  "misfirePolicy": "DO_NOTHING",
  "owner": "admin"
}
```

**响应:**
```json
{
  "id": 1,
  "taskName": "数据同步任务",
  "status": "DRAFT",
  ...
}
```

### 查询任务

**GET** `/api/task/{id}`

### 更新任务

**PUT** `/api/task/{id}`

### 删除任务

**DELETE** `/api/task/{id}`

### 分页查询任务

**GET** `/api/task/list`

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| taskName | string | 否 | 任务名称(模糊查询) |
| taskGroup | string | 否 | 任务分组 |
| status | string | 否 | 状态 |
| page | int | 否 | 页码，默认1 |
| pageSize | int | 否 | 每页大小，默认20 |

### 启动任务

**POST** `/api/task/{id}/start`

### 停止任务

**POST** `/api/task/{id}/stop`

### 暂停任务

**POST** `/api/task/{id}/pause`

### 恢复任务

**POST** `/api/task/{id}/resume`

### 立即执行一次

**POST** `/api/task/{id}/execute`

### 获取运行中的任务

**GET** `/api/task/running`

### 获取任务统计

**GET** `/api/task/stats`

### 获取最近执行时间

**GET** `/api/task/{id}/next-fire-times?n=5`

### 验证Cron表达式

**GET** `/api/task/validate-cron?cronExpression=0/5 * * * * ?`

---

## 执行记录管理

### 查询任务执行记录

**GET** `/api/task/log/task/{taskId}`

### 查询所有执行记录

**GET** `/api/task/log/list`

### 条件查询

**GET** `/api/task/log/query`

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| taskId | long | 否 | 任务ID |
| status | string | 否 | 执行状态 |
| startTime | string | 否 | 开始时间(yyyy-MM-dd HH:mm:ss) |
| endTime | string | 否 | 结束时间 |

### 根据批次号查询

**GET** `/api/task/log/batch/{batchNo}`

### 查询可重试的失败记录

**GET** `/api/task/log/retryable?maxRetries=3`

### 清理旧日志

**DELETE** `/api/task/log/cleanup?days=30`

### 获取今日统计

**GET** `/api/task/log/stats/today`

---

## XXL-Job兼容接口

### 获取所有任务

**GET** `/api/xxl-job/jobinfo/pageList`

### 添加任务

**POST** `/api/xxl-job/jobinfo/add`

### 更新任务

**POST** `/api/xxl-job/jobinfo/update`

### 删除任务

**POST** `/api/xxl-job/jobinfo/remove?id={id}`

### 停止任务

**POST** `/api/xxl-job/jobinfo/stop?id={id}`

### 启动任务

**POST** `/api/xxl-job/jobinfo/start?id={id}`

### 触发任务执行

**POST** `/api/xxl-job/jobinfo/trigger?id={id}`

### 获取任务分组

**GET** `/api/xxl-job/jobgroup/pageList`

---

## 健康检查

### 健康检查

**GET** `/actuator/health`

**响应:**
```json
{
  "status": "UP",
  "timestamp": "2024-01-01T12:00:00",
  "components": {
    "taskScheduler": {
      "status": "UP",
      "details": {
        "runningTasks": 5
      }
    }
  }
}
```

### Prometheus指标

**GET** `/actuator/prometheus`

---

## 任务类型

| 类型 | 说明 |
|------|------|
| BEAN | Spring Bean任务，通过Bean名称调用 |
| CLASS | Java Class任务，通过反射调用 |
| XXL_JOB | XXL-Job兼容模式 |

## 任务状态

| 状态 | 说明 |
|------|------|
| DRAFT | 草稿 |
| RUNNING | 运行中 |
| STOPPED | 已停止 |
| PAUSED | 暂停 |
| ERROR | 异常 |
| DELETED | 已删除 |

## 执行状态

| 状态 | 说明 |
|------|------|
| RUNNING | 执行中 |
| SUCCESS | 成功 |
| FAILED | 失败 |
| RETRYING | 重试中 |
| TIMEOUT | 超时 |
| CANCELLED | 已取消 |

## Cron表达式示例

| 表达式 | 说明 |
|--------|------|
| `0/5 * * * * ?` | 每5秒执行 |
| `0 0 0 * * ?` | 每天零点执行 |
| `0 0 8 ? * MON-FRI` | 工作日早上8点执行 |
| `0 0/30 * * * ?` | 每30分钟执行 |
| `0 0 12 * * ?` | 每天中午12点执行 |
| `0 30 10 ? * 1-5` | 工作日早上10:30执行 |

## 错误码

| 错误码 | 说明 |
|--------|------|
| TASK_NOT_FOUND | 任务不存在 |
| TASK_EXISTS | 任务已存在 |
| INVALID_CRON | 无效的Cron表达式 |
| EXECUTION_FAILED | 任务执行失败 |
| CANNOT_START | 无法启动任务 |
| CANNOT_STOP | 无法停止任务 |
| TASK_TIMEOUT | 任务执行超时 |