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

## 前置条件
- ✅ 已创建 `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. 数据库验证
在数据库执行以下查询：
```sql
SELECT config_key, config_value, description 
FROM system_config 
WHERE config_key = 'referral_config';
```

**预期结果**：
```json
{
  "distributorShare": 90,
  "minWithdrawAmount": 10,
  "bindingDays": 30,
  "userDiscount": 5,
  "enableAutoWithdraw": false
}
```

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

### 6. 业务流程验证

#### 6.1 绑定关系测试
1. 修改「绑定有效期」为 **60 天**，保存
2. 在小程序中让一个新用户通过推广链接进入并登录
3. 查询数据库：
```sql
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. 查询数据库：
```sql
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 恢复默认配置：
```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秒）优化性能