soul-yongping/开发文档/8、部署/管理端推广配置与小程序对接说明.md

# 管理端推广配置与小程序对接说明

## 📋 配置项说明

### 管理端配置
**位置**: `/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（自动提现）

**优势**：
- 管理员可以在后台随时调整配置
- 无需修改代码即可生效
- 用户看到的是实时配置

---

**现在管理端的推广配置已完全对接到小程序逻辑！**