5.7 KiB
5.7 KiB
全站捆绑分销体系 · 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 下单时定推荐人（创建订单前）
- 先查
referral_bindings（referee_id=买家，status=active，expiry_date>NOW） - 无绑定则用请求体
referralCode查 users 得 referrer_id - 写入
orders.referrer_id、orders.referral_code
4.3 支付成功回调（分佣）
- 查
referral_bindings（referee_id=买家，status=active） - 取 referrer_id，佣金 = 订单金额 × distributorShare / 100
- 更新
referral_bindings：purchase_count++，total_commission+=佣金，last_purchase_date=NOW - 更新
users：referrer 的 pending_earnings += 佣金 - 不将 binding 改为 converted，保持 active，允许多次购买分佣
4.4 自动解绑定时任务（每天 02:00）
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
- 提现：用户申请 → 管理审核 → 微信打款
八、相关文档（本项目内）
本 SCALE 可供任何有「全站消费 + 分销」需求的网站/小程序复用。