medical-mall/doc_mall/consumer/COUPON_SYSTEM_GUIDE.md

商城优惠券与红包系统设计文档 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，适配真实表结构字段。请重新执行以生成测试数据。