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

用途: 计算推荐人佣金

// 获取配置
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

位置: 分销中心页面

<text class="commission-rate">{{shareRate}}% 返利</text>

数据来源: /api/referral/data 接口返回 shareRate

对接状态: ✅ 已完成

• 后端从配置读取
• API返回给前端
• 前端动态显示

---

2. minWithdrawAmount（最低提现金额）

后端使用

文件: app/api/withdraw/route.ts

用途: 验证提现金额

// 获取配置
const config = await getConfig('referral_config')
const minWithdrawAmount = config.minWithdrawAmount || 10

// 验证金额
if (amount < minWithdrawAmount) {
  return error('提现金额不能低于' + minWithdrawAmount + '元')
}

前端显示

文件: miniprogram/pages/referral/referral.wxml

位置: 提现按钮

<!-- 旧代码（硬编码） -->
<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

用途: 计算绑定过期时间

// 获取配置
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

用途: 计算好友购买折扣

// 获取配置
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

修改内容:

// 新增读取 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

修改内容:

// data 中新增字段
data: {
  minWithdrawAmount: 10,  // 新增
  shareRate: 90,
  // ...
}

// 从API获取配置
setData({
  shareRate: realData?.shareRate || 90,
  minWithdrawAmount: realData?.minWithdrawAmount || 10,  // 新增
  // ...
})

---

3. 小程序WXML修改

文件: miniprogram/pages/referral/referral.wxml

旧代码:

<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返回	小程序显示	状态
distributorShare	✅	✅	✅	已完成
minWithdrawAmount	✅	✅	✅	刚完成
bindingDays	✅	-	-	已完成（内部逻辑）
userDiscount	✅	-	-	已完成（自动应用）
enableAutoWithdraw	⏸️	-	-	待开发

---

🧪 测试验证

1. 修改配置

1. 登录管理后台
2. 进入「推广设置」页面
3. 修改配置：
   • 分销比例：改为 85%
   • 最低提现金额：改为 20元
4. 保存配置

2. 验证后端

# 测试分销中心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. 部署后端

pnpm build
python devlop.py
pm2 restart soul

2. 测试API

curl "https://soul.quwanzhi.com/api/referral/data?userId=xxx"

3. 上传小程序

• 在微信开发者工具上传代码
• 提交审核
• 发布新版本

---

📊 配置示例

默认配置

{
  "distributorShare": 90,
  "minWithdrawAmount": 10,
  "bindingDays": 30,
  "userDiscount": 5,
  "enableAutoWithdraw": false
}

修改后效果

场景1: 提高最低提现门槛

{ "minWithdrawAmount": 50 }

效果:

• 后端验证：必须满50元才能提现
• 小程序显示：「满50元可提现」

场景2: 降低分成比例

{ "distributorShare": 70 }

效果:

• 后端计算：推荐人获得 70% 佣金
• 小程序显示：「70% 返利」

场景3: 增加好友优惠

{ "userDiscount": 10 }

效果:

• 后端计算：好友购买打 9折
• 微信支付：显示折后价（例如 1元 → 0.9元）

---

🔍 问题排查

问题1: 小程序显示的分成比例不对

原因: 前端没有重新加载数据 解决: 下拉刷新页面，重新调用 /api/referral/data

问题2: 提现验证还是用的旧金额

原因: 后端缓存或配置未更新 解决:

1. 检查数据库 system_config 表
2. 重启PM2服务

问题3: 修改配置后小程序不生效

原因: 小程序使用了旧版本 解决:

1. 确保上传了新版本小程序
2. 用户需要重启小程序

---

✅ 总结

已完成对接：

• ✅ distributorShare（分销比例）- 后端计算 + 小程序显示
• ✅ minWithdrawAmount（最低提现金额）- 后端验证 + 小程序显示
• ✅ bindingDays（绑定天数）- 后端逻辑
• ✅ userDiscount（好友优惠）- 后端计算

待开发功能：

• ⏸️ enableAutoWithdraw（自动提现）

优势：

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

---

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