# 任务模块API接口设计

## 1. 接口概述

任务模块提供以下主要API接口：

1. 获取任务列表
2. 获取任务详情
3. 接取任务
4. 放弃任务
5. 完成任务
6. 领取任务奖励
7. 获取任务进度

## 2. 接口详细说明

### 2.1 获取任务列表

#### 请求

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

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| type | string | 否 | 任务类型（daily, weekly, achievement, event, tutorial, team） |
| status | int | 否 | 任务状态（0:未接取, 1:进行中, 2:已完成, 3:已领取奖励, 4:已失败, 5:已过期） |
| category_id | int | 否 | 任务分类ID |
| page | int | 否 | 页码，默认1 |
| page_size | int | 否 | 每页数量，默认20 |

#### 响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "list": [
      {
        "id": 1,
        "name": "每日登录",
        "description": "完成每日登录任务",
        "type": "daily",
        "category": {
          "id": 1,
          "name": "日常任务"
        },
        "target_type": "login",
        "target_count": 1,
        "current_progress": 0,
        "status": 0,
        "rewards": [
          {
            "item_id": 1001,
            "item_name": "金币",
            "quantity": 100,
            "icon": "coin.png"
          }
        ],
        "time_limit": 86400,
        "expire_at": "2023-06-01 00:00:00",
        "is_available": true
      }
    ]
  }
}
```

### 2.2 获取任务详情

#### 请求

```
GET /api/task/detail
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "name": "每日登录",
    "description": "完成每日登录任务",
    "type": "daily",
    "category": {
      "id": 1,
      "name": "日常任务"
    },
    "target_type": "login",
    "target_params": {
      "specific_id": null
    },
    "target_count": 1,
    "current_progress": 0,
    "status": 0,
    "rewards": [
      {
        "item_id": 1001,
        "item_name": "金币",
        "quantity": 100,
        "icon": "coin.png"
      }
    ],
    "prerequisite_tasks": [
      {
        "id": 101,
        "name": "新手引导",
        "is_completed": true
      }
    ],
    "level_required": 1,
    "time_limit": 86400,
    "expire_at": "2023-06-01 00:00:00",
    "is_available": true,
    "unavailable_reason": null
  }
}
```

### 2.3 接取任务

#### 请求

```
POST /api/task/accept
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "任务接取成功",
  "data": {
    "task_id": 1,
    "status": 1,
    "progress": 0,
    "expire_at": "2023-06-01 00:00:00"
  }
}
```

#### 错误码

| 错误码 | 说明 |
|-------|------|
| 1001 | 任务不存在 |
| 1002 | 任务已接取 |
| 1003 | 任务已过期 |
| 1004 | 等级不足 |
| 1005 | 前置任务未完成 |

### 2.4 放弃任务

#### 请求

```
POST /api/task/abandon
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "任务已放弃",
  "data": {
    "task_id": 1
  }
}
```

#### 错误码

| 错误码 | 说明 |
|-------|------|
| 1001 | 任务不存在 |
| 1006 | 任务未接取 |
| 1007 | 任务已完成，无法放弃 |

### 2.5 完成任务

#### 请求

```
POST /api/task/complete
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "任务完成成功",
  "data": {
    "task_id": 1,
    "status": 2,
    "rewards": [
      {
        "item_id": 1001,
        "item_name": "金币",
        "quantity": 100,
        "icon": "coin.png"
      }
    ],
    "can_claim_now": true
  }
}
```

#### 错误码

| 错误码 | 说明 |
|-------|------|
| 1001 | 任务不存在 |
| 1006 | 任务未接取 |
| 1008 | 任务进度不足，无法完成 |
| 1009 | 任务已过期 |

### 2.6 领取任务奖励

#### 请求

```
POST /api/task/claim-reward
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "奖励领取成功",
  "data": {
    "task_id": 1,
    "status": 3,
    "rewards": [
      {
        "item_id": 1001,
        "item_name": "金币",
        "quantity": 100,
        "icon": "coin.png"
      }
    ]
  }
}
```

#### 错误码

| 错误码 | 说明 |
|-------|------|
| 1001 | 任务不存在 |
| 1010 | 任务未完成，无法领取奖励 |
| 1011 | 奖励已领取 |

### 2.7 获取任务进度

#### 请求

```
GET /api/task/progress
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "task_id": 1,
    "target_count": 10,
    "current_progress": 5,
    "percentage": 50,
    "status": 1,
    "details": [
      {
        "target_id": "1001",
        "target_name": "种植萝卜",
        "current_count": 5,
        "required_count": 10
      }
    ],
    "expire_at": "2023-06-01 00:00:00",
    "time_remaining": 3600
  }
}
```

## 3. 事件通知接口

### 3.1 任务进度更新通知

当任务进度更新时，系统会向客户端推送通知。

#### 通知内容

```json
{
  "event": "task_progress_updated",
  "data": {
    "task_id": 1,
    "old_progress": 4,
    "new_progress": 5,
    "target_count": 10,
    "percentage": 50,
    "is_completed": false
  }
}
```

### 3.2 任务完成通知

当任务完成时，系统会向客户端推送通知。

#### 通知内容

```json
{
  "event": "task_completed",
  "data": {
    "task_id": 1,
    "task_name": "每日登录",
    "rewards": [
      {
        "item_id": 1001,
        "item_name": "金币",
        "quantity": 100,
        "icon": "coin.png"
      }
    ],
    "completed_at": "2023-05-31 15:30:45"
  }
}
```

### 3.3 任务过期通知

当任务即将过期时，系统会向客户端推送通知。

#### 通知内容

```json
{
  "event": "task_expiring",
  "data": {
    "task_id": 1,
    "task_name": "每日登录",
    "expire_at": "2023-06-01 00:00:00",
    "time_remaining": 3600
  }
}
```

## 4. 批量操作接口

### 4.1 批量接取任务

#### 请求

```
POST /api/task/batch-accept
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_ids | array | 是 | 任务ID数组 |

