# 商城优惠券与红包系统设计文档 v1.1

## 1. 系统概述
本系统旨在为消费者提供多种形式的优惠激励，包括店铺优惠券、商品专属券、平台通用券以及现金红包。
核心流程包含：优惠配置(后台) -> 用户领取(前台) -> 下单核销(结算) -> 状态流转。

## 2. 优惠券分类 (Coupon Types)

### 2.1 优惠形式 (`coupon_type`)
1.  **满减券 (Full Reduction)**: `coupon_type=1`, `discount_type=1`. 例如：满 100 减 10。
2.  **折扣券 (Discount)**: `coupon_type=2`, `discount_type=2`. 例如：满 100 打 9 折。
3.  **红包 (Red Packet)**: `coupon_type=1` (或3), `discount_type=1`, `min_order_amount=0`.

### 2.2 适用范围 (Derived from Data)
1.  **店铺券**: `merchant_id` 不为空, `applicable_products` 为空。
2.  **商品券**: `merchant_id` 不为空, `applicable_products` 包含特定商品ID。
3.  **平台券**: `merchant_id` 为空。

## 3. 数据库设计 (Database Schema)

### 3.1 优惠券模板表 (`ml_coupon_templates`)
定义优惠券的规则。
- `id`: UUID (Primary Key)
- `merchant_id`: 商户ID (空则为平台券)
- `name`: 优惠券名称
- `coupon_type`: INTEGER (1:满减, 2:折扣, 3:免运费)
- `discount_type`: INTEGER (1:固定金额, 2:百分比)
- `discount_value`: DECIMAL (减免金额 或 折扣率如0.9)
- `min_order_amount`: DECIMAL (最低消费门槛, 0为无门槛)
- `total_quantity`: INTEGER (发行总量)
- `per_user_limit`: INTEGER (每人限领)
- `applicable_products`: JSONB (适用商品列表)
- `start_time` / `end_time`: 领取有效期
- `status`: INTEGER (1:正常)

### 3.2 用户优惠券表 (`ml_user_coupons`)
记录用户领取的优惠券实例。
- `id`: UUID
- `user_id`: 用户ID
- `template_id`: 关联模板
- `coupon_code`: 唯一码
- `status`: 1-未使用, 2-已使用, 3-已过期
- `received_at`: 领取时间
- `expire_at`: 过期时间
- `order_id`: 关联订单ID

## 4. 业务流程与开发指南

### 4.1 数据展示适配
前端 `getUserCoupons` 方法获取数据后，需根据 `coupon_type` 和 `discount_type` 做展示处理：
- 若 `discount_type == 1`: 展示 `¥{discount_value}`。
- 若 `discount_type == 2`: 展示 `{discount_value * 10}折` (若存0.9) 或根据实际存储值适配。

### 4.2 SQL 初始化
已提供修正后的 `doc_mall/consumer/sql/06_setup_coupons.sql`，适配真实表结构字段。请重新执行以生成测试数据。