# 抽奖盲盒系统API接口文档

## 1. 接口概览

### 基础信息
- **基础URL**: `https://api.example.com`
- **API版本**: `v1`
- **数据格式**: `JSON`
- **字符编码**: `UTF-8`
- **认证方式**: `JWT Token`

### 通用响应格式
```json
{
    "code": 200,
    "msg": "success",
    "data": {},
    "timestamp": 1640995200
}
```

### 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 2. 用户认证接口

### 2.1 发送验证码
```http
POST /api/user/sendCode
```

**请求参数:**
```json
{
    "phone": "13800138000",
    "type": 1
}
```

**参数说明:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | 手机号 |
| type | int | 是 | 类型：1-登录注册 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "验证码发送成功",
    "data": {
        "expire_time": 300
    }
}
```

### 2.2 用户登录/注册
```http
POST /api/user/login
```

**请求参数:**
```json
{
    "phone": "13800138000",
    "code": "123456",
    "openid": "wx_openid_123"
}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
        "user_info": {
            "id": 1001,
            "phone": "13800138000",
            "nickname": "用户昵称",
            "avatar": "头像URL",
            "money": "100.00",
            "integral": "50.00",
            "level": 1
        }
    }
}
```

### 2.3 获取用户信息
```http
GET /api/user/info
```

**请求头:**
```
Authorization: Bearer {token}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1001,
        "phone": "138****8000",
        "nickname": "用户昵称",
        "avatar": "头像URL",
        "money": "100.00",
        "integral": "50.00",
        "money2": "20.00",
        "level": 1,
        "draw_num": 5
    }
}
```

## 3. 商品相关接口

### 3.1 获取商品分类
```http
GET /api/goods/category
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "title": "手办模型",
            "sort": 1
        },
        {
            "id": 2,
            "title": "数码产品",
            "sort": 2
        }
    ]
}
```

### 3.2 获取商品列表
```http
GET /api/goods/list
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category_id | int | 否 | 分类ID |
| type | int | 否 | 商品类型 |
| page | int | 否 | 页码，默认1 |
| limit | int | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 1001,
                "title": "精美手办盲盒",
                "imgurl": "商品图片URL",
                "price": "29.90",
                "type": 1,
                "type_name": "一番赏",
                "stock": 100,
                "sale_stock": 50,
                "status": 1,
                "prize_num": 1,
                "show_price": "29.9元/抽"
            }
        ],
        "total": 100,
        "page": 1,
        "limit": 20
    }
}
```

### 3.3 获取商品详情
```http
GET /api/goods/detail/{id}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "id": 1001,
        "title": "精美手办盲盒",
        "imgurl": "商品封面图",
        "imgurl_detail": "商品详情图",
        "price": "29.90",
        "type": 1,
        "type_name": "一番赏",
        "stock": 100,
        "sale_stock": 50,
        "prize_num": 1,
        "goods_describe": "商品描述",
        "prize_list": [
            {
                "id": 2001,
                "title": "限定手办A",
                "imgurl": "奖品图片",
                "price": "299.00",
                "money": "150.00",
                "real_pro": "0.05000",
                "goods_type": 1,
                "prize_code": "A001"
            }
        ]
    }
}
```

### 3.4 获取商品奖品列表
```http
GET /api/goods/prizeList/{goods_id}
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| num | int | 否 | 第几套，默认0 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 2001,
            "title": "限定手办A",
            "imgurl": "奖品图片",
            "price": "299.00",
            "money": "150.00",
            "real_pro": "0.05000",
            "goods_type": 1,
            "stock": 10,
            "surplus_stock": 8,
            "prize_code": "A001",
            "rank": 1
        }
    ]
}
```

## 4. 订单相关接口

### 4.1 创建订单
```http
POST /api/order/create
```

**请求参数:**
```json
{
    "goods_id": 1001,
    "num": 0,
    "prize_num": 1,
    "coupon_id": 0,
    "use_money": "0.00",
    "use_integral": "0.00",
    "use_draw": 0
}
```

**参数说明:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| goods_id | int | 是 | 商品ID |
| num | int | 是 | 第几套 |
| prize_num | int | 是 | 抽奖数量 |
| coupon_id | int | 否 | 优惠券ID |
| use_money | decimal | 否 | 使用余额 |
| use_integral | decimal | 否 | 使用积分 |
| use_draw | int | 否 | 使用抽奖券 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "订单创建成功",
    "data": {
        "order_id": 10001,
        "order_num": "202401010001",
        "order_total": "29.90",
        "price": "29.90",
        "goods_info": {
            "id": 1001,
            "title": "精美手办盲盒",
            "imgurl": "商品图片"
        }
    }
}
```

### 4.2 获取支付参数
```http
POST /api/order/pay
```

**请求参数:**
```json
{
    "order_id": 10001,
    "pay_type": 1
}
```

