medical-mall/pages/mall/consumer/doc/推销模式功能需求文档.md

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

一、功能概述

本文档描述商城消费者端的推销模式功能，包含以下三大模块：

1. 分享免单系统 - 用户分享商品，达成条件后免单
2. 会员等级系统 - 用户等级享受不同优惠价格
3. 经销点返利系统 - 经销点销售返利

---

二、分享免单系统

2.1 功能描述

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

2.2 业务流程

用户A购买商品 → 生成分享链接 → 分享给用户B/C/D
                                    ↓
                            二级用户通过链接购买
                                    ↓
                            累计购买数量达标（4件）
                                    ↓
                            用户A获得免单奖励
                                    ↓
                            奖励金额存入余额
                                    ↓
                            商家微信返现后清零余额

2.3 数据库设计

2.3.1 分享记录表 ml_share_records

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

2.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	创建时间

2.3.3 免单奖励记录表 ml_free_order_rewards

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

2.4 API 接口

接口	方法	说明
/api/share/create	POST	创建分享记录，生成分享码
/api/share/info	GET	获取分享详情和进度
/api/share/validate	GET	验证分享码有效性
/api/share/my-records	GET	获取我的分享记录列表
/api/share/rewards	GET	获取我的免单奖励记录
/api/admin/clear-balance	POST	商家清零用户余额（后台）

2.5 前端页面

2.5.1 分享弹窗（订单详情页）

• 显示分享链接/二维码
• 显示当前进度（X/4）
• 分享按钮（微信好友、朋友圈）

2.5.2 我的分享页

• 分享记录列表
• 每条记录显示：商品信息、进度、状态
• 邀请好友按钮

2.5.3 我的余额页

• 余额显示
• 免单奖励记录
• 提现说明（联系商家微信）

---

三、会员等级系统

3.1 功能描述

商家可设置多个会员等级，每个等级对应不同的优惠折扣。用户可通过以下方式升级：

1. 商家手动设置等级
2. 累计消费金额自动升级

3.2 等级设置

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

3.3 数据库设计

3.3.1 会员等级配置表 ml_member_levels

字段名	类型	说明
id	INT	等级ID
name	VARCHAR(50)	等级名称
min_amount	DECIMAL(10,2)	升级最低消费金额
discount	DECIMAL(5,4)	折扣率（0.85表示85折）
icon	VARCHAR(200)	等级图标
description	TEXT	等级说明
sort_order	INT	排序
status	INT	状态：0-禁用，1-启用

3.3.2 用户会员信息扩展（ml_user_profiles 扩展字段）

字段名	类型	说明
member_level	INT	当前会员等级
total_spent	DECIMAL(10,2)	累计消费金额
level_updated_at	TIMESTAMPTZ	等级更新时间
manual_level	BOOLEAN	是否手动设置等级
manual_level_by	UUID	手动设置操作人

3.3.3 会员等级变更记录表 ml_member_level_logs

字段名	类型	说明
id	UUID	主键
user_id	UUID	用户ID
old_level	INT	原等级
new_level	INT	新等级
reason	VARCHAR(200)	变更原因
operator_id	UUID	操作人（自动则为空）
created_at	TIMESTAMPTZ	创建时间

3.4 API 接口

接口	方法	说明
/api/member/levels	GET	获取会员等级列表
/api/member/my-info	GET	获取我的会员信息
/api/member/upgrade-check	POST	检查并升级会员等级
/api/admin/set-member-level	POST	商家手动设置用户等级

3.5 前端页面

3.5.1 会员中心页

• 当前等级显示
• 等级进度条
• 等级权益说明
• 升级攻略

3.5.2 商品详情页

• 显示会员价
• 显示折扣信息

---

四、经销点返利系统

4.1 功能描述

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

4.2 返利规则

单数范围	返利金额/单
1-10单	2元/单
11-50单	3元/单
51-100单	4元/单
100单以上	5元/单

4.3 数据库设计

4.3.1 经销点表 ml_distribution_points

