并入后台管理端（vue）和小程序端的代码(template-10550)

2025-08-08 23:04:17 +08:00
parent a0f4fcc03f
commit b0f9eaefa1
1452 changed files with 241138 additions and 0 deletions
--- a/docs/COUPON_FEATURE_GUIDE.md
+++ b/docs/COUPON_FEATURE_GUIDE.md
@@ -0,0 +1,191 @@
+# 优惠券功能使用指南
+
+## 功能概述
+
+本系统实现了完整的优惠券功能，包括优惠券模板管理、用户优惠券管理、优惠券使用、统计分析等功能。
+
+## 核心功能
+
+### 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. **业务规则**：根据实际业务需求调整优惠券规则和限制
+
+## 扩展功能
+
+可以根据业务需要扩展以下功能：
+- 优惠券分享功能
+- 优惠券兑换码功能
+- 优惠券组合使用
+- 优惠券使用统计分析
+- 优惠券营销活动管理