soul-yongping/开发文档/8、部署/新分销逻辑-宝塔操作清单.md

# 新分销逻辑 - 宝塔面板操作清单

## ✅ 已完成的准备工作

- ✅ 数据库字段已添加（last_purchase_date, purchase_count, total_commission）
- ✅ 代码已部署到服务器（/www/wwwroot/soul/dist）
- ✅ 索引已创建

---

## 🔧 宝塔面板操作步骤

### Step 1: 重启 Node.js 服务

1. 登录宝塔面板：`http://你的服务器IP:8888`
2. 左侧菜单 → **网站** → 找到 `soul.quwanzhi.com`
3. 点击 **设置** → **Node项目** 标签
4. 找到项目 `soul`
5. 点击 **重启** 按钮
6. 等待状态变为"运行中"

**或者使用命令行**（如果有SSH权限）：
```bash
# 使用宝塔的pm2完整路径
/www/server/nodejs/v16.20.2/bin/pm2 restart soul

# 查看状态
/www/server/nodejs/v16.20.2/bin/pm2 status

# 查看日志
/www/server/nodejs/v16.20.2/bin/pm2 logs soul --lines 50
```

---

### Step 2: 验证服务是否正常

#### 2.1 检查网站访问
在浏览器打开：`https://soul.quwanzhi.com`

**预期**：
- ✅ 网站正常加载
- ✅ 无404错误
- ✅ 可以正常登录

#### 2.2 检查新API是否生效

打开浏览器控制台，访问：
```
https://soul.quwanzhi.com/api/db/config?key=referral_config
```

**预期返回**：
```json
{
  "success": true,
  "config": {
    "distributorShare": 90,
    "minWithdrawAmount": 10,
    "bindingDays": 30,
    "userDiscount": 5,
    "enableAutoWithdraw": false
  }
}
```

#### 2.3 检查推广设置页面

访问：`https://soul.quwanzhi.com/admin/referral-settings`

**预期**：
- ✅ 页面正常加载
- ✅ 显示当前配置
- ✅ 可以修改并保存

---

### Step 3: 配置自动解绑定时任务

1. 宝塔面板 → 左侧菜单 → **计划任务**
2. 点击 **添加计划任务**
3. 填写以下信息：

**任务配置**：
```
任务类型：Shell脚本
任务名称：自动解绑过期推荐关系
执行周期：每天 02:00（凌晨2点）
脚本内容：
cd /www/wwwroot/soul/dist && /www/server/nodejs/v16.20.2/bin/node scripts/auto-unbind-expired-simple.js >> /www/wwwroot/soul/logs/auto-unbind.log 2>&1
```

4. 点击 **添加**
5. 任务创建后，点击 **执行** 按钮测试一次

**预期日志**（如果没有过期记录）：
```
============================================================
自动解绑定时任务
执行时间: 2026/2/5 14:30:00
============================================================
✅ 已连接到数据库: soul_miniprogram
✅ 无需解绑的记录
============================================================
任务完成
============================================================
```

---

### Step 4: 查看定时任务日志

```bash
# 方式1：SSH命令
cat /www/wwwroot/soul/logs/auto-unbind.log

# 方式2：宝塔面板
计划任务 → 找到"自动解绑"任务 → 点击"日志"
```

---

## 🧪 功能测试（小程序端）

### 测试1：立即切换绑定

1. **准备两个测试账号**：
   - 账号A：作为推荐人A（获取推荐码 SOULA001）
   - 账号C：作为推荐人C（获取推荐码 SOULC001）
   - 账号B：作为购买者

2. **测试步骤**：
   ```
   Step 1: A 分享文章链接给 B
   Step 2: B 点击链接进入小程序（会自动绑定A）
   Step 3: 查数据库验证绑定
   Step 4: C 分享文章链接给 B
   Step 5: B 点击C的链接（应该立即切换）
   Step 6: 再次查数据库验证
   ```

