任务模块API接口设计

1. 接口概述

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

获取任务列表
获取任务详情
接取任务
放弃任务
完成任务
领取任务奖励
获取任务进度

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

响应

{
  "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

响应

{
  "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

响应

{
  "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

响应

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

错误码

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

2.5 完成任务

请求

POST /api/task/complete

请求参数

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

响应

{
  "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

响应

{
  "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

响应

{
  "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 任务进度更新通知

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

通知内容

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

3.2 任务完成通知

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

通知内容

{
  "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 任务过期通知

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

通知内容

{
  "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数组

响应

{
  "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数组

响应

{
  "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	否	结束时间

响应

{
  "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	否	结束时间

响应

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

5.3 删除任务

请求

POST /api/admin/task/delete

请求参数

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

响应

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

5.4 手动重置任务

请求

POST /api/admin/task/reset

请求参数

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

响应

{
  "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. 接口安全性

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

API接口设计.md 12 KB History Raw

任务模块API接口设计

1. 接口概述

2. 接口详细说明

2.1 获取任务列表

请求

请求参数

响应

2.2 获取任务详情

请求

请求参数

响应

2.3 接取任务

请求

请求参数

响应

错误码

2.4 放弃任务

请求

请求参数

响应

错误码

2.5 完成任务

请求

请求参数

响应

错误码

2.6 领取任务奖励

请求

请求参数

响应

错误码

2.7 获取任务进度

请求

请求参数

响应

3. 事件通知接口

3.1 任务进度更新通知

通知内容

3.2 任务完成通知

通知内容

3.3 任务过期通知

通知内容

4. 批量操作接口

4.1 批量接取任务

请求

请求参数

响应

4.2 批量领取奖励

请求

请求参数

响应

5. 管理接口

5.1 创建任务

请求

请求参数

响应

5.2 更新任务

请求

请求参数

响应

5.3 删除任务

请求

请求参数

响应

5.4 手动重置任务

请求

请求参数

响应

6. 错误码汇总

7. 接口安全性

API接口设计.md 12 KB

History Raw