364 lines
9.0 KiB
Markdown
364 lines
9.0 KiB
Markdown
# 代码逻辑和数据库最终检查清单 ✅
|
||
|
||
## 📊 数据库修改（已完成）
|
||
|
||
### 1. referral_bindings 表新增字段
|
||
```sql
|
||
✅ last_purchase_date DATETIME DEFAULT NULL
|
||
✅ purchase_count INT DEFAULT 0
|
||
✅ total_commission DECIMAL(10,2) DEFAULT 0.00
|
||
✅ status ENUM('active', 'expired', 'cancelled') -- 新增 'cancelled'
|
||
```
|
||
|
||
### 2. 索引优化
|
||
```sql
|
||
✅ idx_status_expiry (status, expiry_date)
|
||
✅ idx_referee_status (referee_id, status)
|
||
✅ idx_referrer_status (referrer_id, status)
|
||
✅ idx_purchase_count (purchase_count)
|
||
```
|
||
|
||
### 3. 数据库迁移执行状态
|
||
- ✅ 已通过 `scripts/migrate_db_simple.py` 成功执行
|
||
- ✅ 所有字段已添加
|
||
- ✅ 所有索引已创建
|
||
|
||
---
|
||
|
||
## 🔧 核心API逻辑（已验证）
|
||
|
||
### 1. `/api/referral/bind` - 绑定/切换推荐人 ✅
|
||
|
||
**文件**: `app/api/referral/bind/route.ts`
|
||
|
||
**关键逻辑**:
|
||
```typescript
|
||
✅ 从 referral_config 读取 bindingDays（不再硬编码 30 天）
|
||
✅ 同一推荐人 → 续期（刷新 30 天）
|
||
✅ 不同推荐人 → 立即切换（无需等待过期）
|
||
- 旧绑定标记为 'cancelled'
|
||
- 创建新绑定，expiry_date = NOW + bindingDays
|
||
- 更新 users.referral_count（旧 -1，新 +1）
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 绑定天数可配置
|
||
- ✅ 切换逻辑正确（不检查 expiry_date）
|
||
- ✅ 旧绑定正确标记为 'cancelled'
|
||
- ✅ 新绑定正确创建
|
||
- ✅ 推荐人数量正确更新
|
||
|
||
---
|
||
|
||
### 2. `/api/miniprogram/pay` - 创建支付订单 ✅
|
||
|
||
**文件**: `app/api/miniprogram/pay/route.ts`
|
||
|
||
**关键逻辑**:
|
||
```typescript
|
||
✅ 从 referral_config 读取 userDiscount（如 5 表示 5%）
|
||
✅ 如果有 referralCode，计算折后价
|
||
finalAmount = amount * (1 - userDiscount / 100)
|
||
finalAmount = max(0.01, round(finalAmount, 2))
|
||
✅ 微信支付使用 finalAmount（折后价）
|
||
✅ 订单表记录 finalAmount（折后价）
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 折扣正确应用（原价 1.00，5% off = 0.95）
|
||
- ✅ 最低金额保护（至少 0.01 元）
|
||
- ✅ 金额精确到分（Math.round）
|
||
- ✅ 订单表记录的是折后价
|
||
|
||
---
|
||
|
||
### 3. `/api/miniprogram/pay/notify` - 支付回调 ✅
|
||
|
||
**文件**: `app/api/miniprogram/pay/notify/route.ts`
|
||
|
||
**关键逻辑**:
|
||
```typescript
|
||
✅ 查找 status = 'active' 的绑定记录
|
||
✅ 检查 expiry_date > NOW（过期不分佣）
|
||
✅ 从 referral_config 读取 distributorShare
|
||
✅ 计算佣金：commission = amount * distributorShare / 100
|
||
✅ 更新 users.pending_earnings += commission
|
||
✅ 更新 referral_bindings:
|
||
- last_purchase_date = NOW
|
||
- purchase_count += 1
|
||
- total_commission += commission
|
||
- status 保持 'active'（不再改为 'converted'）
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 只给 active 且未过期的绑定分佣
|
||
- ✅ 佣金比例可配置
|
||
- ✅ 支持多次购买分佣（不改 status）
|
||
- ✅ 正确累加购买次数和佣金
|
||
- ✅ 记录最后购买时间
|
||
|
||
---
|
||
|
||
### 4. `/api/withdraw` - 提现申请 ✅
|
||
|
||
**文件**: `app/api/withdraw/route.ts`
|
||
|
||
**关键逻辑**:
|
||
```typescript
|
||
✅ 从 referral_config 读取 minWithdrawAmount
|
||
✅ 验证 amount >= minWithdrawAmount（不再硬编码 10 元）
|
||
✅ 验证 amount <= pending_earnings
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 最低提现金额可配置
|
||
- ✅ 金额验证逻辑正确
|
||
|
||
---
|
||
|
||
### 5. `/api/referral/data` - 分销数据统计 ✅
|
||
|
||
**文件**: `app/api/referral/data/route.ts`
|
||
|
||
**关键逻辑**:
|
||
```typescript
|
||
✅ 绑定统计:
|
||
- active: status = 'active' AND expiry_date > NOW
|
||
- converted: status = 'active' AND purchase_count > 0
|
||
- expired: status IN ('expired', 'cancelled') OR expiry_date <= NOW
|
||
|
||
✅ 已转化用户列表:
|
||
WHERE status = 'active' AND purchase_count > 0
|
||
ORDER BY last_purchase_date DESC
|
||
|
||
✅ 返回购买次数、累计佣金
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 不再查询 status = 'converted'
|
||
- ✅ 使用 purchase_count 判断是否已购买
|
||
- ✅ 返回新增的字段（purchase_count, total_commission）
|
||
- ✅ 统计逻辑正确（包含 'cancelled' 状态）
|
||
|
||
---
|
||
|
||
## 🎯 管理后台（已验证）
|
||
|
||
### 1. 推广设置页面 ✅
|
||
|
||
**文件**: `app/admin/referral-settings/page.tsx`
|
||
|
||
**配置项**:
|
||
```typescript
|
||
✅ distributorShare (分销比例, 0-100)
|
||
✅ minWithdrawAmount (最低提现金额, 元)
|
||
✅ bindingDays (绑定天数, 天)
|
||
✅ userDiscount (好友优惠, 0-100)
|
||
✅ enableAutoWithdraw (自动提现, boolean)
|
||
```
|
||
|
||
**验证点**:
|
||
- ✅ 读取配置正确
|
||
- ✅ 保存配置正确（Number/Boolean 转换）
|
||
- ✅ 表单验证正确
|
||
- ✅ 成功提示清晰
|
||
|
||
---
|
||
|
||
### 2. 管理后台菜单 ✅
|
||
|
||
**文件**: `app/admin/layout.tsx`
|
||
|
||
```typescript
|
||
✅ 新增菜单项: "推广设置" → /admin/referral-settings
|
||
✅ 图标: CreditCard
|
||
✅ 位置: "用户管理" 和 "系统设置" 之间
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 小程序端（已完成）
|
||
|
||
### 1. UI修改 ✅
|
||
```xml
|
||
✅ 删除"我的邀请码"卡片（miniprogram/pages/referral/referral.wxml）
|
||
```
|
||
|
||
### 2. 绑定逻辑 ✅
|
||
```javascript
|
||
✅ app.js 调用 /api/referral/bind（后端已实现立即切换）
|
||
✅ 无需前端修改
|
||
```
|
||
|
||
### 3. 支付逻辑 ✅
|
||
```javascript
|
||
✅ pages/read/read.js 传递 referralCode（后端已实现折扣）
|
||
✅ 无需前端修改
|
||
```
|
||
|
||
### 4. 数据展示 ✅
|
||
```javascript
|
||
✅ pages/referral/referral.js 调用 /api/referral/data
|
||
✅ 后端已返回新字段（purchase_count, total_commission）
|
||
✅ 无需前端修改
|
||
```
|
||
|
||
---
|
||
|
||
## ⏰ 定时任务（已创建）
|
||
|
||
### 1. 自动解绑脚本 ✅
|
||
|
||
**文件**: `scripts/auto-unbind-expired-simple.js`
|
||
|
||
**逻辑**:
|
||
```javascript
|
||
✅ 查找 status = 'active' AND expiry_date < NOW AND purchase_count = 0
|
||
✅ 批量更新为 status = 'expired'
|
||
✅ 输出详细日志
|
||
```
|
||
|
||
**部署**:
|
||
```bash
|
||
⏸️ 需在宝塔面板配置: 每天 03:00 执行
|
||
命令: cd /www/wwwroot/soul.quwanzhi.com && /www/server/nodejs/v20.11.0/bin/node scripts/auto-unbind-expired-simple.js >> logs/auto-unbind.log 2>&1
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 业务逻辑验证
|
||
|
||
### 场景1: 首次绑定 ✅
|
||
```
|
||
A 分享链接 → B 点击 → /api/referral/bind
|
||
→ 创建新绑定（status = 'active', expiry_date = NOW + 30天）
|
||
→ users.referral_count += 1
|
||
```
|
||
|
||
### 场景2: 切换推荐人 ✅
|
||
```
|
||
B 已绑定 A → B 点击 C 的链接 → /api/referral/bind
|
||
→ 旧绑定（A-B）标记为 'cancelled'
|
||
→ 创建新绑定（C-B, status = 'active', expiry_date = NOW + 30天）
|
||
→ A.referral_count -= 1, C.referral_count += 1
|
||
```
|
||
|
||
### 场景3: 续期绑定 ✅
|
||
```
|
||
B 已绑定 A → B 再次点击 A 的链接 → /api/referral/bind
|
||
→ 更新绑定（expiry_date = NOW + 30天）
|
||
→ referral_count 不变
|
||
```
|
||
|
||
### 场景4: 首次购买 ✅
|
||
```
|
||
B 绑定 C（5天前）→ B 购买 1.00 元章节（有 5% 优惠）
|
||
→ 实付 0.95 元
|
||
→ C 获得佣金 0.95 * 90% = 0.855 元（四舍五入 0.86）
|
||
→ referral_bindings: purchase_count = 1, total_commission = 0.86, last_purchase_date = NOW
|
||
→ C.pending_earnings += 0.86
|
||
→ 绑定保持 'active'
|
||
```
|
||
|
||
### 场景5: 多次购买 ✅
|
||
```
|
||
B 再次购买 1.00 元章节（还在 30 天内）
|
||
→ 实付 0.95 元
|
||
→ C 再获得佣金 0.86 元
|
||
→ referral_bindings: purchase_count = 2, total_commission = 1.72, last_purchase_date = NOW
|
||
→ C.pending_earnings += 0.86（累计 1.72）
|
||
→ 绑定保持 'active'
|
||
```
|
||
|
||
### 场景6: 自动解绑 ✅
|
||
```
|
||
B 绑定 A（30 天前）→ B 从未购买 → 定时任务执行
|
||
→ 查找: status = 'active' AND expiry_date < NOW AND purchase_count = 0
|
||
→ 更新: status = 'expired'
|
||
→ A.referral_count -= 1
|
||
```
|
||
|
||
### 场景7: 提现 ✅
|
||
```
|
||
C 有 pending_earnings = 15.00 元 → 申请提现 12.00 元
|
||
→ 验证 amount >= minWithdrawAmount（默认 10）
|
||
→ 验证 amount <= pending_earnings
|
||
→ 创建提现记录
|
||
→ C.pending_earnings -= 12.00 = 3.00
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 最终确认
|
||
|
||
### 代码逻辑
|
||
- ✅ 所有 API 已适配新逻辑
|
||
- ✅ 所有硬编码值已改为动态配置
|
||
- ✅ 所有状态转换逻辑正确
|
||
- ✅ 所有金额计算精确到分
|
||
|
||
### 数据库
|
||
- ✅ 所有字段已添加
|
||
- ✅ 所有索引已创建
|
||
- ✅ 数据类型正确
|
||
- ✅ 默认值正确
|
||
|
||
### 小程序
|
||
- ✅ UI 已删除邀请码卡片
|
||
- ✅ 绑定逻辑兼容后端
|
||
- ✅ 支付逻辑兼容后端
|
||
- ✅ 数据展示兼容后端
|
||
|
||
### 管理后台
|
||
- ✅ 推广设置页面已创建
|
||
- ✅ 菜单已添加
|
||
- ✅ 配置读写正确
|
||
|
||
### 定时任务
|
||
- ✅ 脚本已创建
|
||
- ⏸️ 需在宝塔配置（部署时）
|
||
|
||
---
|
||
|
||
## 🚀 部署检查项
|
||
|
||
部署前确认:
|
||
- ✅ 代码已修改
|
||
- ✅ 数据库已迁移
|
||
- ✅ 本地测试通过
|
||
|
||
部署后确认:
|
||
- ⏸️ PM2 重启成功
|
||
- ⏸️ 定时任务配置成功
|
||
- ⏸️ 管理后台可访问 `/admin/referral-settings`
|
||
- ⏸️ 小程序绑定/支付/分佣功能测试通过
|
||
|
||
---
|
||
|
||
## 📝 测试用例（可选）
|
||
|
||
如需本地测试，运行:
|
||
```bash
|
||
node scripts/test-referral-flow.js
|
||
```
|
||
|
||
测试覆盖:
|
||
- ✅ 首次绑定
|
||
- ✅ 续期绑定
|
||
- ✅ 切换绑定
|
||
- ✅ 首次购买分佣
|
||
- ✅ 多次购买分佣
|
||
- ✅ 过期绑定不分佣
|
||
|
||
---
|
||
|
||
## ✅ 结论
|
||
|
||
**所有代码逻辑和数据库修改已完成并验证，可以放心部署！**
|
||
|
||
需要在宝塔面板配置的只有：
|
||
1. 重启 PM2 服务（让新代码生效）
|
||
2. 配置定时任务（自动解绑）
|
||
|
||
参考文档: `开发文档/8、部署/新分销逻辑-宝塔操作清单.md`
|