385 lines
8.6 KiB
Markdown
385 lines
8.6 KiB
Markdown
# 管理端推广配置与小程序对接说明
|
||
|
||
## 📋 配置项说明
|
||
|
||
### 管理端配置
|
||
**位置**: `/admin/referral-settings`
|
||
|
||
**配置项**:
|
||
1. **distributorShare** - 分销比例（例如：90 表示 90%）
|
||
2. **minWithdrawAmount** - 最低提现金额（例如：10 表示 10元）
|
||
3. **bindingDays** - 绑定天数（例如：30 表示 30天）
|
||
4. **userDiscount** - 好友优惠（例如：5 表示 5% 折扣）
|
||
5. **enableAutoWithdraw** - 是否启用自动提现
|
||
|
||
**存储位置**: `system_config` 表，键名 `referral_config`
|
||
|
||
---
|
||
|
||
## ✅ 已对接的配置
|
||
|
||
### 1. distributorShare（分销比例）
|
||
|
||
#### 后端使用
|
||
**文件**: `app/api/miniprogram/pay/notify/route.ts`
|
||
|
||
**用途**: 计算推荐人佣金
|
||
```typescript
|
||
// 获取配置
|
||
const config = await getConfig('referral_config')
|
||
const distributorShare = config.distributorShare / 100 // 90 → 0.9
|
||
|
||
// 计算佣金
|
||
const commission = amount * distributorShare // 1元 * 0.9 = 0.9元
|
||
```
|
||
|
||
#### 前端显示
|
||
**文件**: `miniprogram/pages/referral/referral.wxml`
|
||
|
||
**位置**: 分销中心页面
|
||
```xml
|
||
<text class="commission-rate">{{shareRate}}% 返利</text>
|
||
```
|
||
|
||
**数据来源**: `/api/referral/data` 接口返回 `shareRate`
|
||
|
||
**对接状态**: ✅ 已完成
|
||
- 后端从配置读取
|
||
- API返回给前端
|
||
- 前端动态显示
|
||
|
||
---
|
||
|
||
### 2. minWithdrawAmount（最低提现金额）
|
||
|
||
#### 后端使用
|
||
**文件**: `app/api/withdraw/route.ts`
|
||
|
||
**用途**: 验证提现金额
|
||
```typescript
|
||
// 获取配置
|
||
const config = await getConfig('referral_config')
|
||
const minWithdrawAmount = config.minWithdrawAmount || 10
|
||
|
||
// 验证金额
|
||
if (amount < minWithdrawAmount) {
|
||
return error('提现金额不能低于' + minWithdrawAmount + '元')
|
||
}
|
||
```
|
||
|
||
#### 前端显示
|
||
**文件**: `miniprogram/pages/referral/referral.wxml`
|
||
|
||
**位置**: 提现按钮
|
||
```xml
|
||
<!-- 旧代码（硬编码） -->
|
||
<view class="withdraw-btn {{earnings < 10 ? 'btn-disabled' : ''}}">
|
||
{{earnings < 10 ? '满10元可提现' : '申请提现'}}
|
||
</view>
|
||
|
||
<!-- 新代码（动态配置） -->
|
||
<view class="withdraw-btn {{pendingEarnings < minWithdrawAmount ? 'btn-disabled' : ''}}">
|
||
{{pendingEarnings < minWithdrawAmount ? '满' + minWithdrawAmount + '元可提现' : '申请提现'}}
|
||
</view>
|
||
```
|
||
|
||
**数据来源**: `/api/referral/data` 接口返回 `minWithdrawAmount`
|
||
|
||
**对接状态**: ✅ 刚完成
|
||
- 后端从配置读取
|
||
- API新增返回字段
|
||
- 前端动态显示
|
||
|
||
---
|
||
|
||
### 3. bindingDays（绑定天数）
|
||
|
||
#### 后端使用
|
||
**文件**: `app/api/referral/bind/route.ts`
|
||
|
||
**用途**: 计算绑定过期时间
|
||
```typescript
|
||
// 获取配置
|
||
const config = await getConfig('referral_config')
|
||
const bindingDays = config.bindingDays || 30
|
||
|
||
// 计算过期时间
|
||
const expiryDate = new Date()
|
||
expiryDate.setDate(expiryDate.getDate() + bindingDays)
|
||
```
|
||
|
||
**对接状态**: ✅ 已完成
|
||
- 后端从配置读取
|
||
- 自动应用于绑定逻辑
|
||
- 前端无需显示（内部逻辑）
|
||
|
||
---
|
||
|
||
### 4. userDiscount（好友优惠）
|
||
|
||
#### 后端使用
|
||
**文件**: `app/api/miniprogram/pay/route.ts`
|
||
|
||
**用途**: 计算好友购买折扣
|
||
```typescript
|
||
// 获取配置
|
||
const config = await getConfig('referral_config')
|
||
const userDiscount = config.userDiscount || 0
|
||
|
||
// 计算折后价
|
||
if (userDiscount > 0 && referralCode) {
|
||
finalAmount = amount * (1 - userDiscount / 100) // 1元 * (1 - 0.05) = 0.95元
|
||
}
|
||
```
|
||
|
||
**对接状态**: ✅ 已完成
|
||
- 后端从配置读取
|
||
- 自动应用于支付流程
|
||
- 前端无需显示（微信支付弹窗自动显示折后价）
|
||
|
||
---
|
||
|
||
### 5. enableAutoWithdraw（自动提现）
|
||
|
||
**对接状态**: ⏸️ 功能待开发
|
||
- 配置已存在
|
||
- 后端逻辑待实现
|
||
- 前端UI待实现
|
||
|
||
---
|
||
|
||
## 🔄 数据流向图
|
||
|
||
```
|
||
管理端修改配置
|
||
↓
|
||
保存到 system_config 表
|
||
↓
|
||
后端API读取配置（getConfig）
|
||
↓
|
||
├─→ /api/referral/bind → 使用 bindingDays
|
||
├─→ /api/miniprogram/pay → 使用 userDiscount
|
||
├─→ /api/miniprogram/pay/notify → 使用 distributorShare
|
||
├─→ /api/withdraw → 使用 minWithdrawAmount
|
||
└─→ /api/referral/data → 返回 shareRate + minWithdrawAmount
|
||
↓
|
||
小程序获取数据
|
||
↓
|
||
动态显示配置
|
||
```
|
||
|
||
---
|
||
|
||
## 📝 本次修改内容
|
||
|
||
### 1. 后端API修改
|
||
**文件**: `app/api/referral/data/route.ts`
|
||
|
||
**修改内容**:
|
||
```typescript
|
||
// 新增读取 minWithdrawAmount
|
||
let minWithdrawAmount = 10
|
||
try {
|
||
const config = await getConfig('referral_config')
|
||
if (config?.minWithdrawAmount) {
|
||
minWithdrawAmount = Number(config.minWithdrawAmount)
|
||
}
|
||
} catch (e) { /* 使用默认 */ }
|
||
|
||
// 返回数据中新增字段
|
||
return {
|
||
shareRate: Math.round(distributorShare * 100),
|
||
minWithdrawAmount, // 新增
|
||
// ... 其他字段
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 小程序JS修改
|
||
**文件**: `miniprogram/pages/referral/referral.js`
|
||
|
||
**修改内容**:
|
||
```javascript
|
||
// data 中新增字段
|
||
data: {
|
||
minWithdrawAmount: 10, // 新增
|
||
shareRate: 90,
|
||
// ...
|
||
}
|
||
|
||
// 从API获取配置
|
||
setData({
|
||
shareRate: realData?.shareRate || 90,
|
||
minWithdrawAmount: realData?.minWithdrawAmount || 10, // 新增
|
||
// ...
|
||
})
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 小程序WXML修改
|
||
**文件**: `miniprogram/pages/referral/referral.wxml`
|
||
|
||
**旧代码**:
|
||
```xml
|
||
<view class="withdraw-btn {{earnings < 10 ? 'btn-disabled' : ''}}">
|
||
{{earnings < 10 ? '满10元可提现' : '申请提现'}}
|
||
</view>
|
||
```
|
||
|
||
**新代码**:
|
||
```xml
|
||
<view class="withdraw-btn {{pendingEarnings < minWithdrawAmount ? 'btn-disabled' : ''}}">
|
||
{{pendingEarnings < minWithdrawAmount ? '满' + minWithdrawAmount + '元可提现' : '申请提现'}}
|
||
</view>
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ 对接完成度
|
||
|
||
| 配置项 | 后端使用 | API返回 | 小程序显示 | 状态 |
|
||
|--------|---------|---------|------------|------|
|
||
| distributorShare | ✅ | ✅ | ✅ | 已完成 |
|
||
| minWithdrawAmount | ✅ | ✅ | ✅ | 刚完成 |
|
||
| bindingDays | ✅ | - | - | 已完成（内部逻辑）|
|
||
| userDiscount | ✅ | - | - | 已完成（自动应用）|
|
||
| enableAutoWithdraw | ⏸️ | - | - | 待开发 |
|
||
|
||
---
|
||
|
||
## 🧪 测试验证
|
||
|
||
### 1. 修改配置
|
||
1. 登录管理后台
|
||
2. 进入「推广设置」页面
|
||
3. 修改配置：
|
||
- 分销比例：改为 85%
|
||
- 最低提现金额：改为 20元
|
||
4. 保存配置
|
||
|
||
### 2. 验证后端
|
||
```bash
|
||
# 测试分销中心API
|
||
curl "https://soul.quwanzhi.com/api/referral/data?userId=xxx"
|
||
|
||
# 预期返回
|
||
{
|
||
"shareRate": 85,
|
||
"minWithdrawAmount": 20,
|
||
...
|
||
}
|
||
```
|
||
|
||
### 3. 验证小程序
|
||
1. 打开小程序「分销中心」页面
|
||
2. 检查显示：
|
||
- 「85% 返利」（而不是 90%）
|
||
- 「满20元可提现」（而不是满10元）
|
||
3. 尝试提现时，应该验证是否满20元
|
||
|
||
---
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 部署后端
|
||
```bash
|
||
pnpm build
|
||
python devlop.py
|
||
pm2 restart soul
|
||
```
|
||
|
||
### 2. 测试API
|
||
```bash
|
||
curl "https://soul.quwanzhi.com/api/referral/data?userId=xxx"
|
||
```
|
||
|
||
### 3. 上传小程序
|
||
- 在微信开发者工具上传代码
|
||
- 提交审核
|
||
- 发布新版本
|
||
|
||
---
|
||
|
||
## 📊 配置示例
|
||
|
||
### 默认配置
|
||
```json
|
||
{
|
||
"distributorShare": 90,
|
||
"minWithdrawAmount": 10,
|
||
"bindingDays": 30,
|
||
"userDiscount": 5,
|
||
"enableAutoWithdraw": false
|
||
}
|
||
```
|
||
|
||
### 修改后效果
|
||
|
||
#### 场景1: 提高最低提现门槛
|
||
```json
|
||
{ "minWithdrawAmount": 50 }
|
||
```
|
||
**效果**:
|
||
- 后端验证：必须满50元才能提现
|
||
- 小程序显示：「满50元可提现」
|
||
|
||
#### 场景2: 降低分成比例
|
||
```json
|
||
{ "distributorShare": 70 }
|
||
```
|
||
**效果**:
|
||
- 后端计算：推荐人获得 70% 佣金
|
||
- 小程序显示：「70% 返利」
|
||
|
||
#### 场景3: 增加好友优惠
|
||
```json
|
||
{ "userDiscount": 10 }
|
||
```
|
||
**效果**:
|
||
- 后端计算：好友购买打 9折
|
||
- 微信支付：显示折后价（例如 1元 → 0.9元）
|
||
|
||
---
|
||
|
||
## 🔍 问题排查
|
||
|
||
### 问题1: 小程序显示的分成比例不对
|
||
**原因**: 前端没有重新加载数据
|
||
**解决**: 下拉刷新页面，重新调用 `/api/referral/data`
|
||
|
||
### 问题2: 提现验证还是用的旧金额
|
||
**原因**: 后端缓存或配置未更新
|
||
**解决**:
|
||
1. 检查数据库 `system_config` 表
|
||
2. 重启PM2服务
|
||
|
||
### 问题3: 修改配置后小程序不生效
|
||
**原因**: 小程序使用了旧版本
|
||
**解决**:
|
||
1. 确保上传了新版本小程序
|
||
2. 用户需要重启小程序
|
||
|
||
---
|
||
|
||
## ✅ 总结
|
||
|
||
**已完成对接**：
|
||
- ✅ distributorShare（分销比例）- 后端计算 + 小程序显示
|
||
- ✅ minWithdrawAmount（最低提现金额）- 后端验证 + 小程序显示
|
||
- ✅ bindingDays（绑定天数）- 后端逻辑
|
||
- ✅ userDiscount（好友优惠）- 后端计算
|
||
|
||
**待开发功能**：
|
||
- ⏸️ enableAutoWithdraw（自动提现）
|
||
|
||
**优势**：
|
||
- 管理员可以在后台随时调整配置
|
||
- 无需修改代码即可生效
|
||
- 用户看到的是实时配置
|
||
|
||
---
|
||
|
||
**现在管理端的推广配置已完全对接到小程序逻辑！**
|