huangzhenbao/medical-mall

Fork 0

Files

cyh666666 b5c7947ad8 consumer模块完成度95%，优化安卓端界面和小程序测试3

2026-03-13 17:12:00 +08:00

9.6 KiB

Raw Blame History

商城推销模式功能需求文档

一、功能概述

本文档描述商城消费者端的推销模式功能，该功能为商家级别功能，即：

商家可自主开启/关闭自己店铺的推销模式
只有开启了推销模式的商家，其店铺订单才会显示"分享免单"按钮
会员等级系统为全局功能，适用于所有商家
经销点返利系统为商家级别功能，由商家自行配置

1.1 核心变更说明

功能模块	作用范围	说明
分享免单系统	商家级别	商家开启后，其订单才显示分享免单入口
会员等级系统	全局	所有用户统一等级体系
经销点返利系统	商家级别	商家自行创建和管理经销点
用户余额系统	商家级别	每个商家有独立的用户余额池

二、商家推销模式配置

2.1 商家推销设置表 ml_merchant_promotion_config

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID（关联ml_shops.merchant_id）
promotion_enabled	BOOLEAN	是否开启推销模式（默认false）
share_free_enabled	BOOLEAN	是否开启分享免单（默认false）
distribution_enabled	BOOLEAN	是否开启经销点返利（默认false）
required_count	INT	分享免单所需购买数（默认4）
reward_type	VARCHAR(20)	奖励类型：product_price-商品价格，fixed-固定金额
fixed_reward_amount	DECIMAL(10,2)	固定奖励金额（reward_type=fixed时使用）
created_at	TIMESTAMPTZ	创建时间
updated_at	TIMESTAMPTZ	更新时间

2.2 商家用户余额表 ml_merchant_user_balance

每个商家的用户余额独立计算，用户在不同商家有不同余额

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID
user_id	UUID	用户ID
balance	DECIMAL(10,2)	当前余额
frozen_balance	DECIMAL(10,2)	冻结余额
total_earned	DECIMAL(10,2)	累计获得
total_withdrawn	DECIMAL(10,2)	累计提现
updated_at	TIMESTAMPTZ	更新时间
UNIQUE(merchant_id, user_id)		联合唯一约束

三、分享免单系统

3.1 功能描述

用户购买商品后，可分享商品链接给其他用户（二级用户）。当二级用户通过分享链接购买该商品累计达到指定数量时，原用户可获得免单奖励。

重要变更：

只有开启了分享免单功能的商家，其订单才显示分享免单入口
分享免单所需购买数由商家自行设置（默认4人）
奖励金额可以是商品价格或固定金额

3.2 业务流程

商家开启推销模式 → 用户购买商品 → 订单详情显示"分享免单"按钮
                                      ↓
                              用户点击创建分享记录
                                      ↓
                              分享给好友B/C/D
                                      ↓
                              好友通过分享码购买
                                      ↓
                              累计购买数量达标
                                      ↓
                              用户获得免单奖励
                                      ↓
                              奖励存入该商家下的用户余额

3.3 数据库设计

3.3.1 分享记录表 ml_share_records

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID（新增）
user_id	UUID	分享用户ID
product_id	UUID	商品ID
order_id	UUID	关联订单ID
share_code	VARCHAR(20)	分享码（唯一）
required_count	INT	需要的购买数量
current_count	INT	当前已购买数量
status	INT	状态：0-进行中，1-已完成，2-已失效
reward_amount	DECIMAL(10,2)	奖励金额
created_at	TIMESTAMPTZ	创建时间
completed_at	TIMESTAMPTZ	完成时间

3.3.2 二级购买记录表 ml_secondary_purchases

字段名	类型	说明
id	UUID	主键
share_record_id	UUID	关联分享记录ID
buyer_id	UUID	购买用户ID
order_id	UUID	订单ID
quantity	INT	购买数量
created_at	TIMESTAMPTZ	创建时间

3.3.3 免单奖励记录表 ml_free_order_rewards

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID（新增）
user_id	UUID	获得奖励的用户ID
share_record_id	UUID	关联分享记录ID
amount	DECIMAL(10,2)	奖励金额
status	INT	状态：0-待处理，1-已发放，2-已清零
cleared_at	TIMESTAMPTZ	清零时间
cleared_by	UUID	清零操作人
created_at	TIMESTAMPTZ	创建时间

