297 lines
9.6 KiB
Markdown
297 lines
9.6 KiB
Markdown
# 商城推销模式功能需求文档
|
||
|
||
## 一、功能概述
|
||
|
||
本文档描述商城消费者端的推销模式功能，**该功能为商家级别功能**，即：
|
||
|
||
- **商家可自主开启/关闭**自己店铺的推销模式
|
||
- 只有**开启了推销模式的商家**，其店铺订单才会显示"分享免单"按钮
|
||
- **会员等级系统**为全局功能，适用于所有商家
|
||
- **经销点返利系统**为商家级别功能，由商家自行配置
|
||
|
||
### 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 订单列表页/订单详情页
|
||
|
||
```typescript
|
||
// 判断是否显示分享免单按钮
|
||
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 商家端（新增）
|
||
|
||
| 页面 | 说明 |
|
||
|------|------|
|
||
| 推销模式设置 | 开启/关闭分享免单、经销点功能 |
|
||
| 用户余额管理 | 查看用户余额、清零操作 |
|
||
| 经销点管理 | 创建、编辑经销点 |
|
||
|
||
---
|
||
|
||
## 九、开发优先级
|
||
|
||
### 第一阶段
|
||
1. 商家推销配置表（SQL）
|
||
2. 修改用户余额表结构（按商家区分）
|
||
3. 修改分享记录表结构（添加merchant_id）
|
||
4. 前端：根据商家配置显示分享免单按钮
|
||
|
||
### 第二阶段
|
||
1. 商家端推销模式设置页面
|
||
2. 用户余额按商家分组显示
|
||
3. 经销点返利系统
|
||
|
||
---
|
||
|
||
## 十、SQL变更清单
|
||
|
||
需要执行以下SQL变更：
|
||
|
||
1. **新增商家推销配置表** `ml_merchant_promotion_config`
|
||
2. **修改用户余额表** 添加merchant_id字段，改为联合唯一约束
|
||
3. **修改分享记录表** 添加merchant_id字段
|
||
4. **修改余额记录表** 添加merchant_id字段
|
||
5. **修改免单奖励表** 添加merchant_id字段
|
||
6. **修改经销点表** 添加merchant_id字段
|
||
|
||
详细SQL语句见：`promotion_system_tables_v2.sql`
|