复制项目
This commit is contained in:
kim.dev.6789
340
docs/API_SCHEDULED_TASK.md
Normal file
340
docs/API_SCHEDULED_TASK.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 定时任务 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. 服务端只负责存储配置，不执行定时任务
|
||||
|
||||
Reference in New Issue
Block a user