返利系统配置指南

返利系统允许用户通过推荐链接邀请新用户注册，在被推荐用户的每笔消费中获得现金佣金。系统同时支持双向注册奖励，推荐人和被推荐人都可以获得积分奖励。

相关页面

系统概述

快速启用

返利系统默认关闭。完成支付、风控、提现和客服流程配置后，设置 AFFILIATE_ENABLED=true 才会启用。

启用后，用户仪表盘会自动出现 Affiliate 和 Withdrawal 两个标签页，管理后台侧边栏出现 Commissions 和 Withdrawals 导航。

最小配置

必须显式开启；其余参数均可使用默认值：

# 必填：默认关闭
AFFILIATE_ENABLED=true
# 可选：其余值均有合理默认值
# AFFILIATE_COMMISSION_RATE=0.20
# AFFILIATE_REFERRER_SIGNUP_BONUS=10
# AFFILIATE_REFEREE_SIGNUP_BONUS=10
# AFFILIATE_MIN_WITHDRAWAL=100
# AFFILIATE_COOKIE_EXPIRY_DAYS=30

禁用返利系统

AFFILIATE_ENABLED=false

设置后：

• 用户仪表盘不显示 Affiliate / Withdrawal 标签
• 管理后台不显示佣金/提现导航
• API 返回 enabled: false
• 支付 Webhook 跳过佣金处理

环境变量配置

币种限制

当前返利系统仅支持单一币种。佣金余额 commissionBalance 是一个简单数值累加字段，不区分币种。

如果你的 config/payment.ts 中有多个币种的 plan（如 USD 和 CNY），你必须确保参与返利的 plan 都使用同一币种。混合不同币种的佣金会导致余额数字无实际意义。

推荐做法：

1. 将 AFFILIATE_CURRENCY 设为你主要的计费币种（默认 USD）
2. 确保 config/payment.ts 中所有参与返利的 plan 的 currency 与 AFFILIATE_CURRENCY 一致
3. 如果你同时有 CNY 和 USD 的 plan，考虑仅对其中一种币种的 plan 启用佣金（需自行在 Webhook 处理逻辑中过滤）

配置示例

# 高佣金模式（适合高客单价产品）
AFFILIATE_COMMISSION_RATE=0.30
AFFILIATE_MIN_WITHDRAWAL=50

# 固定佣金模式（每单固定 5 元）
AFFILIATE_FIXED_COMMISSION_AMOUNT=5

# 大额注册奖励（促进推荐）
AFFILIATE_REFERRER_SIGNUP_BONUS=50
AFFILIATE_REFEREE_SIGNUP_BONUS=20

工作流程

推荐注册流程

1. 用户 A 在仪表盘获取推荐链接：https://yourapp.com?ref=NjMDryrv
2. 用户 B 点击链接访问网站
3. 中间件自动将 ref 参数存为 Cookie（30 天有效）
4. 用户 B 注册并登录
5. 首次访问仪表盘时自动触发 claim
6. 系统将推荐关系记录到数据库
7. 双方各获得积分奖励（如果配置了奖励金额 > 0）

佣金产生流程

1. 用户 B（被推荐人）购买任何付费计划或积分包
2. 支付成功 → 支付 Webhook 触发
3. Webhook 处理完订单后调用 processReferralCommission(orderId)
4. 系统检查订单元数据中的推荐人信息
5. 按配置的佣金比例计算佣金金额
6. 创建佣金记录，累加到推荐人的 commissionBalance

提现流程

1. 用户 A 在仪表盘 Withdrawal 标签申请提现
2. 填写金额、支付方式（支付宝/银行转账等）、收款账号
3. 系统验证余额 ≥ 提现金额 ≥ 最低提现金额
4. 余额立即扣减（防止重复提现）
5. 管理员在后台审批：
   - 批准（completed）：管理员手动转账
   - 拒绝（rejected）：余额自动退还

管理员操作

查看佣金记录

访问 /admin/commissions，可以：

• 查看所有用户的佣金记录
• 按邮箱搜索
• 查看佣金金额、订单金额、佣金率、状态

审批提现

访问 /admin/withdrawals，可以：

• 查看所有提现申请
• 按邮箱搜索
• 点击 Approve 批准提现（需手动转账）
• 点击 Reject 拒绝提现（余额自动退还用户）

常见问题

用户看不到 Affiliate 标签？

检查 AFFILIATE_ENABLED=true 已配置。重启开发服务器使配置生效。

佣金没有产生？

1. 确认被推荐用户的订单 metadata 中包含 referralCode 和 referrerId
2. 查看支付 Webhook 日志中是否有 [Affiliate][Commission] 相关输出
3. 确认 processReferralCommission(orderId) 已在对应支付方式的 Webhook 中调用

推荐链接不生效？

1. 确认链接包含 ?ref=CODE 参数
2. 检查浏览器是否设置了 referral_code Cookie
3. 用户必须注册并登录后才能 claim
4. 每个用户只能被推荐一次

数据库 SQLite 兼容性？

系统同时支持 PostgreSQL 和 SQLite。所有 SQL 使用标准 CAST() 语法，已在两种数据库上通过完整 E2E 测试。

相关文档

• 积分系统配置 - 注册奖励通过积分系统发放
• 支付测试指南 - 测试支付 Webhook 触发佣金
• 数据库配置 - PostgreSQL / SQLite 切换