# 消费抽奖营销活动系统 - 接口使用说明 ## 系统概述 本系统是一个基于消费行为的抽奖营销活动系统，支持多种奖品类型、灵活的参与条件和开奖方式。通过用户购买商品、充值等行为自动获得抽奖机会，提高用户参与度和复购率。 ## 核心功能 - **多样化奖品**：支持实物奖品、优惠券、红包、兑换码、商城奖品 - **灵活条件**：支持购买指定商品、消费满额、充值满额等触发条件 - **三种开奖模式**：即抽即中、按时间开奖、按人数开奖 - **精准投放**：支持会员等级、会员标签的精准用户群体控制 - **完善统计**：详细的抽奖记录和数据统计分析 ## 数据表结构 系统包含以下核心数据表： 1. **shop_lottery_activity** - 活动主表 2. **shop_lottery_prize** - 奖品表 3. **shop_lottery_condition** - 参与条件表 4. **shop_lottery_draw_record** - 抽奖记录表 5. **shop_lottery_win_record** - 中奖记录表 6. **shop_lottery_user_chance** - 用户抽奖机会表 7. **shop_lottery_statistics** - 活动统计表 请先执行数据库建表脚本创建相关表结构。 ## API接口说明 ### 基础接口路径 ``` /api/lottery/ ``` ### 1. 获取活动列表 **接口地址：** `GET /api/lottery/activityList` **请求参数：** ```json { "page": 1, // 页码，默认1 "limit": 10, // 每页数量，默认10 "status": 1 // 活动状态，默认1（进行中） } ``` **返回示例：** ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 1, "name": "新用户专享抽奖", "description": "新用户购买任意商品即可参与抽奖", "cover_image": "/uploads/lottery/cover1.jpg", "status": 1, "lottery_type": 1, "prizes": [ { "id": 1, "name": "iPhone 15", "type": 2, "image": "/uploads/prize/iphone15.jpg", "probability": 0.01 } ], "total_participants": 1580 } ], "total": 5 } } ``` ### 2. 获取活动详情 **接口地址：** `GET /api/lottery/activityDetail` **请求参数：** ```json { "activity_id": 1 // 活动ID，必填 } ``` **返回示例：** ```json { "code": 1, "msg": "获取成功", "data": { "id": 1, "name": "新用户专享抽奖", "description": "活动描述", "start_time": 1703980800, "end_time": 1704067200, "lottery_type": 1, "person_limit_num": 3, "prizes": [ { "id": 1, "name": "iPhone 15", "type": 2, "probability": 0.01, "remain_stock": 10, "is_unlocked": true } ], "user_chances": { "total_chances": 5, "used_chances": 2, "remain_chances": 3 }, "user_draw_count": 2, "user_win_count": 1 } } ``` ### 3. 执行抽奖 **接口地址：** `POST /api/lottery/draw` **请求参数：** ```json { "activity_id": 1 // 活动ID，必填 } ``` **返回示例：** ```json { "code": 1, "msg": "抽奖成功", "data": { "draw_id": 12345, "is_win": 1, "prize": { "id": 2, "name": "10元优惠券", "type": 3, "type_text": "优惠券", "image": "/uploads/coupon.jpg", "win_prompt": "恭喜获得10元优惠券！" }, "win_record_id": 6789, "deliver_status": 1, "draw_time": 1703980800 } } ``` ### 4. 获取用户抽奖机会 **接口地址：** `GET /api/lottery/getUserChances` **请求参数：** ```json { "activity_id": 1 // 活动ID，必填 } ``` **返回示例：** ```json { "code": 1, "msg": "获取成功", "data": { "total_chances": 5, "used_chances": 2, "remain_chances": 3, "last_get_time": 1703980800, "last_use_time": 1703981000, "get_detail": [ { "trigger_type": "order", "order_id": 1001, "order_amount": 299.00, "granted_time": 1703980800 } ] } } ``` ### 5. 获取抽奖记录 **接口地址：** `GET /api/lottery/getDrawRecords` **请求参数：** ```json { "activity_id": 1, // 活动ID，可选 "page": 1, // 页码，默认1 "limit": 20 // 每页数量，默认20 } ``` **返回示例：** ```json { "code": 1, "msg": "获取成功", "data": { "list": [ { "id": 12345, "activity_id": 1, "activity_name": "新用户专享抽奖", "prize_name": "10元优惠券", "is_win": 1, "draw_time": 1703980800, "win_record": { "id": 6789, "deliver_status": 1, "deliver_status_text": "已发放" } } ], "total": 10 } } ``` ### 6. 获取中奖记录 **接口地址：** `GET /api/lottery/getWinRecords` **请求参数：** ```json { "page": 1, // 页码，默认1 "limit": 20 // 每页数量，默认20 } ``` ### 7. 设置收货地址 **接口地址：** `POST /api/lottery/setWinRecordAddress` **请求参数：** ```json { "win_record_id": 6789, "receiver_name": "张三", "receiver_mobile": "13800138000", "receiver_address": "北京市朝阳区某某小区1号楼101室" } ``` ### 8. 获取活动排行榜 **接口地址：** `GET /api/lottery/getRanking` **请求参数：** ```json { "activity_id": 1, // 活动ID，必填 "page": 1, // 页码，默认1 "limit": 50 // 每页数量，默认50 } ``` ## 核心服务使用 ### 1. 抽奖服务 (LotteryService) ```php use app\common\Service\LotteryService; // 执行抽奖 $result = LotteryService::drawLottery($activityId, $userId, $triggerType, $triggerOrderId, $triggerAmount); // 获取用户抽奖机会 $chances = LotteryService::getUserChances($activityId, $userId); ``` ### 2. 抽奖机会服务 (LotteryChanceService) ```php use app\common\Service\LotteryChanceService; // 订单完成后分发抽奖机会 $orderInfo = [ 'id' => $orderId, 'user_id' => $userId, 'total_amount' => 299.00, 'goods' => [ ['goods_id' => 1, 'goods_sku_id' => 1, 'nums' => 2] ] ]; $grantedChances = LotteryChanceService::checkAndGrantChanceForOrder($orderInfo, $userId); // 充值完成后分发抽奖机会 $rechargeInfo = [ 'id' => $rechargeId, 'user_id' => $userId, 'amount' => 100.00 ]; $grantedChances = LotteryChanceService::checkAndGrantChanceForRecharge($rechargeInfo, $userId); // 手动给用户增加抽奖机会（管理员操作） LotteryChanceService::manualGrantChance($activityId, $userId, 3, '客服补偿', $adminId); ``` ## 订单钩子集成 系统提供了订单完成钩子，可以在订单支付完成或充值完成时自动检查并分发抽奖机会。 ### 1. 在 tags.php 中注册钩子 ```php // application/tags.php 或相应的钩子配置文件 return [ // 订单支付完成钩子 'order_paid' => [ 'app\\common\\behavior\\LotteryOrderHook' ], // 充值完成钩子 'recharge_paid' => [ 'app\\common\\behavior\\LotteryOrderHook' ] ]; ``` ### 2. 在订单支付完成时触发钩子 ```php // 在订单支付完成的地方调用 \think\Hook::listen('order_paid', ['order' => $orderInfo]); // 在充值完成的地方调用 \think\Hook::listen('recharge_paid', ['recharge' => $rechargeInfo]); ``` ## 抽奖算法说明 系统采用基于概率权重的抽奖算法： 1. **概率计算**：根据奖品设置的概率百分比进行权重计算 2. **随机选择**：使用 mt_rand() 生成随机数，按权重范围选择中奖奖品 3. **库存控制**：实时检查奖品库存，库存不足时自动排除 4. **并发安全**：使用 Redis 锁防止并发抽奖导致的问题 ## 常见问题 ### 1. 如何设置奖品概率？ - 概率值为百分比，例如：0.01 表示 0.01% - 所有奖品概率之和建议不超过 100% - 未中奖奖品的概率可以设置为较大值作为保底 ### 2. 如何配置参与条件？ ```php // 购买指定商品 $condition = [ 'type' => 1, // 购买指定商品 'goods_ids' => [1, 2, 3], // 商品ID列表 'goods_rule' => 1, // 1=指定商品参与，2=指定商品不可参与 'reward_times' => 1, // 奖励抽奖次数 'is_repeatable' => 0 // 是否可重复获得 ]; // 单笔订单消费满额 $condition = [ 'type' => 2, // 单笔订单消费满额 'condition_value' => 199.00, // 满额金额 'reward_times' => 1, // 奖励抽奖次数 'is_repeatable' => 1 // 可重复获得 ]; ``` ### 3. 如何处理奖品发放？ - **自动发放**：优惠券、红包、兑换码可设置自动发放 - **手动发放**：实物奖品需要手动处理发货 - **发放状态**：通过 deliver_status 字段跟踪发放状态 ### 4. 性能优化建议 - 使用 Redis 缓存活动和奖品信息 - 对于大量用户的活动，考虑使用消息队列异步处理 - 定期清理过期的抽奖记录数据 ## 扩展功能 ### 1. 社交分享 可以扩展分享中奖结果到社交媒体的功能，增加活动传播度。 ### 2. 定时开奖 对于按时间开奖的活动，可以使用定时任务来处理开奖逻辑。 ### 3. 数据分析 基于抽奖数据进行用户行为分析，优化营销策略。 ### 4. 多渠道集成 支持微信小程序、APP、H5 等多个渠道的抽奖功能。