diff --git a/开发文档/9、手册/全站捆绑分销体系-SCALE.md b/开发文档/9、手册/全站捆绑分销体系-SCALE.md new file mode 100644 index 00000000..cc792c1a --- /dev/null +++ b/开发文档/9、手册/全站捆绑分销体系-SCALE.md @@ -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 可供任何有「全站消费 + 分销」需求的网站/小程序复用。*