字段名	类型	说明
id	UUID	主键
name	VARCHAR(100)	经销点名称
contact_name	VARCHAR(50)	联系人
contact_phone	VARCHAR(20)	联系电话
address	VARCHAR(200)	地址
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	创建时间

4.3.2 经销点订单关联表 ml_distribution_orders

字段名	类型	说明
id	UUID	主键
distribution_id	UUID	经销点ID
order_id	UUID	订单ID
user_id	UUID	下单用户ID
order_amount	DECIMAL(10,2)	订单金额
rebate_amount	DECIMAL(10,2)	返利金额
status	INT	状态：0-待结算，1-已结算
settled_at	TIMESTAMPTZ	结算时间
created_at	TIMESTAMPTZ	创建时间

4.3.3 返利配置表 ml_rebate_config

字段名	类型	说明
id	UUID	主键
min_orders	INT	最小单数
max_orders	INT	最大单数
rebate_per_order	DECIMAL(10,2)	每单返利金额
status	INT	状态

4.3.4 返利提现记录表 ml_rebate_withdrawals

字段名	类型	说明
id	UUID	主键
distribution_id	UUID	经销点ID
amount	DECIMAL(10,2)	提现金额
status	INT	状态：0-待处理，1-已完成，2-已拒绝
handled_by	UUID	处理人
handled_at	TIMESTAMPTZ	处理时间
created_at	TIMESTAMPTZ	创建时间

4.4 API 接口

接口	方法	说明
/api/distribution/info	GET	获取经销点信息
/api/distribution/orders	GET	获取经销点订单列表
/api/distribution/rebate-summary	GET	获取返利统计
/api/distribution/withdraw	POST	申请提现
/api/admin/distributions	GET	获取经销点列表（后台）
/api/admin/create-distribution	POST	创建经销点（后台）
/api/admin/settle-rebate	POST	结算返利（后台）

4.5 前端页面

4.5.1 经销点中心页（经销点负责人）

• 经销点信息
• 今日/本月订单数
• 累计返利
• 可提现余额
• 申请提现按钮

4.5.2 经销点订单页

• 订单列表
• 筛选（日期、状态）
• 每单返利金额显示

---

五、用户余额系统

5.1 数据库设计

5.1.1 用户余额表 ml_user_balance

字段名	类型	说明
id	UUID	主键
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	更新时间

5.1.2 余额变动记录表 ml_balance_records

字段名	类型	说明
id	UUID	主键
user_id	UUID	用户ID
type	VARCHAR(50)	类型：free_order-免单，rebate-返利，withdraw-提现，clear-清零
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	创建时间

---

六、前端页面汇总

6.1 消费者端新增页面

页面	路径	说明
我的分享	/pages/mall/consumer/share/my-shares	分享记录列表
分享详情	/pages/mall/consumer/share/detail	分享进度详情
我的余额	/pages/mall/consumer/balance/index	余额和奖励记录
会员中心	/pages/mall/consumer/member/index	会员等级信息
会员权益	/pages/mall/consumer/member/benefits	等级权益说明

6.2 经销点端页面（可选独立入口）

页面	路径	说明
经销点中心	/pages/distribution/index	经销点首页
经销点订单	/pages/distribution/orders	订单列表
返利记录	/pages/distribution/rebates	返利记录
提现申请	/pages/distribution/withdraw	提现页面

---

七、开发优先级

第一阶段（核心功能）

1. 用户余额系统
2. 分享免单系统
3. 会员等级系统

第二阶段（扩展功能）

1. 经销点返利系统
2. 后台管理功能
3. 数据统计报表

---

八、注意事项

1. 安全性

   • 分享码唯一且不可预测
   • 防止刷单作弊（同一用户多次购买不计入）
   • 余额变动需有完整记录

2. 性能

   • 高频查询使用缓存
   • 大数据量分页处理

3. 合规性

   • 返利模式需符合当地法规
   • 用户协议需明确说明规则

4. 扩展性

   • 返利规则可配置
   • 会员等级可扩展
   • 支持多种分享渠道