soul-yongping/开发文档/8、部署/自动解绑API配置说明.md

# 自动解绑API配置说明

## 📋 接口信息

### API 地址
```
GET https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
```

### 功能说明
自动解绑过期的推荐关系，条件：
- ✅ `status = 'active'`（活跃状态）
- ✅ `expiry_date < NOW()`（已过期）
- ✅ `purchase_count = 0`（从未购买）

**规则说明**：
- 只解绑「活跃 + 过期 + 未购买」的绑定
- 如果用户购买过（`purchase_count > 0`），即使过期也**不解绑**
- 保留有价值的推荐关系记录

---

## 🔧 宝塔面板配置

### 步骤1: 创建计划任务

1. 登录宝塔面板
2. 点击左侧菜单「计划任务」
3. 点击「添加计划任务」

### 步骤2: 配置任务参数

**任务类型**: 访问URL

**任务名称**: 自动解绑过期推荐关系

**执行周期**: N分钟

**分钟选择**: 30（每30分钟执行一次）

**URL地址**:
```
https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
```

**备注**: 自动解绑过期且未购买的推荐关系

### 步骤3: 保存并测试

1. 点击「保存」
2. 点击「执行」按钮手动测试一次
3. 查看执行日志，确认任务正常运行

---

## 📊 返回数据格式

### 成功响应（有数据）
```json
{
  "success": true,
  "message": "自动解绑完成",
  "unbound": 5,
  "updatedReferrers": 3,
  "details": [
    {
      "refereeId": "user_123",
      "referrerId": "user_456",
      "bindingDate": "2026-01-05T10:30:00.000Z",
      "expiryDate": "2026-02-04T10:30:00.000Z",
      "daysExpired": 1
    }
  ],
  "duration": 245
}
```

### 成功响应（无数据）
```json
{
  "success": true,
  "message": "无需解绑的记录",
  "unbound": 0,
  "duration": 12
}
```

### 失败响应（密钥错误）
```json
{
  "success": false,
  "error": "未授权访问"
}
```

---

## 🔍 日志示例

### 控制台输出
```
[UnbindExpired] ========== 自动解绑任务开始 ==========
[UnbindExpired] 找到 5 条需要解绑的记录
[UnbindExpired] 1. 用户 user_123
  推荐人: user_456
  绑定时间: 2026/1/5
  过期时间: 2026/2/4 (已过期 1 天)
  购买次数: 0
  累计佣金: ¥0.00
[UnbindExpired] 2. 用户 user_789
  推荐人: user_456
  绑定时间: 2026/1/10
  过期时间: 2026/2/3 (已过期 2 天)
  购买次数: 0
  累计佣金: ¥0.00
...
[UnbindExpired] 已成功解绑 5 条记录
[UnbindExpired] 更新推荐人 user_456 的 referral_count (-3)
[UnbindExpired] 更新推荐人 user_999 的 referral_count (-2)
[UnbindExpired] 解绑完成: 5 条记录，更新 2 个推荐人
[UnbindExpired] ========== 任务结束 (耗时 245ms) ==========
```

---

## 🔐 安全说明

### 密钥保护
- 密钥硬编码在代码中：`soul_cron_unbind_2026`
- 只能通过正确的密钥访问接口
- 如果需要修改密钥，编辑 `app/api/cron/unbind-expired/route.ts` 第 24 行

### 访问权限
- ✅ 只支持 GET 请求
- ✅ 需要提供正确的 secret 参数
- ✅ 错误的密钥返回 401 未授权

---

## ⏰ 推荐执行频率

### 每30分钟（推荐）
- ✅ 及时处理过期绑定
- ✅ 不会给服务器造成压力
- ✅ 符合业务需求

### 其他选项
- 每15分钟：如果需要更实时的解绑
- 每1小时：如果对实时性要求不高
- 每天凌晨3点：如果只需要每日清理

---

## 🧪 手动测试

### 方法1: 浏览器测试
直接在浏览器访问：
```
https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026
```

### 方法2: curl 命令
```bash
curl "https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026"
```

### 方法3: 宝塔面板手动执行
1. 进入「计划任务」
2. 找到"自动解绑过期推荐关系"任务
3. 点击「执行」按钮
4. 查看「日志」了解执行结果

---

## 📝 数据库操作

### 查询将被解绑的记录（测试用）
```sql
SELECT 
  id, 
  referrer_id, 
  referee_id, 
  binding_date, 
  expiry_date, 
  purchase_count,
  total_commission,
  DATEDIFF(NOW(), expiry_date) as days_expired
FROM referral_bindings
WHERE status = 'active'
  AND expiry_date < NOW()
  AND purchase_count = 0
ORDER BY expiry_date ASC;
```

### 查看解绑历史
```sql
SELECT 
  id, 
  referrer_id, 
  referee_id, 
  binding_date, 
  expiry_date,
  status,
  purchase_count,
  total_commission
FROM referral_bindings
WHERE status = 'expired'
ORDER BY expiry_date DESC
LIMIT 20;
```

---

## 🔄 对比：API vs 脚本

### 旧方案（Node.js 脚本）
```bash
# 缺点：
- ❌ 需要配置服务器环境变量
- ❌ 需要手动配置数据库连接
- ❌ 需要确保 Node.js 路径正确
- ❌ 依赖外部脚本文件
```

### 新方案（API接口）
```bash
# 优点：
- ✅ 无需配置环境变量
- ✅ 无需手动配置数据库（使用现有连接）
- ✅ 宝塔面板直接调用URL
- ✅ 集成在应用代码中
- ✅ 更易于维护和监控
```

---

## 📊 监控与告警

### 监控指标
- 解绑数量（`unbound`）
- 执行时长（`duration`）
- 成功率

### 查看执行历史
在宝塔面板的「计划任务」→「日志」中查看每次执行的结果。

### 建议
- 如果单次解绑数量 > 100，检查是否有异常
- 如果连续失败，检查数据库连接或接口状态

---

## ✅ 部署检查清单

部署前确认：
- ✅ API 文件已创建：`app/api/cron/unbind-expired/route.ts`
- ✅ 代码已部署到服务器
- ✅ PM2 服务已重启

部署后确认：
- ✅ 手动访问接口测试成功
- ✅ 宝塔计划任务已创建
- ✅ 执行周期设置为 30 分钟
- ✅ 手动执行一次测试成功
- ✅ 查看日志确认正常运行

---

## 🚀 快速配置命令

### 宝塔面板 - 计划任务配置

**任务类型**: 访问URL  
**URL地址**: `https://soul.quwanzhi.com/api/cron/unbind-expired?secret=soul_cron_unbind_2026`  
**执行周期**: N分钟 → 30  
**任务名称**: 自动解绑过期推荐关系  

---

**配置完成后，系统将每30分钟自动解绑过期且未购买的推荐关系！**