#### 响应

```json
{
  "code": 0,
  "message": "批量接取任务成功",
  "data": {
    "success_count": 2,
    "failed_count": 1,
    "results": [
      {
        "task_id": 1,
        "success": true,
        "message": "接取成功"
      },
      {
        "task_id": 2,
        "success": true,
        "message": "接取成功"
      },
      {
        "task_id": 3,
        "success": false,
        "message": "任务已接取",
        "error_code": 1002
      }
    ]
  }
}
```

### 4.2 批量领取奖励

#### 请求

```
POST /api/task/batch-claim-reward
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| task_ids | array | 是 | 任务ID数组 |

#### 响应

```json
{
  "code": 0,
  "message": "批量领取奖励成功",
  "data": {
    "success_count": 2,
    "failed_count": 1,
    "results": [
      {
        "task_id": 1,
        "success": true,
        "rewards": [
          {
            "item_id": 1001,
            "item_name": "金币",
            "quantity": 100
          }
        ]
      },
      {
        "task_id": 2,
        "success": true,
        "rewards": [
          {
            "item_id": 1002,
            "item_name": "钻石",
            "quantity": 10
          }
        ]
      },
      {
        "task_id": 3,
        "success": false,
        "message": "任务未完成",
        "error_code": 1010
      }
    ],
    "total_rewards": [
      {
        "item_id": 1001,
        "item_name": "金币",
        "quantity": 100
      },
      {
        "item_id": 1002,
        "item_name": "钻石",
        "quantity": 10
      }
    ]
  }
}
```

## 5. 管理接口

### 5.1 创建任务

#### 请求

```
POST /api/admin/task/create
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| name | string | 是 | 任务名称 |
| description | string | 否 | 任务描述 |
| category_id | int | 是 | 任务分类ID |
| type | string | 是 | 任务类型 |
| target_type | string | 是 | 目标类型 |
| target_params | object | 否 | 目标参数 |
| target_count | int | 是 | 目标数量 |
| rewards | array | 是 | 奖励内容 |
| prerequisite_tasks | array | 否 | 前置任务 |
| level_required | int | 否 | 所需等级 |
| time_limit | int | 否 | 时间限制（秒） |
| reset_type | string | 否 | 重置类型 |
| is_active | boolean | 否 | 是否激活 |
| start_time | string | 否 | 开始时间 |
| end_time | string | 否 | 结束时间 |

#### 响应

```json
{
  "code": 0,
  "message": "任务创建成功",
  "data": {
    "id": 10,
    "name": "新任务",
    "type": "daily",
    "created_at": "2023-05-31 16:00:00"
  }
}
```

### 5.2 更新任务

#### 请求

```
POST /api/admin/task/update
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| id | int | 是 | 任务ID |
| name | string | 否 | 任务名称 |
| description | string | 否 | 任务描述 |
| category_id | int | 否 | 任务分类ID |
| type | string | 否 | 任务类型 |
| target_type | string | 否 | 目标类型 |
| target_params | object | 否 | 目标参数 |
| target_count | int | 否 | 目标数量 |
| rewards | array | 否 | 奖励内容 |
| prerequisite_tasks | array | 否 | 前置任务 |
| level_required | int | 否 | 所需等级 |
| time_limit | int | 否 | 时间限制（秒） |
| reset_type | string | 否 | 重置类型 |
| is_active | boolean | 否 | 是否激活 |
| start_time | string | 否 | 开始时间 |
| end_time | string | 否 | 结束时间 |

#### 响应

```json
{
  "code": 0,
  "message": "任务更新成功",
  "data": {
    "id": 10,
    "updated_at": "2023-05-31 16:30:00"
  }
}
```

### 5.3 删除任务

#### 请求

```
POST /api/admin/task/delete
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| id | int | 是 | 任务ID |

#### 响应

```json
{
  "code": 0,
  "message": "任务删除成功",
  "data": {
    "id": 10
  }
}
```

### 5.4 手动重置任务

#### 请求

```
POST /api/admin/task/reset
```

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| reset_type | string | 是 | 重置类型（daily, weekly, monthly） |
| task_ids | array | 否 | 指定任务ID数组，为空则重置所有符合类型的任务 |

#### 响应

```json
{
  "code": 0,
  "message": "任务重置成功",
  "data": {
    "reset_type": "daily",
    "affected_count": 15,
    "reset_time": "2023-05-31 00:00:00"
  }
}
```

## 6. 错误码汇总

| 错误码 | 说明 |
|-------|------|
| 1001 | 任务不存在 |
| 1002 | 任务已接取 |
| 1003 | 任务已过期 |
| 1004 | 等级不足 |
| 1005 | 前置任务未完成 |
| 1006 | 任务未接取 |
| 1007 | 任务已完成，无法放弃 |
| 1008 | 任务进度不足，无法完成 |
| 1009 | 任务已过期 |
| 1010 | 任务未完成，无法领取奖励 |
| 1011 | 奖励已领取 |
| 1012 | 任务不可用 |
| 1013 | 任务已失败 |
| 1014 | 批量操作部分失败 |
| 1015 | 参数错误 |
| 1016 | 操作频率限制 |
| 1017 | 系统错误 |

## 7. 接口安全性

1. 所有接口都需要进行用户身份验证
2. 敏感操作（如领取奖励）需要进行额外的安全验证
3. 接口访问频率限制，防止恶意请求
4. 服务端验证所有请求参数，防止非法数据
5. 记录关键操作日志，用于审计和问题排查