# 优惠券功能使用指南

## 功能概述

本系统实现了完整的优惠券功能，包括优惠券模板管理、用户优惠券管理、优惠券使用、统计分析等功能。

## 核心功能

### 1. 优惠券模板管理
- 创建优惠券模板（满减券、折扣券、免费券）
- 设置发放数量限制和个人领取限制
- 配置适用范围（全部商品、指定商品、指定分类）
- 设置有效期（领取后生效或固定时间）

### 2. 用户优惠券管理
- 用户主动领取优惠券
- 系统自动发放优惠券
- 优惠券使用和退还
- 优惠券状态管理（未使用、已使用、已过期）

### 3. 订单优惠券功能
- 获取订单可用优惠券
- 计算优惠券优惠金额
- 验证优惠券适用性
- 推荐最优优惠券组合

### 4. 业务场景支持
- 新用户注册赠送
- 生日优惠券发放
- 消费返券
- 活动批量发放

## 数据库表结构

### 优惠券模板表 (shop_coupon)
```sql
- id: 主键
- name: 优惠券名称
- description: 优惠券描述
- type: 优惠券类型(10满减券 20折扣券 30免费券)
- reduce_price: 满减金额
- discount: 折扣率(0-100)
- min_price: 最低消费金额
- total_count: 发放总数量(-1无限制)
- issued_count: 已发放数量
- limit_per_user: 每人限领数量(-1无限制)
- expire_type: 到期类型(10领取后生效 20固定时间)
- expire_day: 有效天数
- start_time: 有效期开始时间
- end_time: 有效期结束时间
- apply_range: 适用范围(10全部商品 20指定商品 30指定分类)
- apply_range_config: 适用范围配置(JSON格式)
- enabled: 是否启用
- status: 状态
```

### 用户优惠券表 (shop_user_coupon)
```sql
- id: 主键
- coupon_id: 优惠券模板ID
- user_id: 用户ID
- name: 优惠券名称
- type: 优惠券类型
- reduce_price: 满减金额
- discount: 折扣率
- min_price: 最低消费金额
- start_time: 有效期开始时间
- end_time: 有效期结束时间
- status: 使用状态(0未使用 1已使用 2已过期)
- use_time: 使用时间
- order_id: 使用订单ID
- order_no: 使用订单号
- obtain_type: 获取方式(10主动领取 20系统发放 30活动赠送)
- obtain_source: 获取来源描述
```

## API接口说明

### 优惠券模板管理
- `GET /api/shop/shop-coupon/page` - 分页查询优惠券模板
- `POST /api/shop/shop-coupon` - 创建优惠券模板
- `PUT /api/shop/shop-coupon` - 更新优惠券模板
- `DELETE /api/shop/shop-coupon/{id}` - 删除优惠券模板

### 用户优惠券管理
- `GET /api/shop/user-coupon/my` - 获取当前用户优惠券
- `GET /api/shop/user-coupon/my/available` - 获取可用优惠券
- `POST /api/shop/user-coupon/receive/{couponId}` - 领取优惠券
- `PUT /api/shop/user-coupon/use` - 使用优惠券
- `PUT /api/shop/user-coupon/return/{orderId}` - 退还优惠券

### 优惠券业务功能
- `POST /api/shop/coupon-business/available-for-order` - 获取订单可用优惠券
- `POST /api/shop/coupon-business/calculate-order-amount` - 计算使用优惠券后的订单金额
- `POST /api/shop/coupon-business/recommend-best-combination` - 推荐最优优惠券组合
- `POST /api/shop/coupon-business/batch-issue-activity` - 批量发放活动优惠券

## 使用示例

### 1. 创建优惠券模板
```json
{
  "name": "新用户专享券",
  "description": "新用户注册即可领取",
  "type": 10,
  "reducePrice": 20.00,
  "minPrice": 100.00,
  "totalCount": 1000,
  "limitPerUser": 1,
  "expireType": 10,
  "expireDay": 30,
  "applyRange": 10,
  "enabled": 1
}
```

### 2. 用户领取优惠券
```javascript
// 前端调用
POST /api/shop/user-coupon/receive/1
```

### 3. 订单使用优惠券
```json
{
  "goodsItems": [
    {
      "goodsId": 1,
      "categoryId": 1,
      "price": 150.00,
      "quantity": 1
    }
  ],
  "totalAmount": 150.00
}
```

### 4. 计算优惠金额
```javascript
// 获取可用优惠券
POST /api/shop/coupon-business/available-for-order

// 计算优惠金额
POST /api/shop/coupon-business/calculate-order-amount?userCouponId=1
```

## 定时任务

系统包含以下定时任务：

1. **过期优惠券处理** - 每天凌晨2点执行
   - 自动更新过期优惠券状态

2. **优惠券到期提醒** - 每天上午10点执行
   - 提醒用户即将过期的优惠券

3. **生日优惠券发放** - 每天凌晨1点执行
   - 为当天生日的用户发放生日优惠券

## 配置说明

### 优惠券类型配置
- `TYPE_REDUCE = 10` - 满减券
- `TYPE_DISCOUNT = 20` - 折扣券  
- `TYPE_FREE = 30` - 免费券

### 适用范围配置
- `APPLY_ALL = 10` - 全部商品
- `APPLY_GOODS = 20` - 指定商品
- `APPLY_CATEGORY = 30` - 指定分类

### 获取方式配置
- `OBTAIN_RECEIVE = 10` - 主动领取
- `OBTAIN_SYSTEM = 20` - 系统发放
- `OBTAIN_ACTIVITY = 30` - 活动赠送

## 注意事项

1. **数据一致性**：优惠券使用和退还操作需要保证数据一致性
2. **并发控制**：优惠券领取需要考虑并发情况，避免超发
3. **性能优化**：大量用户时需要考虑查询性能优化
4. **业务规则**：根据实际业务需求调整优惠券规则和限制

## 扩展功能

可以根据业务需要扩展以下功能：
- 优惠券分享功能
- 优惠券兑换码功能
- 优惠券组合使用
- 优惠券使用统计分析
- 优惠券营销活动管理