**参数说明:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| order_id | int | 是 | 订单ID |
| pay_type | int | 是 | 支付方式：1-微信，2-支付宝 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "pay_params": {
            "appId": "wx123456789",
            "timeStamp": "1640995200",
            "nonceStr": "abc123",
            "package": "prepay_id=wx123456789",
            "signType": "RSA",
            "paySign": "signature"
        }
    }
}
```

### 4.3 获取订单列表
```http
GET /api/order/list
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | int | 否 | 订单状态：0-未支付，1-已支付 |
| page | int | 否 | 页码 |
| limit | int | 否 | 每页数量 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 10001,
                "order_num": "202401010001",
                "goods_title": "精美手办盲盒",
                "goods_imgurl": "商品图片",
                "order_total": "29.90",
                "price": "29.90",
                "prize_num": 1,
                "status": 1,
                "addtime": 1640995200,
                "pay_time": 1640995300
            }
        ],
        "total": 50,
        "page": 1,
        "limit": 20
    }
}
```

## 5. 抽奖相关接口

### 5.1 获取中奖记录
```http
GET /api/prize/list
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | int | 否 | 状态：0-待选择，1-回收，2-发货，3-集市 |
| page | int | 否 | 页码 |
| limit | int | 否 | 每页数量 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 20001,
                "order_id": 10001,
                "goodslist_title": "限定手办A",
                "goodslist_imgurl": "奖品图片",
                "goodslist_price": "299.00",
                "goodslist_money": "150.00",
                "goodslist_type": 1,
                "status": 0,
                "addtime": 1640995300,
                "prize_code": "A001",
                "luck_no": 1
            }
        ],
        "total": 20,
        "page": 1,
        "limit": 20
    }
}
```

### 5.2 选择奖品处理方式
```http
POST /api/prize/choose
```

**请求参数:**
```json
{
    "order_list_ids": [20001, 20002],
    "type": 1
}
```

**参数说明:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| order_list_ids | array | 是 | 中奖记录ID数组 |
| type | int | 是 | 处理方式：1-回收，2-发货，3-集市 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "recovery_num": "R202401010001",
        "total_money": "300.00"
    }
}
```

## 6. 集市相关接口

### 6.1 获取集市商品列表
```http
GET /api/market/list
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| keyword | string | 否 | 搜索关键词 |
| min_price | decimal | 否 | 最低价格 |
| max_price | decimal | 否 | 最高价格 |
| page | int | 否 | 页码 |
| limit | int | 否 | 每页数量 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 30001,
                "order_num": "M202401010001",
                "price": "280.00",
                "stock": 1,
                "status": 0,
                "addtime": 1640995400,
                "goods_info": [
                    {
                        "title": "限定手办A",
                        "imgurl": "奖品图片",
                        "price": "299.00"
                    }
                ]
            }
        ],
        "total": 100,
        "page": 1,
        "limit": 20
    }
}
```

### 6.2 发布集市商品
```http
POST /api/market/publish
```

**请求参数:**
```json
{
    "order_list_ids": [20001],
    "price": "280.00"
}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "发布成功",
    "data": {
        "market_id": 30001,
        "order_num": "M202401010001"
    }
}
```

### 6.3 购买集市商品
```http
POST /api/market/buy
```

**请求参数:**
```json
{
    "market_id": 30001,
    "pay_type": 1
}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "购买成功",
    "data": {
        "order_id": 40001,
        "pay_params": {
            "appId": "wx123456789",
            "timeStamp": "1640995200",
            "nonceStr": "abc123",
            "package": "prepay_id=wx123456789",
            "signType": "RSA",
            "paySign": "signature"
        }
    }
}
```

## 7. 财务相关接口

### 7.1 获取资金明细
```http
GET /api/finance/moneyLog
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | int | 否 | 类型：1-充值，2-消费，3-回收等 |
| page | int | 否 | 页码 |
| limit | int | 否 | 每页数量 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 50001,
                "change_money": "+150.00",
                "money": "250.00",
                "type": 4,
                "type_name": "背包回收",
                "content": "回收奖品获得",
                "addtime": 1640995500
            }
        ],
        "total": 50,
        "page": 1,
        "limit": 20
    }
}
```

### 7.2 获取积分明细
```http
GET /api/finance/integralLog
```

**响应格式同资金明细**

### 7.3 获取优惠券列表
```http
GET /api/finance/couponList
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | int | 否 | 状态：0-未使用，1-已使用，2-已过期 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 60001,
            "title": "新人专享券",
            "price": "5.00",
            "man_price": "30.00",
            "end_time": 1641081600,
            "status": 0,
            "state": 0
        }
    ]
}
```

## 8. 发货相关接口

### 8.1 创建发货订单
```http
POST /api/delivery/create
```

**请求参数:**
```json
{
    "order_list_ids": [20001, 20002],
    "name": "张三",
    "mobile": "13800138000",
    "address": "北京市朝阳区xxx街道xxx号",
    "message": "请小心轻放"
}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "发货订单创建成功",
    "data": {
        "send_id": 70001,
        "send_num": "S202401010001",
        "freight": "10.00",
        "total_price": "10.00"
    }
}
```