3.4 前端逻辑变更

3.4.1 订单列表页/订单详情页

// 判断是否显示分享免单按钮
async function checkShareFreeEnabled(merchantId: string): Promise<boolean> {
  const config = await supabaseService.getMerchantPromotionConfig(merchantId)
  return config?.promotion_enabled && config?.share_free_enabled
}

// 在订单卡片中
<view v-if="order.status >= 2 && order.status <= 4 && isShareFreeEnabled(order.merchant_id)" 
      class="share-free-row" @click="shareForFree(order)">
  <text>🎁 分享免单</text>
</view>

3.4.2 我的余额页

需要按商家分组显示余额
或显示总余额，点击查看各商家余额明细

四、会员等级系统

4.1 功能描述

会员等级系统为全局功能，用户等级在所有商家通用。用户可通过累计消费金额自动升级，或由商家手动设置等级。

4.2 等级设置（全局配置）

等级	名称	升级条件	折扣
0	普通会员	注册即可	无折扣
1	铜牌会员	累计消费500元	98折
2	银牌会员	累计消费2000元	95折
3	金牌会员	累计消费5000元	92折
4	钻石会员	累计消费10000元	88折
5	VIP会员	商家手动设置	85折

4.3 数据库设计

保持原有设计不变，会员等级为全局配置。

五、经销点返利系统

5.1 功能描述

商家可创建多个经销点，每个经销点有独立的推广码。经销点通过推广码产生的订单可获得返利。

重要变更：

经销点返利为商家级别功能
商家需先开启经销点功能才能使用

5.2 数据库设计

5.2.1 经销点表 ml_distribution_points

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID（新增）
name	VARCHAR(100)	经销点名称
contact_name	VARCHAR(50)	联系人
contact_phone	VARCHAR(20)	联系电话
invite_code	VARCHAR(20)	邀请码（唯一）
owner_id	UUID	负责人用户ID
status	INT	状态：0-禁用，1-启用
total_orders	INT	累计订单数
total_rebate	DECIMAL(10,2)	累计返利
balance	DECIMAL(10,2)	可提现余额
created_at	TIMESTAMPTZ	创建时间

六、余额变动记录表

6.1 ml_balance_records（按商家区分）

字段名	类型	说明
id	UUID	主键
merchant_id	UUID	商家ID（新增）
user_id	UUID	用户ID
type	VARCHAR(50)	类型
amount	DECIMAL(10,2)	变动金额
balance_before	DECIMAL(10,2)	变动前余额
balance_after	DECIMAL(10,2)	变动后余额
related_id	UUID	关联ID
description	VARCHAR(200)	描述
operator_id	UUID	操作人
created_at	TIMESTAMPTZ	创建时间

七、API 接口变更

7.1 新增接口

接口	方法	说明
/api/merchant/promotion-config	GET	获取商家推销配置
/api/merchant/user-balance	GET	获取用户在某商家的余额
/api/merchant/user-balance-list	GET	获取用户所有商家余额列表

7.2 修改接口

接口	变更说明
/api/share/create	新增merchant_id参数
/api/share/my-records	按merchant_id筛选
/api/balance/info	新增merchant_id参数

八、前端页面变更

8.1 消费者端

页面	变更说明
订单列表/详情	根据商家配置显示分享免单按钮
我的余额	按商家分组显示余额，或显示余额列表
我的分享	按商家筛选分享记录

8.2 商家端（新增）

页面	说明
推销模式设置	开启/关闭分享免单、经销点功能
用户余额管理	查看用户余额、清零操作
经销点管理	创建、编辑经销点

九、开发优先级

第一阶段

商家推销配置表（SQL）
修改用户余额表结构（按商家区分）
修改分享记录表结构（添加merchant_id）
前端：根据商家配置显示分享免单按钮

第二阶段

商家端推销模式设置页面
用户余额按商家分组显示
经销点返利系统

十、SQL变更清单

需要执行以下SQL变更：

新增商家推销配置表 ml_merchant_promotion_config
修改用户余额表 添加merchant_id字段，改为联合唯一约束
修改分享记录表 添加merchant_id字段
修改余额记录表 添加merchant_id字段
修改免单奖励表 添加merchant_id字段
修改经销点表 添加merchant_id字段

详细SQL语句见：promotion_system_tables_v2.sql

9.6 KiB Raw Blame History Unescape Escape