soul-yongping/开发文档/8、部署/推广设置页面测试清单.md

推广设置页面 - 完整性测试清单

前置条件

• ✅ 已创建 app/admin/referral-settings/page.tsx
• ✅ 已修改 app/admin/layout.tsx 添加菜单入口
• ✅ 已修复 app/api/referral/bind/route.ts 读取 bindingDays

功能验证（按顺序测试）

1. 页面访问测试

• 访问 https://soul.quwanzhi.com/admin/referral-settings 页面正常加载
• 左侧菜单显示「推广设置」入口
• 点击菜单可正常跳转，高亮状态正确

2. 配置加载测试

• 页面打开时自动从 system_config 表加载现有配置
• 若无配置，显示默认值：
  • 好友优惠：5%
  • 推广者分成：90%
  • 绑定有效期：30天
  • 最低提现金额：10元
  • 自动提现：关闭

3. 表单输入验证

• 修改「好友优惠」为 10，输入框显示正确
• 拖动「推广者分成」滑块，数值同步更新
• 输入「绑定有效期」为 60，输入框显示正确
• 修改「最低提现金额」为 50，输入框显示正确
• 切换「自动提现」开关，状态正确

4. 配置保存测试

• 点击「保存配置」按钮
• 弹出成功提示：「✅ 分销配置已保存成功！」
• 刷新页面后，配置仍然是刚才保存的值

5. 数据库验证

在数据库执行以下查询：

SELECT config_key, config_value, description 
FROM system_config 
WHERE config_key = 'referral_config';

预期结果：

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

所有字段都应该是 数字类型（不是字符串 "90"）

6. 业务流程验证

6.1 绑定关系测试

1. 修改「绑定有效期」为 60 天，保存
2. 在小程序中让一个新用户通过推广链接进入并登录
3. 查询数据库：

SELECT referee_id, referrer_id, expiry_date, status
FROM referral_bindings
WHERE referee_id = '新用户ID'
ORDER BY created_at DESC LIMIT 1;

4. 验证：expiry_date 应该是当前时间 + 60 天（不是硬编码的 30 天）

6.2 佣金计算测试

1. 修改「推广者分成」为 85%，保存
2. 让已绑定的用户在小程序购买 100 元的订单
3. 等待支付成功回调
4. 查询数据库：

SELECT user_id, earnings, pending_earnings
FROM users
WHERE user_id = '推广者ID';

5. 验证：pending_earnings 应该增加 85 元（不是 90 元）

6.3 提现门槛测试

1. 修改「最低提现金额」为 50 元，保存
2. 刷新小程序「推广中心」页面
3. 验证：推广规则卡片显示「满 50 元 可提现」
4. 用 pending_earnings < 50 的账号点击提现，应提示「可提现金额不足」

6.4 小程序展示验证

刷新小程序「推广中心」页面，检查「推广规则」卡片：

• 「好友优惠」显示与后台设置一致（如 5%）
• 「你得收益」显示与后台设置一致（如 90%）
• 「绑定期」显示与后台设置一致（如 30 天）

关键代码验证点

读取 referral_config 的 API：

1. ✅ app/api/referral/bind/route.ts - 读取 bindingDays
2. ✅ app/api/miniprogram/pay/notify/route.ts - 读取 distributorShare 并除以 100
3. ✅ app/api/referral/data/route.ts - 读取 distributorShare 并除以 100

数据类型保护：

• ✅ 前端保存时强制转换为 Number 类型
• ✅ 后端 setConfig 使用 JSON.stringify 正确序列化
• ✅ 后端 getConfig 使用 JSON.parse 正确反序列化

回滚方案

如果测试发现问题，可以执行以下 SQL 恢复默认配置：

UPDATE system_config
SET config_value = '{"distributorShare":90,"minWithdrawAmount":10,"bindingDays":30,"userDiscount":5,"enableAutoWithdraw":false}'
WHERE config_key = 'referral_config';

常见问题排查

Q1: 保存后刷新，配置变成了默认值？

排查：检查数据库 system_config 表是否正确写入

Q2: 小程序显示的比例与后台不一致？

排查：

1. 小程序端是否有缓存，清除缓存重试
2. 检查 API /api/referral/data 是否正确读取配置
3. 检查小程序代码是否硬编码了规则文案

Q3: 新绑定关系的过期时间还是 30 天？

排查：

1. 确认 app/api/referral/bind/route.ts 已正确修改
2. 重启 Node.js 服务（pm2 restart soul）
3. 检查服务器日志是否有 "读取配置失败" 的警告

Q4: 佣金计算还是用的旧比例？

排查：

1. 确认订单是在 修改配置之后 创建的
2. 历史订单不会重算，只影响新订单
3. 检查 app/api/miniprogram/pay/notify/route.ts 的日志

上线建议

1. 先在测试环境验证：完成上述所有测试用例
2. 备份数据库：上线前导出 system_config 表
3. 灰度发布：先让内部测试账号测试，确认无误后全量放开
4. 监控日志：上线后密切关注 PM2 日志，搜索 "referral_config" 关键词

性能影响

• 每次绑定/支付回调会额外查询 1 次 system_config 表
• 由于 config_key 有索引，性能影响可忽略
• 建议后续可增加 Redis 缓存（TTL 60秒）优化性能