281 lines
5.9 KiB
Markdown
281 lines
5.9 KiB
Markdown
# 自动解绑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分钟自动解绑过期且未购买的推荐关系！**
|