# 抽奖API接口说明 ## 概述 本文档描述了抽奖系统的API接口，包括活动管理、抽奖操作、记录查询等功能。 ## 接口列表 ### 1. 获取抽奖活动列表 **接口地址**: `/api/lottery/activityList` **请求方式**: GET **参数说明**: - `page` (可选): 页码，默认1 - `pageSize` (可选): 每页数量，默认10 - `status` (可选): 活动状态，默认进行中 **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 1, "name": "新年抽奖活动", "description": "活动描述", "cover_image": "/uploads/cover.jpg", "type": 1, "status": 2, "start_time": 1640995200, "end_time": 1641081600, "lottery_type": 1, "guide_image": "/uploads/guide.jpg", "guide_text": "活动引导文字", "intro_content": "活动详细介绍", "prizes": [ { "id": 1, "name": "一等奖", "type": 2, "image": "/uploads/prize1.jpg", "probability": 0.01 } ], "total_participants": 100 } ], "total": 1 } } ``` ### 2. 获取活动详情 **接口地址**: `/api/lottery/activityDetail` **请求方式**: GET **参数说明**: - `activity_id` (必填): 活动ID **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "id": 1, "name": "新年抽奖活动", "description": "活动描述", "cover_image": "/uploads/cover.jpg", "type": 1, "status": 2, "start_time": 1640995200, "end_time": 1641081600, "lottery_type": 1, "guide_image": "/uploads/guide.jpg", "guide_text": "活动引导文字", "intro_content": "活动详细介绍", "prizes": [ { "id": 1, "name": "一等奖", "type": 2, "image": "/uploads/prize1.jpg", "description": "奖品描述", "probability": 0.01, "total_stock": 10, "remain_stock": 8, "win_prompt": "恭喜中奖！", "sort_order": 1, "unlock_people_num": 100, "is_unlocked": true } ], "total_participants": 100, "user_chances": { "total_chances": 10, "used_chances": 3, "remain_chances": 7, "last_get_time": 1640995200, "last_use_time": 1640995300 }, "user_draw_count": 3, "user_win_count": 1 } } ``` ### 3. 执行抽奖 **接口地址**: `/api/lottery/draw` **请求方式**: POST **参数说明**: - `activity_id` (必填): 活动ID **返回示例**: ```json { "code": 1, "msg": "抽奖成功", "data": { "draw_id": 123, "is_win": true, "prize": { "id": 1, "name": "一等奖", "type": 2, "type_text": "实物奖品", "image": "/uploads/prize1.jpg", "win_prompt": "恭喜中奖！" }, "draw_time": 1640995400, "win_record_id": 456, "deliver_status": 0, "exchange_code": null } } ``` ### 4. 获取用户抽奖机会 **接口地址**: `/api/lottery/getUserChances` **请求方式**: GET **参数说明**: - `activity_id` (必填): 活动ID **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "total_chances": 10, "used_chances": 3, "remain_chances": 7, "last_get_time": 1640995200, "last_use_time": 1640995300 } } ``` ### 5. 获取用户抽奖记录 **接口地址**: `/api/lottery/getDrawRecords` **请求方式**: GET **参数说明**: - `activity_id` (可选): 活动ID，不传则查询所有活动 - `page` (可选): 页码，默认1 - `limit` (可选): 每页数量，默认20 **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 123, "activity_id": 1, "activity_name": "新年抽奖活动", "prize_id": 1, "prize_name": "一等奖", "prize_type": 2, "prize_image": "/uploads/prize1.jpg", "is_win": true, "draw_time": 1640995400, "trigger_type_text": "购买商品", "win_record": { "id": 456, "deliver_status": 0, "deliver_status_text": "待发放", "deliver_time": null, "exchange_code": null } } ], "total": 1 } } ``` ### 6. 获取用户中奖记录 **接口地址**: `/api/lottery/getWinRecords` **请求方式**: GET **参数说明**: - `page` (可选): 页码，默认1 - `limit` (可选): 每页数量，默认20 **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 456, "activity_id": 1, "activity_name": "新年抽奖活动", "prize_id": 1, "prize_name": "一等奖", "prize_type": 2, "deliver_status": 0, "deliver_status_text": "待发放", "deliver_time": null, "exchange_code": null, "createtime": 1640995400, "amount": 100.00 } ], "total": 1 } } ``` ### 7. 设置中奖记录收货地址 **接口地址**: `/api/lottery/setWinRecordAddress` **请求方式**: POST **参数说明**: - `win_record_id` (必填): 中奖记录ID - `receiver_name` (必填): 收货人姓名 - `receiver_mobile` (必填): 收货人手机号 - `receiver_address` (必填): 收货地址 **返回示例**: ```json { "code": 1, "msg": "设置成功", "data": null } ``` ### 8. 获取活动排行榜 **接口地址**: `/api/lottery/getRanking` **请求方式**: GET **参数说明**: - `activity_id` (必填): 活动ID - `page` (可选): 页码，默认1 - `limit` (可选): 每页数量，默认50 **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": [ { "rank": 1, "user_id": 123, "nickname": "用户昵称", "avatar": "/uploads/avatar.jpg", "win_count": 5 } ] } ``` ### 9. 获取奖品列表 **接口地址**: `/api/lottery/getPrizes` **请求方式**: GET **参数说明**: - `lottery_id` (可选): 活动ID，不传则查询进行中活动的奖品 - `page` (可选): 页码，默认1 - `pageSize` (可选): 每页数量，默认10 - `type` (可选): 奖品类型筛选，支持JSON数组格式 **返回示例**: ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 1, "activity_id": 1, "name": "一等奖", "type": 2, "type_text": "实物奖品", "image": "/uploads/prize1.jpg", "description": "奖品描述", "probability": 0.01, "probability_percent": 1.00, "total_stock": 10, "remain_stock": 8, "stock_percent": 80.00, "win_prompt": "恭喜中奖！", "sort_order": 1, "unlock_people_num": 100, "is_unlocked": true, "activity_name": "新年抽奖活动", "activity_status": 2, "createtime": 1640995200 } ], "total": 1, "current_page": 1, "last_page": 1, "per_page": 10 } } ``` ## 奖品类型说明 | 类型值 | 类型名称 | 说明 | |--------|----------|------| | 1 | 未中奖 | 未中奖类型 | | 2 | 实物奖品 | 实物商品 | | 3 | 积分 | 用户积分 | | 4 | 余额 | 用户余额 | | 5 | 优惠券 | 优惠券 | | 6 | 红包 | 红包 | | 7 | 兑换码 | 兑换码 | | 8 | 商城奖品 | 商城商品 | ## 活动状态说明 | 状态值 | 状态名称 | 说明 | |--------|----------|------| | 1 | 未开始 | 活动未开始 | | 2 | 进行中 | 活动进行中 | | 3 | 已结束 | 活动已结束 | | 4 | 已取消 | 活动已取消 | | 5 | 已暂停 | 活动已暂停 | ## 发放状态说明 | 状态值 | 状态名称 | 说明 | |--------|----------|------| | 0 | 待发放 | 奖品待发放 | | 1 | 已发放 | 奖品已发放 | | 2 | 发放失败 | 奖品发放失败 | | 3 | 已取消 | 奖品发放已取消 | ## 错误码说明 | 错误码 | 说明 | |--------|------| | 1 | 成功 | | 0 | 失败 | ## 注意事项 1. 所有需要登录的接口都需要在请求头中携带用户token 2. 分页参数page从1开始 3. 时间戳使用秒级时间戳 4. 图片路径为相对路径，需要拼接域名 5. 概率值为0-1之间的小数 6. 库存数量为整数 7. 金额单位为元，保留两位小数