# 微信卡券服务

## 功能介绍

微信卡券服务提供了创建、管理和使用微信卡券的功能，包括会员卡、优惠券、礼品卡等多种类型的卡券。

## 核心方法

### WechatCardService

#### createCard(array $card)

创建卡券。

**参数：**
- `$card` - 卡券配置数组

**返回值：** 卡券创建结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 创建会员卡
$card = [
    'card_type' => 'MEMBER_CARD',
    'member_card' => [
        'base_info' => [
            'logo_url' => 'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0',
            'brand_name' => '测试会员卡',
            'code_type' => 'CODE_TYPE_TEXT',
            'title' => '会员卡',
            'sub_title' => '副标题',
            'color' => 'Color010',
            'notice' => '使用时向服务员出示此券',
            'service_phone' => '020-88888888',
            'description' => '此会员卡仅限在指定门店使用',
            'date_info' => [
                'type' => 'DATE_TYPE_PERMANENT'
            ],
            'sku' => [
                'quantity' => 5000
            ],
            'get_limit' => 3,
            'use_custom_code' => false,
            'bind_openid' => false,
            'can_share' => true,
            'can_give_friend' => true
        ],
        'advanced_info' => [
            'use_condition' => [
                'accept_category' => '',
                'reject_category' => '',
                'can_use_with_other_discount' => true
            ],
            'abstract' => [
                'abstract' => '会员专享优惠',
                'icon_url_list' => [
                    'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0'
                ]
            ],
            'text_image_list' => [
                [
                    'image_url' => 'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0',
                    'text' => '使用说明'
                ]
            ],
            'time_limit' => [],
            'business_service' => [
                'BIZ_SERVICE_FREE_WIFI',
                'BIZ_SERVICE_PARKING',
                'BIZ_SERVICE_VALET_PARKING',
                'BIZ_SERVICE_DELIVERY'
            ]
        ],
        'supply_bonus' => true,
        'supply_balance' => true,
        'prerogative' => '会员专享',
        'auto_activate' => true,
        'auto_activate_after_pay' => false,
        'activate_url' => '',
        'member_url_name' => '会员中心',
        'member_url' => 'http://www.example.com/member',
        'bonus_url_name' => '积分商城',
        'bonus_url' => 'http://www.example.com/bonus',
        'balance_url_name' => '余额查询',
        'balance_url' => 'http://www.example.com/balance',
        'custom_field1_name' => '等级',
        'custom_field1_value' => '普通会员',
        'custom_field2_name' => '积分',
        'custom_field2_value' => '0'
    ]
];

$result = Wechat::officialAccount()->card->createCard($card);
print_r($result);
```

#### getCardInfo(string $cardId)

获取卡券详情。

**参数：**
- `$cardId` - 卡券 ID

**返回值：** 卡券详情

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 获取卡券详情
$cardInfo = Wechat::officialAccount()->card->getCardInfo('CARD_ID');
print_r($cardInfo);
```

#### updateCard(array $card)

更新卡券。

**参数：**
- `$card` - 卡券更新配置数组

**返回值：** 更新结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 更新卡券
$card = [
    'card_id' => 'CARD_ID',
    'member_card' => [
        'base_info' => [
            'title' => '更新后的会员卡',
            'sub_title' => '更新后的副标题'
        ]
    ]
];

$result = Wechat::officialAccount()->card->updateCard($card);
print_r($result);
```

#### deleteCard(string $cardId)

删除卡券。

**参数：**
- `$cardId` - 卡券 ID

**返回值：** 删除结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 删除卡券
$result = Wechat::officialAccount()->card->deleteCard('CARD_ID');
print_r($result);
```

#### createQrcode(array $params)

创建卡券二维码。

**参数：**
- `$params` - 二维码配置数组

**返回值：** 二维码创建结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 创建卡券二维码
$params = [
    'action_name' => 'QR_CARD',
    'action_info' => [
        'card' => [
            'card_id' => 'CARD_ID',
            'is_unique_code' => false,
            'outer_id' => 1
        ]
    ],
    'expire_seconds' => 1800
];

$result = Wechat::officialAccount()->card->createQrcode($params);
print_r($result);
```

#### activateCard(string $cardId, string $code, array $params = [])

激活卡券。

**参数：**
- `$cardId` - 卡券 ID
- `$code` - 卡券 code
- `$params` - 激活参数

**返回值：** 激活结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 激活卡券
$result = Wechat::officialAccount()->card->activateCard('CARD_ID', 'CODE');
print_r($result);
```

#### setTestWhitelist(array $openids)

设置测试白名单。

**参数：**
- `$openids` - 测试用户的 OpenID 数组

**返回值：** 设置结果

**示例：**
```php
use Kylin\Wechat\Facades\Wechat;

// 设置测试白名单
$result = Wechat::officialAccount()->card->setTestWhitelist(['o4HhH5tZ-xxxxx']);
print_r($result);
```

## 实际应用场景

### 1. 创建优惠券

```php
use Kylin\Wechat\Facades\Wechat;

// 创建优惠券
$card = [
    'card_type' => 'GENERAL_COUPON',
    'general_coupon' => [
        'base_info' => [
            'logo_url' => 'http://mmbiz.qpic.cn/mmbiz/iaL1LJM1mF9aRKPZJkmG8xXhiaHqkKSVMMWeN3hLut7X7hicFNjakmxibMLGWpXrEXB33367o7zHN0CwngnQY7zb7g/0',
            'brand_name' => '测试优惠券',
            'code_type' => 'CODE_TYPE_TEXT',
            'title' => '满100减20',
            'sub_title' => '限时优惠',
            'color' => 'Color010',
            'notice' => '使用时向服务员出示此券',
            'service_phone' => '020-88888888',
            'description' => '满100元减20元，仅限在指定门店使用',
            'date_info' => [
                'type' => 'DATE_TYPE_FIX_TIME_RANGE',
                'begin_timestamp' => time(),
                'end_timestamp' => time() + 7 * 24 * 3600
            ],
            'sku' => [
                'quantity' => 1000
            ],
            'get_limit' => 1,
            'use_custom_code' => false,
            'bind_openid' => false,
            'can_share' => true,
            'can_give_friend' => true
        ],
        'default_detail' => '满100元减20元'
    ]
];

$result = Wechat::officialAccount()->card->createCard($card);
```

### 2. 批量发放卡券

```php
use Kylin\Wechat\Facades\Wechat;

// 批量发放卡券
$params = [
    'card_id' => 'CARD_ID',
    'openid_list' => ['o4HhH5tZ-xxxxx', 'o4HhH5tZ-yyyyy']
];

$result = Wechat::officialAccount()->card->batchSendCard($params);
print_r($result);
```
