chat-deploy/docs/API_SCHEDULED_TASK.md

# 定时任务 API 接口文档

## 基础信息

- **基础路径**: `/scheduled_task`
- **认证方式**: 所有接口都需要在请求头中携带 `token`（通过 `mw.CheckToken` 中间件验证）
- **请求方法**: 所有接口均为 `POST`

## 公共数据结构

### ScheduledTaskMessage（消息内容）

```json
{
  "type": 1,           // 消息类型：1-文本，2-图片，3-视频
  "content": "string", // 消息内容（文本内容、图片URL、视频URL等）
  "thumbnail": "string", // 缩略图URL（用于图片和视频，可选）
  "duration": 0,      // 时长（秒，用于视频，可选）
  "fileSize": 0       // 文件大小（字节，用于图片和视频，可选）
}
```

### ScheduledTaskInfo（定时任务信息）

```json
{
  "id": "string",                    // 任务ID
  "userID": "string",                // 用户ID
  "name": "string",                  // 任务名称
  "cronExpression": "string",        // Crontab表达式：分 时 日 月 周（例如："0 9 * * *"）
  "messages": [                      // 消息列表（支持多条消息一起发送）
    {
      "type": 1,
      "content": "string",
      "thumbnail": "string",
      "duration": 0,
      "fileSize": 0
    }
  ],
  "recvIDs": ["string"],             // 接收者ID列表（单聊，可以多个）
  "groupIDs": ["string"],            // 群组ID列表（群聊，可以多个）
  "status": 1,                       // 状态：0-已禁用，1-已启用
  "createTime": 1234567890123,       // 创建时间（毫秒时间戳）
  "updateTime": 1234567890123        // 更新时间（毫秒时间戳）
}
```

### RequestPagination（分页信息）

```json
{
  "pageNumber": 1,    // 页码（从1开始）
  "showNumber": 10    // 每页显示数量
}
```

## Crontab 表达式说明

格式：`分 时 日 月 周`

- **分**: 0-59
- **时**: 0-23
- **日**: 1-31
- **月**: 1-12
- **周**: 0-7（0和7都表示周日）

### 示例

- `"0 9 * * *"` - 每天9点执行
- `"*/5 * * * *"` - 每5分钟执行
- `"0 0 * * 1"` - 每周一0点执行
- `"0 12 * * 1-5"` - 周一到周五每天12点执行
- `"0 0 1 * *"` - 每月1号0点执行

---

## 1. 创建定时任务

**接口地址**: `POST /scheduled_task/create`

**请求参数**:

```json
{
  "name": "string",                  // 必填：任务名称
  "cronExpression": "string",        // 必填：Crontab表达式
  "messages": [                      // 必填：消息列表（至少一条）
    {
      "type": 1,                     // 必填：消息类型：1-文本，2-图片，3-视频
      "content": "string",            // 必填：消息内容
      "thumbnail": "string",          // 可选：缩略图URL
      "duration": 0,                  // 可选：时长（秒）
      "fileSize": 0                  // 可选：文件大小（字节）
    }
  ],
  "recvIDs": ["string"],             // 可选：接收者ID列表（单聊，可以多个）
  "groupIDs": ["string"],            // 可选：群组ID列表（群聊，可以多个）
  "status": 1                        // 可选：状态：0-已禁用，1-已启用（默认为1）
}
```

**注意**: `recvIDs` 和 `groupIDs` 至少需要提供一个，不能同时为空。

**响应参数**:

```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "taskID": "string"               // 创建的任务ID
  }
}
```

**请求示例**:

```json
{
  "name": "每日问候",
  "cronExpression": "0 9 * * *",
  "messages": [
    {
      "type": 1,
      "content": "早上好！"
    },
    {
      "type": 2,
      "content": "https://example.com/image.jpg",
      "thumbnail": "https://example.com/thumb.jpg",
      "fileSize": 102400
    }
  ],
  "recvIDs": ["user1", "user2"],
  "groupIDs": ["group1"],
  "status": 1
}
```

---

## 2. 获取定时任务详情

**接口地址**: `POST /scheduled_task/get`

**请求参数**:

```json
{
  "taskID": "string"                 // 必填：任务ID
}
```

**响应参数**:

```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "task": {                        // 定时任务信息
      "id": "string",
      "userID": "string",
      "name": "string",
      "cronExpression": "string",
      "messages": [
        {
          "type": 1,
          "content": "string",
          "thumbnail": "string",
          "duration": 0,
          "fileSize": 0
        }
      ],
      "recvIDs": ["string"],
      "groupIDs": ["string"],
      "status": 1,
      "createTime": 1234567890123,
      "updateTime": 1234567890123
    }
  }
}
```

---

## 3. 获取定时任务列表

**接口地址**: `POST /scheduled_task/list`

**请求参数**:

```json
{
  "pagination": {                    // 必填：分页信息
    "pageNumber": 1,                 // 页码（从1开始）
    "showNumber": 10                  // 每页显示数量
  }
}
```

**响应参数**:

```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 100,                    // 总数
    "tasks": [                       // 任务列表
      {
        "id": "string",
        "userID": "string",
        "name": "string",
        "cronExpression": "string",
        "messages": [
          {
            "type": 1,
            "content": "string",
            "thumbnail": "string",
            "duration": 0,
            "fileSize": 0
          }
        ],
        "recvIDs": ["string"],
        "groupIDs": ["string"],
        "status": 1,
        "createTime": 1234567890123,
        "updateTime": 1234567890123
      }
    ]
  }
}
```

---

## 4. 更新定时任务

**接口地址**: `POST /scheduled_task/update`

**请求参数**:

```json
{
  "taskID": "string",                // 必填：任务ID
  "name": "string",                   // 可选：任务名称
  "cronExpression": "string",         // 可选：Crontab表达式
  "messages": [                       // 可选：消息列表
    {
      "type": 1,
      "content": "string",
      "thumbnail": "string",
      "duration": 0,
      "fileSize": 0
    }
  ],
  "recvIDs": ["string"],             // 可选：接收者ID列表
  "groupIDs": ["string"],            // 可选：群组ID列表
  "status": 1                        // 可选：状态：0-已禁用，1-已启用
}
```

**注意**: 
- 所有字段都是可选的，只更新提供的字段
- 如果更新 `recvIDs` 和 `groupIDs`，确保至少有一个不为空

**响应参数**:

```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}
```

**请求示例**:

```json
{
  "taskID": "task123",
  "name": "更新后的任务名称",
  "status": 0
}
```

---

## 5. 删除定时任务

**接口地址**: `POST /scheduled_task/delete`

**请求参数**:

```json
{
  "taskIDs": ["string"]              // 必填：任务ID列表（支持批量删除）
}
```

**响应参数**:

```json
{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {}
}
```

**请求示例**:

```json
{
  "taskIDs": ["task1", "task2", "task3"]
}
```

---

## 错误码说明

- `0`: 成功
- 其他错误码请参考系统错误码定义

## 注意事项

1. 所有接口都需要在请求头中携带有效的 `token`
2. 用户只能操作自己创建的定时任务
3. `recvIDs` 和 `groupIDs` 可以同时提供，表示同时发送到多个单聊和群聊
4. `messages` 数组支持多条消息，会按顺序发送
5. Crontab 表达式需要符合标准格式，客户端负责解析和执行
6. 服务端只负责存储配置，不执行定时任务