推荐奖励
TanStack Ship 推荐奖励系统，通过自动化双重激励积分奖励推动用户增长，推荐人和新用户均可获得奖励。
概述
TanStack Ship 的推荐奖励系统通过激励现有用户邀请新用户加入平台来推动用户增长。该系统构建于双重奖励模型之上，推荐用户（邀请人）和受邀新用户在成功转化后均可获得积分奖励，形成互利的病毒式增长循环，降低客户获取成本。
作为 TanStack Ship 平台的一部分，推荐奖励模块与邀请系统（追踪谁邀请了谁）、积分系统（以可消费积分形式发放奖励）和用户仪表板（提供推荐状态和奖励余额可见性）深度集成。系统以幂等性保证处理奖励，确保每个成功推荐无论面临竞争条件还是重试场景，都能获得且仅获得一次奖励发放。
设计流程
推荐奖励系统自动化从事件触发到幂等发放再到审计记录的完整奖励生命周期：
核心能力
双重奖励结构
当新用户通过推荐链接注册时，系统自动向双方发放奖励：
| 参与者 | 奖励类型 | 目的 |
|---|---|---|
| 邀请人 | 积分（例如 500） | 激励分享和推荐行为 |
| 新用户 | 积分（例如 200） | 鼓励平台参与的新人欢迎奖励 |
这种双重激励结构创造了强大的增长机制——现有用户有动力分享他们的推荐链接，而新用户在加入后立即获得价值，既提高了推荐量又提升了新用户满意度。
客户端推荐状态示例：
import { useQuery } from '@tanstack/react-query'
export function ReferralStatus() {
const { data } = useQuery({
queryKey: ['referral-stats'],
queryFn: () =>
fetch('/api/referrals/stats').then((r) => r.json()) as Promise<{
totalRewardsEarned: number
successfulReferrals: number
pendingRewards: number
}>,
})
return (
<div className="rounded-lg border p-4">
<h3 className="mb-3 font-semibold">你的推荐奖励</h3>
<dl className="grid grid-cols-3 gap-4">
<div>
<dt className="text-xs text-muted-foreground">已获得</dt>
<dd className="text-xl font-bold">{data?.totalRewardsEarned ?? '—'}</dd>
</div>
<div>
<dt className="text-xs text-muted-foreground">推荐数</dt>
<dd className="text-xl font-bold">{data?.successfulReferrals ?? 0}</dd>
</div>
<div>
<dt className="text-xs text-muted-foreground">待处理</dt>
<dd className="text-xl font-bold">{data?.pendingRewards ?? 0}</dd>
</div>
</dl>
</div>
)
}
可配置奖励管理
管理员可通过管理仪表板在 /dashboard/admin/credits/invite-reward 配置奖励参数：
- 邀请人奖励金额 — 设置奖励给推荐用户的积分数量
- 新用户欢迎金额 — 配置新受邀用户的欢迎奖励
- 奖励开关 — 在不影响现有邀请追踪的情况下全局启用或禁用奖励系统
- 发放历史 — 查看详细的交易日志，显示所有奖励发放及时间戳和用户归因
- 门槛配置 — 可选要求邀请人拥有活跃订阅才可发放奖励，防止滥用
幂等奖励处理
奖励系统将幂等性作为核心可靠性特性设计：
如果单个推荐被多次处理——无论是由于 webhook 重试、并发竞争条件还是数据库复制延迟——系统确保奖励恰好发放一次。这是通过在数据库中对推荐到奖励的映射强制执行唯一约束，结合奖励发放逻辑中的事务处理来实现的。
交易历史与审计线索
所有奖励操作都记录在交易日志中，提供完全的透明度：
- 奖励金额和类型分类（邀请人奖励 vs. 新用户欢迎奖励）
- 关联的推荐记录，包含邀请人和受邀人标识符
- 处理时间戳，按时间顺序准确排序
- 状态追踪（待处理、已完成、失败），附失败原因记录
- 管理员审核界面，用于需要时的人工对账
设计理念
双重激励增长模型
推荐奖励系统围绕双重激励结构设计，奖励推荐人和被推荐用户双方。这创造了一个强大的病毒式获客循环：现有用户因有形的积分奖励激励而成为品牌倡导者，新用户在加入时立即获得价值，从而提高推荐流量的转化率。可配置的奖励比例允许平台运营者根据其特定的增长经济学优化获客成本与推荐速度之间的平衡。
幂等性优先的可靠性
每次奖励发放都受幂等性保证的保护，通过在数据库级别对推荐到奖励映射实施唯一约束来强制执行。无论推荐事件由于 webhook 重试、并发竞争条件或系统故障被处理一次还是一百次，奖励恰好发放一次。这种幂等性优先的方法是系统可靠性的基础——它消除了整类发放错误，无需复杂的分布式锁定或外部协调。与 ReferralCandy 不同——它依赖于具有网络依赖性的外部 API 幂等性——我们的奖励处理使用您自己基础设施内的数据库级唯一约束，确保支付保证在网络分区时仍然有效。
可配置的奖励经济学
奖励金额、资格标准和发放条件均可通过管理仪表板完全配置，无需修改代码。这使得平台运营者可以运行实验——调整奖励规模、测试资格门槛或临时禁用奖励——并实时观察对获客指标的影响。系统的交易日志提供了计算推荐项目的单次获客成本和投资回报率所需的数据。
最佳实践
最优奖励规模
设置足够有吸引力以激励分享但又可持续的奖励金额。常见的比例是邀请人与新用户奖励之间的 2.5:1 比例（例如邀请人 500 积分，新用户 200 积分）。通过归因分析仪表板监控单次获客成本，并根据渠道效果调整奖励金额。
滥用预防
实施资格要求以防止滥用系统。常见的安全措施包括要求邀请人拥有活跃订阅或达到最低账户年龄后才能获得奖励。系统支持可通过管理仪表板启用的可配置门槛检查。
透明沟通
向邀请人和受邀人双方展示清晰的推荐奖励条款。用户仪表板应显示准确的奖励金额、发放条件和待处理奖励的当前状态。透明度建立信任，鼓励更多分享行为。
监控与优化
追踪关键的推荐指标——推荐转化率、平均每位获客奖励成本和推荐用户的终身价值。使用这些指标来优化奖励金额和资格标准。系统的审计线索提供了此分析所需的数据。
常见问题
推荐奖励系统如何工作？ 当现有用户分享其推荐链接且新用户通过该链接注册时，双方都会收到积分奖励。邀请人因成功推荐获得奖励，新用户因通过推荐加入获得欢迎奖励。
系统上线后能否更改奖励金额？
可以。奖励金额可通过管理仪表板在 /dashboard/admin/credits/invite-reward 配置。更改立即对所有未来推荐生效。历史推荐发放不受影响。
如果用户尝试自我推荐会发生什么？ 系统通过 IP 追踪和账户验证防止自我推荐。如果用户在注册时尝试使用自己的邀请码，系统拒绝该推荐且不处理任何奖励。
奖励对用户来说是否应纳税？ 税务影响取决于您所在司法管辖区以及奖励的性质（虚拟积分 vs. 真实货币）。请咨询您的法律团队，了解您运营地区推荐奖励的税务处理方式。
幂等性如何防止重复奖励？ 系统使用数据库级唯一约束，基于邀请 ID 和奖励类型的组合。如果同一推荐事件被处理两次，第二次尝试会因违反唯一约束而失败，不会创建重复奖励。
管理员能否手动调整奖励？ 可以。管理员可以通过积分系统的管理界面创建手动积分交易，在需要时调整奖励，例如补偿边界情况或处理追溯性奖励。
推荐效果有哪些报告可用？ 管理仪表板的推荐奖励部分提供发放历史、推荐成功率、总奖励发放量和按用户的推荐统计。这些数据可与归因分析系统交叉引用，进行全面的增长分析。
配置
通过管理仪表板在 /dashboard/admin/credits/invite-reward 管理推荐奖励。配置选项包括：
- 邀请人奖励金额（积分点数）
- 新用户欢迎奖励金额（积分点数）
- 全局启用/禁用开关
- 资格要求（订阅状态、最低账户年龄）
奖励通过积分系统发放，积分系统必须处于激活状态。核心奖励功能无需额外环境变量。
集成点
推荐奖励系统与以下 TanStack Ship 平台模块集成：