### 8.2 获取发货订单列表
```http
GET /api/delivery/list
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "list": [
            {
                "id": 70001,
                "send_num": "S202401010001",
                "freight": "10.00",
                "status": 1,
                "count": 2,
                "name": "张三",
                "mobile": "138****8000",
                "address": "北京市朝阳区xxx街道xxx号",
                "courier_number": "SF1234567890",
                "courier_name": "顺丰速运",
                "addtime": 1640995600,
                "send_time": 1640995700
            }
        ]
    }
}
```

### 8.3 获取物流信息
```http
GET /api/delivery/track/{send_id}
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "courier_number": "SF1234567890",
        "courier_name": "顺丰速运",
        "delivery_status": 3,
        "delivery_list": [
            {
                "time": "2024-01-01 10:00:00",
                "context": "快件已发出"
            },
            {
                "time": "2024-01-01 15:30:00",
                "context": "快件已到达中转站"
            }
        ]
    }
}
```

## 9. 系统配置接口

### 9.1 获取系统配置
```http
GET /api/system/config
```

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": {
        "app_name": "抽奖盲盒",
        "app_version": "1.0.0",
        "customer_service": "400-123-4567",
        "agreement_url": "https://example.com/agreement",
        "privacy_url": "https://example.com/privacy"
    }
}
```

### 9.2 获取轮播图
```http
GET /api/system/banner
```

**请求参数:**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | int | 否 | 类型：1-首页轮播，2-抽卡机轮播 |

**响应示例:**
```json
{
    "code": 200,
    "msg": "success",
    "data": [
        {
            "id": 1,
            "imgurl": "轮播图URL",
            "url": "跳转链接",
            "ttype": 2,
            "goods_id": 1001
        }
    ]
}
```

## 10. 错误码说明

| 错误码 | 说明 |
|--------|------|
| 10001 | 参数错误 |
| 10002 | 用户不存在 |
| 10003 | 验证码错误 |
| 10004 | 验证码已过期 |
| 20001 | 商品不存在 |
| 20002 | 商品已下架 |
| 20003 | 商品库存不足 |
| 30001 | 订单不存在 |
| 30002 | 订单状态错误 |
| 30003 | 余额不足 |
| 40001 | 支付失败 |
| 40002 | 支付超时 |
| 50001 | 抽奖失败 |
| 50002 | 奖品库存不足 |

## 11. 接口调用示例

### JavaScript示例
```javascript
// 用户登录
const login = async (phone, code) => {
    const response = await fetch('/api/user/login', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            phone: phone,
            code: code
        })
    });
    
    const result = await response.json();
    if (result.code === 200) {
        localStorage.setItem('token', result.data.token);
        return result.data;
    } else {
        throw new Error(result.msg);
    }
};

// 获取商品列表
const getGoodsList = async (params = {}) => {
    const query = new URLSearchParams(params).toString();
    const response = await fetch(`/api/goods/list?${query}`, {
        headers: {
            'Authorization': `Bearer ${localStorage.getItem('token')}`
        }
    });
    
    return await response.json();
};

// 创建订单
const createOrder = async (orderData) => {
    const response = await fetch('/api/order/create', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'Authorization': `Bearer ${localStorage.getItem('token')}`
        },
        body: JSON.stringify(orderData)
    });
    
    return await response.json();
};
```

### PHP示例
```php
<?php
class ApiClient {
    private $baseUrl;
    private $token;
    
    public function __construct($baseUrl) {
        $this->baseUrl = $baseUrl;
    }
    
    public function setToken($token) {
        $this->token = $token;
    }
    
    public function request($method, $endpoint, $data = null) {
        $url = $this->baseUrl . $endpoint;
        $headers = ['Content-Type: application/json'];
        
        if ($this->token) {
            $headers[] = 'Authorization: Bearer ' . $this->token;
        }
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if ($data) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
        }
        
        $response = curl_exec($ch);
        curl_close($ch);
        
        return json_decode($response, true);
    }
    
    public function login($phone, $code) {
        return $this->request('POST', '/api/user/login', [
            'phone' => $phone,
            'code' => $code
        ]);
    }
    
    public function getGoodsList($params = []) {
        $query = http_build_query($params);
        return $this->request('GET', '/api/goods/list?' . $query);
    }
}

// 使用示例
$client = new ApiClient('https://api.example.com');
$result = $client->login('13800138000', '123456');

if ($result['code'] === 200) {
    $client->setToken($result['data']['token']);
    $goodsList = $client->getGoodsList(['type' => 1, 'page' => 1]);
}
?>
```

这份API文档涵盖了抽奖盲盒系统的主要功能接口，包括用户认证、商品管理、订单处理、抽奖机制、集市交易、财务管理等核心业务模块。每个接口都提供了详细的参数说明和响应示例，便于前端开发和第三方集成。