消费抽奖营销活动系统 - 接口使用说明

系统概述

本系统是一个基于消费行为的抽奖营销活动系统，支持多种奖品类型、灵活的参与条件和开奖方式。通过用户购买商品、充值等行为自动获得抽奖机会，提高用户参与度和复购率。

核心功能

多样化奖品：支持实物奖品、优惠券、红包、兑换码、商城奖品
灵活条件：支持购买指定商品、消费满额、充值满额等触发条件
三种开奖模式：即抽即中、按时间开奖、按人数开奖
精准投放：支持会员等级、会员标签的精准用户群体控制
完善统计：详细的抽奖记录和数据统计分析

数据表结构

系统包含以下核心数据表：

shop_lottery_activity - 活动主表
shop_lottery_prize - 奖品表
shop_lottery_condition - 参与条件表
shop_lottery_draw_record - 抽奖记录表
shop_lottery_win_record - 中奖记录表
shop_lottery_user_chance - 用户抽奖机会表
shop_lottery_statistics - 活动统计表

请先执行数据库建表脚本创建相关表结构。

API接口说明

基础接口路径

/api/lottery/

1. 获取活动列表

接口地址： GET /api/lottery/activityList

请求参数：

{
    "page": 1,        // 页码，默认1
    "limit": 10,      // 每页数量，默认10
    "status": 1       // 活动状态，默认1（进行中）
}

返回示例：

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

请求参数：

{
    "activity_id": 1   // 活动ID，必填
}

返回示例：

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

请求参数：

{
    "activity_id": 1   // 活动ID，必填
}

返回示例：

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

请求参数：

{
    "activity_id": 1   // 活动ID，必填
}

返回示例：

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

请求参数：

{
    "activity_id": 1,  // 活动ID，可选
    "page": 1,         // 页码，默认1
    "limit": 20        // 每页数量，默认20
}

返回示例：

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

请求参数：

{
    "page": 1,         // 页码，默认1
    "limit": 20        // 每页数量，默认20
}

7. 设置收货地址

接口地址： POST /api/lottery/setWinRecordAddress

请求参数：

{
    "win_record_id": 6789,
    "receiver_name": "张三",
    "receiver_mobile": "13800138000",
    "receiver_address": "北京市朝阳区某某小区1号楼101室"
}

8. 获取活动排行榜

接口地址： GET /api/lottery/getRanking

请求参数：

{
    "activity_id": 1,  // 活动ID，必填
    "page": 1,         // 页码，默认1
    "limit": 50        // 每页数量，默认50
}

核心服务使用

1. 抽奖服务 (LotteryService)

use app\common\Service\LotteryService;

// 执行抽奖
$result = LotteryService::drawLottery($activityId, $userId, $triggerType, $triggerOrderId, $triggerAmount);

// 获取用户抽奖机会
$chances = LotteryService::getUserChances($activityId, $userId);

2. 抽奖机会服务 (LotteryChanceService)

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 中注册钩子

// application/tags.php 或相应的钩子配置文件
return [
    // 订单支付完成钩子
    'order_paid' => [
        'app\\common\\behavior\\LotteryOrderHook'
    ],
    // 充值完成钩子
    'recharge_paid' => [
        'app\\common\\behavior\\LotteryOrderHook'
    ]
];

2. 在订单支付完成时触发钩子

// 在订单支付完成的地方调用
\think\Hook::listen('order_paid', ['order' => $orderInfo]);

// 在充值完成的地方调用
\think\Hook::listen('recharge_paid', ['recharge' => $rechargeInfo]);

抽奖算法说明

系统采用基于概率权重的抽奖算法：

概率计算：根据奖品设置的概率百分比进行权重计算
随机选择：使用 mt_rand() 生成随机数，按权重范围选择中奖奖品
库存控制：实时检查奖品库存，库存不足时自动排除
并发安全：使用 Redis 锁防止并发抽奖导致的问题

常见问题

1. 如何设置奖品概率？

概率值为百分比，例如：0.01 表示 0.01%
所有奖品概率之和建议不超过 100%
未中奖奖品的概率可以设置为较大值作为保底

2. 如何配置参与条件？

// 购买指定商品
$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 等多个渠道的抽奖功能。

消费抽奖系统接口使用说明.md 9.9 KB Riwayat Mentahan

消费抽奖营销活动系统 - 接口使用说明

系统概述

核心功能

数据表结构

API接口说明

基础接口路径

1. 获取活动列表

2. 获取活动详情

3. 执行抽奖

4. 获取用户抽奖机会

5. 获取抽奖记录

6. 获取中奖记录

7. 设置收货地址

8. 获取活动排行榜

核心服务使用

1. 抽奖服务 (LotteryService)

2. 抽奖机会服务 (LotteryChanceService)

订单钩子集成

1. 在 tags.php 中注册钩子

2. 在订单支付完成时触发钩子

抽奖算法说明

常见问题

1. 如何设置奖品概率？

2. 如何配置参与条件？

3. 如何处理奖品发放？

4. 性能优化建议

扩展功能

1. 社交分享

2. 定时开奖

3. 数据分析

4. 多渠道集成

消费抽奖系统接口使用说明.md 9.9 KB

Riwayat Mentahan