sync: 开发文档 | 原因: 开发文档更新
This commit is contained in:
卡若
157
开发文档/9、手册/全站捆绑分销体系-SCALE.md
Normal file
157
开发文档/9、手册/全站捆绑分销体系-SCALE.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# 全站捆绑分销体系 · SCALE（可复用规格）
|
||||
|
||||
> **版本**：1.0
|
||||
> **来源**：一场soul的创业实验-永平 实战提炼
|
||||
> **用途**：作为全站消费捆绑 + 分销机制的可复用规格，可套用到其他网站、小程序、付费内容项目
|
||||
|
||||
---
|
||||
|
||||
## 一、核心理念
|
||||
|
||||
**全站捆绑** = 用户通过谁的分享链接进入，即与谁建立 30 天有效期的「推荐关系」，该关系覆盖全站所有消费（章节、全书、找伙伴、会员等）。
|
||||
|
||||
**分销体系** = 被推荐人支付成功 → 推荐人获得佣金（默认 90%）→ 支持提现。
|
||||
|
||||
---
|
||||
|
||||
## 二、核心规则（30 天捆绑）
|
||||
|
||||
| 规则 | 说明 |
|
||||
|:---|:---|
|
||||
| **动态绑定** | 用户 B 点击谁的分享链接，立即绑定谁（无条件切换） |
|
||||
| **佣金归属** | B 购买时，佣金给当前推荐人（最新绑定的那个人） |
|
||||
| **30 天有效期** | 绑定日起 30 天内有效，可续期（同一推荐人再次点击则刷新 30 天） |
|
||||
| **自动解绑** | 绑定 30 天内，若 B 既没点击其他链接，也没有任何购买 → 自动解绑 |
|
||||
|
||||
### 时间线示例
|
||||
|
||||
```
|
||||
Day 0: A 推荐 B → B 注册 → B 绑定 A（30 天有效期）
|
||||
Day 5: B 点击 C 的链接 → B 立即切换绑定 C（重新开始 30 天有效期）
|
||||
Day 10: B 购买 → 佣金给 C（当前推荐人）
|
||||
Day 35: 绑定 C 的 30 天到期，若期间无购买 → 自动解绑
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、数据库设计（最小可复用）
|
||||
|
||||
### 3.1 referral_bindings（推荐绑定表）
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| id | VARCHAR(64) | 主键 |
|
||||
| referee_id | VARCHAR(64) | 被推荐人（买家） |
|
||||
| referrer_id | VARCHAR(64) | 推荐人（拿佣金的人） |
|
||||
| referral_code | VARCHAR(20) | 推荐码 |
|
||||
| status | ENUM | active / cancelled / expired |
|
||||
| binding_date | TIMESTAMP | 最后一次绑定时间 |
|
||||
| expiry_date | DATETIME | 过期时间（30 天后） |
|
||||
| last_purchase_date | DATETIME | 最后一次购买时间 |
|
||||
| purchase_count | INT | 购买次数 |
|
||||
| total_commission | DECIMAL(10,2) | 累计佣金 |
|
||||
|
||||
### 3.2 users（需扩展字段）
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| referral_code | 自己的邀请码 |
|
||||
| referred_by | 可选，首次推荐人 |
|
||||
| pending_earnings | 待结算佣金 |
|
||||
| earnings | 已结算佣金 |
|
||||
|
||||
### 3.3 orders（需扩展字段）
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| referrer_id | 下单时的推荐人 user_id |
|
||||
| referral_code | 下单时使用的邀请码（对账/展示） |
|
||||
|
||||
### 3.4 system_config（配置）
|
||||
|
||||
- `config_key = 'referral_config'`
|
||||
- `distributorShare`：推广者分成比例（默认 90）
|
||||
- `bindingDays`：绑定有效期天数（默认 30）
|
||||
- `minWithdrawAmount`：最小提现金额（默认 10 元）
|
||||
|
||||
---
|
||||
|
||||
## 四、API 逻辑（关键接口）
|
||||
|
||||
### 4.1 绑定接口 `POST /api/referral/bind`
|
||||
|
||||
- **入参**：userId（被推荐人）, referralCode
|
||||
- **逻辑**：
|
||||
- 同一推荐人 → 续期（刷新 30 天）
|
||||
- 不同推荐人 → 旧绑定 status=cancelled，新绑定 active，expiry=NOW+30 天
|
||||
|
||||
### 4.2 下单时定推荐人（创建订单前）
|
||||
|
||||
1. 先查 `referral_bindings`（referee_id=买家，status=active，expiry_date>NOW）
|
||||
2. 无绑定则用请求体 `referralCode` 查 users 得 referrer_id
|
||||
3. 写入 `orders.referrer_id`、`orders.referral_code`
|
||||
|
||||
### 4.3 支付成功回调（分佣）
|
||||
|
||||
1. 查 `referral_bindings`（referee_id=买家，status=active）
|
||||
2. 取 referrer_id，佣金 = 订单金额 × distributorShare / 100
|
||||
3. 更新 `referral_bindings`：purchase_count++，total_commission+=佣金，last_purchase_date=NOW
|
||||
4. 更新 `users`：referrer 的 pending_earnings += 佣金
|
||||
5. **不**将 binding 改为 converted，保持 active，允许多次购买分佣
|
||||
|
||||
### 4.4 自动解绑定时任务（每天 02:00）
|
||||
|
||||
```sql
|
||||
UPDATE referral_bindings
|
||||
SET status = 'expired'
|
||||
WHERE status = 'active'
|
||||
AND expiry_date < NOW()
|
||||
AND purchase_count = 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、概念区分（避免混乱）
|
||||
|
||||
| 概念 | 含义 | 存储 | 用途 |
|
||||
|------|------|------|------|
|
||||
| **邀请码** | 一串码，如 SOULABC123 | users.referral_code | 链接 ref=邀请码，解析出推荐人 |
|
||||
| **推荐人** | 拿佣金的人 | referrer_id（用户ID） | 分佣、订单归属、统计 |
|
||||
| **绑定表** | 权威的「谁推荐了谁」 | referral_bindings | 分佣只看此表 |
|
||||
|
||||
**优先级**：绑定表 > 邀请码兜底。订单 referrer_id 只做展示/对账，不参与分佣计算。
|
||||
|
||||
---
|
||||
|
||||
## 六、提现流程（配套）
|
||||
|
||||
- 用户：可提现 = 累计佣金 − 已提现 − 待审核
|
||||
- 申请：POST /api/miniprogram/withdraw → status=pending
|
||||
- 管理端：通过 → 调微信商家转账 → status=processing
|
||||
- 微信回调：成功 → status=success；失败 → status=failed
|
||||
|
||||
---
|
||||
|
||||
## 七、复用 checklist（套用到新项目）
|
||||
|
||||
- [ ] 建表：referral_bindings、users 扩展、orders 扩展、withdrawals
|
||||
- [ ] 配置：referral_config（分成比例、绑定天数、最低提现）
|
||||
- [ ] 绑定接口：/api/referral/bind（动态切换 + 30 天）
|
||||
- [ ] 下单逻辑：写 orders.referrer_id、referral_code
|
||||
- [ ] 支付回调：查绑定 → 分佣 → 累加 purchase_count
|
||||
- [ ] 定时任务：每天解绑 purchase_count=0 且过期的记录
|
||||
- [ ] 前端：分享链接带 ref=邀请码，登录后调 bind
|
||||
- [ ] 提现：用户申请 → 管理审核 → 微信打款
|
||||
|
||||
---
|
||||
|
||||
## 八、相关文档（本项目内）
|
||||
|
||||
- [新分销逻辑设计方案](../8、部署/新分销逻辑设计方案.md)
|
||||
- [邀请码分销规则说明](../8、部署/邀请码分销规则说明.md)
|
||||
- [分销与绑定流程图](../8、部署/分销与绑定流程图.md)
|
||||
- [分销提现流程图](../8、部署/分销提现流程图.md)
|
||||
|
||||
---
|
||||
|
||||
*本 SCALE 可供任何有「全站消费 + 分销」需求的网站/小程序复用。*
|
||||
Reference in New Issue
Block a user