409 lines
11 KiB
Markdown
409 lines
11 KiB
Markdown
# 新分销逻辑设计方案
|
||
|
||
## 📌 业务需求
|
||
|
||
### 核心规则
|
||
1. **动态绑定**：用户B点击谁的分享链接，立即绑定谁（无条件切换）
|
||
2. **佣金归属**：B购买时，佣金给当前推荐人（最新绑定的那个人）
|
||
3. **自动解绑**：绑定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天到期，如果期间无购买 → 自动解绑
|
||
```
|
||
|
||
---
|
||
|
||
## 🗄️ 数据库设计
|
||
|
||
### 1. `referral_bindings` 表字段调整
|
||
|
||
| 字段 | 类型 | 说明 | 新增/修改 |
|
||
|------|------|------|-----------|
|
||
| `id` | VARCHAR(64) | 主键 | - |
|
||
| `referee_id` | VARCHAR(64) | 被推荐人（B） | - |
|
||
| `referrer_id` | VARCHAR(64) | 推荐人（当前） | - |
|
||
| `referral_code` | VARCHAR(20) | 推荐码 | - |
|
||
| `status` | ENUM | active/converted/expired/cancelled | **新增 cancelled** |
|
||
| `binding_date` | TIMESTAMP | 最后一次绑定时间 | - |
|
||
| `expiry_date` | DATETIME | 过期时间（30天后） | - |
|
||
| `last_purchase_date` | DATETIME | 最后一次购买时间 | **新增** |
|
||
| `purchase_count` | INT | 购买次数 | **新增** |
|
||
| `total_commission` | DECIMAL | 累计佣金 | **新增** |
|
||
|
||
### 2. 新增字段的 SQL
|
||
|
||
```sql
|
||
-- 添加新字段
|
||
ALTER TABLE referral_bindings
|
||
ADD COLUMN last_purchase_date DATETIME NULL COMMENT '最后一次购买时间',
|
||
ADD COLUMN purchase_count INT DEFAULT 0 COMMENT '购买次数',
|
||
ADD COLUMN total_commission DECIMAL(10,2) DEFAULT 0.00 COMMENT '累计佣金',
|
||
ADD INDEX idx_expiry_status (expiry_date, status);
|
||
|
||
-- 修改 status 枚举（如果需要）
|
||
ALTER TABLE referral_bindings
|
||
MODIFY COLUMN status ENUM('active', 'converted', 'expired', 'cancelled') DEFAULT 'active';
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 API 逻辑修改
|
||
|
||
### 1. `/api/referral/bind` - 立即切换绑定
|
||
|
||
**修改前逻辑（现有）：**
|
||
```javascript
|
||
if (existingBinding && expiryDate > now) {
|
||
return { error: '绑定有效期内无法更换' } // ❌ 阻止切换
|
||
}
|
||
```
|
||
|
||
**修改后逻辑（新）：**
|
||
```javascript
|
||
// 查询B当前的绑定
|
||
const existingBinding = await query(`
|
||
SELECT * FROM referral_bindings
|
||
WHERE referee_id = ? AND status = 'active'
|
||
`, [userId])
|
||
|
||
if (existingBinding.length > 0) {
|
||
const current = existingBinding[0]
|
||
|
||
// 情况1: 同一个推荐人 → 续期（刷新30天）
|
||
if (current.referrer_id === newReferrerId) {
|
||
await query(`
|
||
UPDATE referral_bindings
|
||
SET expiry_date = DATE_ADD(NOW(), INTERVAL 30 DAY),
|
||
binding_date = NOW()
|
||
WHERE id = ?
|
||
`, [current.id])
|
||
return { success: true, action: 'renewed' }
|
||
}
|
||
|
||
// 情况2: 不同推荐人 → 立即切换
|
||
else {
|
||
// 旧绑定标记为 cancelled
|
||
await query(`
|
||
UPDATE referral_bindings
|
||
SET status = 'cancelled'
|
||
WHERE id = ?
|
||
`, [current.id])
|
||
|
||
// 创建新绑定
|
||
await query(`
|
||
INSERT INTO referral_bindings
|
||
(id, referee_id, referrer_id, referral_code, status, binding_date, expiry_date)
|
||
VALUES (?, ?, ?, ?, 'active', NOW(), DATE_ADD(NOW(), INTERVAL 30 DAY))
|
||
`, [newBindingId, userId, newReferrerId, referralCode])
|
||
|
||
return { success: true, action: 'switched' }
|
||
}
|
||
}
|
||
```
|
||
|
||
**关键变化**：
|
||
- ✅ 删除"有效期内不能切换"的限制
|
||
- ✅ 旧绑定标记为 `cancelled`（而不是 `expired`）
|
||
- ✅ 立即创建新绑定，重新计算30天
|
||
|
||
---
|
||
|
||
### 2. `/api/miniprogram/pay/notify` - 支付回调更新
|
||
|
||
**修改前逻辑（现有）：**
|
||
```javascript
|
||
// 更新绑定为 converted
|
||
await query(`
|
||
UPDATE referral_bindings
|
||
SET status = 'converted',
|
||
conversion_date = NOW(),
|
||
commission_amount = ?
|
||
WHERE id = ?
|
||
`, [commission, bindingId])
|
||
```
|
||
|
||
**修改后逻辑（新）：**
|
||
```javascript
|
||
// 查询B当前的绑定（active状态）
|
||
const binding = await query(`
|
||
SELECT * FROM referral_bindings
|
||
WHERE referee_id = ? AND status = 'active'
|
||
ORDER BY binding_date DESC LIMIT 1
|
||
`, [userId])
|
||
|
||
if (binding.length === 0) {
|
||
console.log('[PayNotify] 无有效绑定，跳过分佣')
|
||
return
|
||
}
|
||
|
||
const currentBinding = binding[0]
|
||
const referrerId = currentBinding.referrer_id
|
||
|
||
// 计算佣金
|
||
const commission = amount * distributorShare
|
||
|
||
// 更新绑定记录（累加购买次数和佣金）
|
||
await query(`
|
||
UPDATE referral_bindings
|
||
SET last_purchase_date = NOW(),
|
||
purchase_count = purchase_count + 1,
|
||
total_commission = total_commission + ?
|
||
WHERE id = ?
|
||
`, [commission, currentBinding.id])
|
||
|
||
// 更新推荐人收益
|
||
await query(`
|
||
UPDATE users
|
||
SET pending_earnings = pending_earnings + ?
|
||
WHERE id = ?
|
||
`, [commission, referrerId])
|
||
|
||
console.log('[PayNotify] 分佣成功:', {
|
||
referee: userId,
|
||
referrer: referrerId,
|
||
commission,
|
||
purchaseCount: currentBinding.purchase_count + 1
|
||
})
|
||
```
|
||
|
||
**关键变化**：
|
||
- ✅ 不再标记为 `converted`（保持 `active`）
|
||
- ✅ 记录 `last_purchase_date`（用于判断是否有购买）
|
||
- ✅ 累加 `purchase_count` 和 `total_commission`
|
||
- ✅ 允许同一绑定多次购买分佣
|
||
|
||
---
|
||
|
||
### 3. 定时任务 - 自动解绑
|
||
|
||
**新增文件**: `scripts/auto-unbind-expired.js`
|
||
|
||
```javascript
|
||
/**
|
||
* 自动解绑定时任务
|
||
* 每天凌晨2点运行（建议配置 cron）
|
||
*
|
||
* 解绑条件：
|
||
* 1. 绑定超过30天（expiry_date < NOW）
|
||
* 2. 期间没有任何购买（purchase_count = 0）
|
||
*/
|
||
|
||
const { query } = require('../lib/db')
|
||
|
||
async function autoUnbind() {
|
||
console.log('[AutoUnbind] 开始执行自动解绑任务...')
|
||
|
||
try {
|
||
// 查询需要解绑的记录
|
||
const expiredBindings = await query(`
|
||
SELECT id, referee_id, referrer_id, binding_date, expiry_date
|
||
FROM referral_bindings
|
||
WHERE status = 'active'
|
||
AND expiry_date < NOW()
|
||
AND purchase_count = 0
|
||
`)
|
||
|
||
if (expiredBindings.length === 0) {
|
||
console.log('[AutoUnbind] 无需解绑的记录')
|
||
return
|
||
}
|
||
|
||
console.log(`[AutoUnbind] 找到 ${expiredBindings.length} 条需要解绑的记录`)
|
||
|
||
// 批量更新为 expired
|
||
const ids = expiredBindings.map(b => b.id)
|
||
await query(`
|
||
UPDATE referral_bindings
|
||
SET status = 'expired'
|
||
WHERE id IN (?)
|
||
`, [ids])
|
||
|
||
console.log(`[AutoUnbind] ✅ 已解绑 ${expiredBindings.length} 条记录`)
|
||
|
||
// 输出明细
|
||
expiredBindings.forEach(b => {
|
||
console.log(` - ${b.referee_id} 解除与 ${b.referrer_id} 的绑定（绑定于 ${b.binding_date}）`)
|
||
})
|
||
|
||
} catch (error) {
|
||
console.error('[AutoUnbind] ❌ 执行失败:', error)
|
||
}
|
||
}
|
||
|
||
// 如果直接运行此脚本
|
||
if (require.main === module) {
|
||
autoUnbind().then(() => {
|
||
console.log('[AutoUnbind] 任务完成')
|
||
process.exit(0)
|
||
})
|
||
}
|
||
|
||
module.exports = { autoUnbind }
|
||
```
|
||
|
||
**部署方式（宝塔面板）**：
|
||
1. 进入"计划任务" → 添加 Shell 脚本
|
||
2. 执行周期：每天 02:00
|
||
3. 脚本内容：
|
||
```bash
|
||
cd /www/wwwroot/soul && node scripts/auto-unbind-expired.js
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 状态流转图
|
||
|
||
```
|
||
用户B的绑定状态流转：
|
||
|
||
[无绑定]
|
||
↓ (点击A的链接)
|
||
[active - 绑定A] ← expiry_date = NOW + 30天
|
||
↓ (点击C的链接)
|
||
[active - 绑定C] ← 旧绑定变 cancelled，新绑定 expiry_date = NOW + 30天
|
||
↓ (购买)
|
||
[active - 绑定C] ← purchase_count++, last_purchase_date = NOW
|
||
↓ (30天后，无购买)
|
||
[expired] ← 自动解绑
|
||
↓ (再次点击D的链接)
|
||
[active - 绑定D] ← 重新绑定
|
||
```
|
||
|
||
**status 枚举说明**：
|
||
- `active`: 当前有效绑定
|
||
- `cancelled`: 被切换（用户点了其他人链接）
|
||
- `expired`: 30天到期且无购买
|
||
- `converted`: **不再使用**（在新逻辑中，购买不改变status）
|
||
|
||
---
|
||
|
||
## 🧪 测试用例
|
||
|
||
### 用例1: 立即切换绑定
|
||
|
||
```
|
||
1. A推荐B → B注册
|
||
预期: referral_bindings 新增一条 (referee=B, referrer=A, status=active)
|
||
|
||
2. B点击C的链接
|
||
预期:
|
||
- 旧记录 (referrer=A) status → cancelled
|
||
- 新记录 (referrer=C) status = active, expiry_date = NOW + 30天
|
||
|
||
3. B购买文章
|
||
预期:
|
||
- 佣金给C（不是A）
|
||
- binding.purchase_count = 1
|
||
- binding.last_purchase_date = NOW
|
||
```
|
||
|
||
### 用例2: 30天无购买自动解绑
|
||
|
||
```
|
||
1. A推荐B → B注册
|
||
预期: binding (referee=B, referrer=A, expiry_date = NOW + 30天)
|
||
|
||
2. 等待31天（模拟）
|
||
手动执行: node scripts/auto-unbind-expired.js
|
||
预期: binding.status → expired
|
||
|
||
3. B点击C的链接
|
||
预期: 创建新绑定 (referrer=C)
|
||
```
|
||
|
||
### 用例3: 多次购买累加佣金
|
||
|
||
```
|
||
1. A推荐B → B绑定A
|
||
2. B购买文章1（1元）
|
||
预期: A获得佣金 0.9元，binding.purchase_count = 1
|
||
3. B购买文章2（1元）
|
||
预期: A再获得佣金 0.9元，binding.purchase_count = 2，total_commission = 1.8
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
### 1. 边界情况处理
|
||
|
||
**Q1: B多次点击同一个人的链接？**
|
||
- A: 刷新 `expiry_date`（续期30天），不创建新记录
|
||
|
||
**Q2: B在切换推荐人后的旧订单佣金？**
|
||
- A: 历史佣金不变，只影响新订单
|
||
|
||
**Q3: 用户注册时没有推荐码？**
|
||
- A: 无绑定状态，等待首次点击分享链接
|
||
|
||
### 2. 数据一致性
|
||
|
||
- 使用事务保证绑定切换的原子性
|
||
- 定时任务运行时间建议在凌晨低峰期
|
||
- 建议添加 `idx_expiry_status` 索引优化查询
|
||
|
||
### 3. 性能优化
|
||
|
||
```sql
|
||
-- 优化索引
|
||
CREATE INDEX idx_referee_status ON referral_bindings(referee_id, status);
|
||
CREATE INDEX idx_expiry_purchase ON referral_bindings(expiry_date, purchase_count);
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### Step 1: 数据库迁移
|
||
```bash
|
||
# 执行 SQL 添加新字段
|
||
mysql -u root -p mycontent_db < scripts/migration-add-binding-fields.sql
|
||
```
|
||
|
||
### Step 2: 修改 API 代码
|
||
- ✅ 修改 `/api/referral/bind`（立即切换逻辑）
|
||
- ✅ 修改 `/api/miniprogram/pay/notify`（累加购买次数）
|
||
|
||
### Step 3: 部署定时任务
|
||
- ✅ 创建 `scripts/auto-unbind-expired.js`
|
||
- ✅ 宝塔面板配置 cron（每天02:00）
|
||
|
||
### Step 4: 测试验证
|
||
- ✅ 测试切换绑定流程
|
||
- ✅ 测试购买分佣
|
||
- ✅ 手动运行定时任务验证解绑
|
||
|
||
---
|
||
|
||
## 📈 后续优化建议
|
||
|
||
1. **管理后台增强**
|
||
- 查看绑定切换历史（谁被谁抢走了）
|
||
- 统计推荐人的"流失率"（被切换走的比例）
|
||
|
||
2. **用户端提示**
|
||
- 点击新链接时提示"即将切换推荐人"
|
||
- 显示当前绑定的推荐人信息
|
||
|
||
3. **防刷机制**
|
||
- 限制同一用户短时间内频繁切换绑定
|
||
- 记录IP和设备指纹防止恶意刷绑定
|
||
|
||
4. **数据分析**
|
||
- 统计平均绑定时长
|
||
- 分析哪些推荐人容易被"抢走"
|
||
- 优化推荐策略
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [分销与绑定流程图](./分销与绑定流程图.md)
|
||
- [推广设置功能完整修复清单](./推广设置功能-完整修复清单.md)
|
||
- [API接入说明](./API接入说明.md)
|