3. **数据库验证SQL**：
   ```sql
   -- 查看B当前的绑定状态
   SELECT 
     referee_id, 
     referrer_id, 
     status, 
     binding_date, 
     expiry_date
   FROM referral_bindings
   WHERE referee_id = 'B的用户ID'
   ORDER BY binding_date DESC;
   ```

   **预期结果**：
   - 最新一条：`referrer_id = C的ID, status = active`
   - 上一条：`referrer_id = A的ID, status = cancelled`

---

### 测试2：购买分佣

1. **B 购买一篇文章（1元）**
2. **查看分佣结果**：
   ```sql
   SELECT 
     rb.referrer_id,
     rb.purchase_count,
     rb.total_commission,
     rb.last_purchase_date,
     u.pending_earnings
   FROM referral_bindings rb
   JOIN users u ON rb.referrer_id = u.id
   WHERE rb.referee_id = 'B的用户ID' AND rb.status = 'active';
   ```

   **预期结果**（假设90%分成）：
   ```
   referrer_id: C的ID
   purchase_count: 1
   total_commission: 0.90
   pending_earnings: 0.90
   ```

3. **B 再次购买**：
   ```sql
   -- 查询应显示
   purchase_count: 2
   total_commission: 1.80
   pending_earnings: 1.80
   ```

---

### 测试3：好友优惠（新功能）

1. **后台设置好友优惠为 10%**
   - 访问：`https://soul.quwanzhi.com/admin/referral-settings`
   - 修改"好友优惠"为 `10`
   - 保存

2. **B 通过推荐链接购买**
   - 原价 1.00 元的文章
   - 支付时应显示 **0.90 元**（10% off）

3. **验证佣金计算**：
   - C 应获得佣金 = 0.90 × 90% = **0.81 元**
   - 而不是 1.00 × 90% = 0.90 元

---

## 📊 后台监控

### 查看绑定切换记录

**SQL查询**：
```sql
-- 查看最近的绑定切换
SELECT 
  rb.referee_id,
  rb.referrer_id,
  rb.status,
  rb.binding_date,
  rb.purchase_count,
  rb.total_commission
FROM referral_bindings rb
WHERE rb.status IN ('active', 'cancelled')
ORDER BY rb.binding_date DESC
LIMIT 20;
```

### 查看即将过期的绑定

```sql
-- 7天内即将过期且无购买的绑定
SELECT 
  rb.referee_id,
  rb.referrer_id,
  rb.binding_date,
  rb.expiry_date,
  DATEDIFF(rb.expiry_date, NOW()) as days_left,
  rb.purchase_count
FROM referral_bindings rb
WHERE rb.status = 'active'
  AND rb.expiry_date > NOW()
  AND DATEDIFF(rb.expiry_date, NOW()) <= 7
  AND rb.purchase_count = 0
ORDER BY days_left ASC;
```

---

## ⚠️ 常见问题

### Q1: 点击新链接后没有切换？
**检查**：
- 宝塔面板 → Node项目 → 查看日志
- 搜索 `[Referral Bind]` 关键词
- 确认是否有报错

### Q2: 购买后 purchase_count 还是 0？
**检查**：
- 查看支付回调日志：`pm2 logs soul | grep PayNotify`
- 确认字段 `purchase_count` 是否存在
- 执行SQL验证：`SHOW COLUMNS FROM referral_bindings;`

### Q3: 定时任务没有执行？
**检查**：
- 宝塔面板 → 计划任务 → 找到任务 → 点击"执行"测试
- 查看日志：`cat /www/wwwroot/soul/logs/auto-unbind.log`
- 确认脚本路径正确：`ls -la /www/wwwroot/soul/dist/scripts/auto-unbind-expired-simple.js`

---

## 📝 部署后清理

部署成功后，删除临时文件：

```bash
# 本地清理
rm .env.migration
```

---

## ✅ 完成检查清单

- [ ] 数据库字段已添加
- [ ] 代码已部署
- [ ] PM2服务运行正常
- [ ] 网站可以访问
- [ ] 推广设置页面正常
- [ ] 定时任务已配置
- [ ] 功能测试通过

---

**下一步：执行上述测试验证，或告诉我遇到的任何问题！**