邀请系统
TanStack Ship 邀请系统，支持用户推荐、唯一邀请码、积分奖励和被邀请人管理。
概述
TanStack Ship 的邀请系统使现有用户能够邀请新用户加入平台，通过口碑传播推动有机增长。每位用户获得一个唯一的邀请码和推荐链接。当邀请促成新注册时，邀请人和新用户都会获得积分奖励。
作为 TanStack Ship 平台的一部分，邀请模块与积分系统（奖励发放）、邮件营销系统（邀请投递）和认证系统（使用邀请码注册）集成。
设计流程
邀请系统编排从邀请码生成到奖励发放的完整推荐旅程，确保每个阶段的幂等处理：
核心能力
邀请码
每位用户在注册时自动分配一个唯一的邀请码：
- 自动生成 — 为每个用户创建唯一码
- 用户可见 — 在用户的账户设置中显示（
/dashboard/account/invite） - 优惠码兼容 — 可在注册时作为优惠码使用
- 推荐链接 — 可嵌入推荐链接中方便分享
邀请码格式设计为人类可读，方便口头分享。
示例 — 推荐链接中的邀请码：
https://yourplatform.com/signup?ref=INVITE_ABC123
客户端邀请分享示例：
import { useQuery } from '@tanstack/react-query'
export function InviteCard() {
const { data } = useQuery({
queryKey: ['my-invite'],
queryFn: () =>
fetch('/api/invitations/my-code').then((r) => r.json()) as Promise<{
code: string
referralLink: string
rewardAmount: number
totalInvites: number
}>,
})
return (
<div className="rounded-lg border p-4">
<p className="text-sm text-muted-foreground">你的推荐链接</p>
<p className="mt-1 font-mono text-sm">{data?.referralLink ?? '—'}</p>
<div className="mt-3 grid grid-cols-2 gap-4">
<div>
<p className="text-xs text-muted-foreground">每次邀请奖励</p>
<p className="text-lg font-bold">{data?.rewardAmount ?? '—'} 积分</p>
</div>
<div>
<p className="text-xs text-muted-foreground">成功邀请</p>
<p className="text-lg font-bold">{data?.totalInvites ?? 0}</p>
</div>
</div>
</div>
)
}
推荐链接
每个用户拥有个性化的推荐链接，编码了其邀请码：
- 自动将新注册归因于邀请人
- 可通过邮件、社交媒体或即时通讯应用分发
- 追踪成功转化和待处理邀请
- 结合 UTM 参数用于营销归因
奖励系统
当新用户通过邀请注册时，双方受益：
- 邀请人获得 — 积分奖励（可配置金额，例如 500 积分）
- 新用户获得 — 欢迎积分奖励（例如 200 积分）
- 奖励幂等处理——无重复支付
- 完整交易历史可审计
奖励金额可在管理面板中按活动配置。
管理员管理
管理员可从以下位置配置和监控邀请系统：
/dashboard/admin/credits/invite-reward— 配置奖励金额和限制/dashboard/admin/users— 查看每个用户的邀请统计- 邀请指标仪表板 — 追踪总邀请数、转化率和奖励支出
设计理念
双重激励架构
邀请系统构建于双重激励模型之上，邀请人和新用户都能从成功推荐中获得价值。这创造了一个强大的病毒式循环：现有用户因获得积分奖励而有动力分享邀请码，新用户因欢迎奖励而愿意使用邀请码。奖励比例可配置，使平台运营者能够将增长机制调整到符合其单位经济效益。与 Friendbuy 等独立推荐平台不同——它们作为外部 SaaS 运行，使用独立的奖励数据库和基于 webhook 的支付集成——我们的邀请系统在您自己的积分基础设施内直接处理奖励，奖励流程中无需任何第三方 API 调用。
幂等奖励处理
每次奖励发放都受幂等性保证的保护——每个邀请码只能用于一次注册，通过数据库级别的唯一约束强制执行。这防止了最常见的发放错误：由重试、并发注册或竞争条件导致的重复奖励。系统记录每次奖励尝试（成功或拒绝），提供完整的审计追踪用于问题排查。
无摩擦引导
邀请码具有双重用途：标识推荐人，并可在注册时作为优惠码使用。这种双用途设计减少了注册摩擦——拥有邀请码的用户只需在注册表单中一起输入，无需单独的推荐流程。系统也支持无需邀请码的开放注册，确保邀请机制推动增长而不制造进入障碍。
最佳实践
激励双方
双重奖励系统（同时奖励邀请人和被邀请人）显著提高转化率。配置奖励使双方都能看到明确的价值。
社交分享集成
鼓励用户在社交媒体上分享推荐链接，提供带有追踪链接和 UTM 参数的预格式化帖子。
监控奖励滥用
设置合理的奖励限制，监控可疑模式（例如单个用户从同一 IP 生成大量邀请）。系统记录所有邀请活动以供审计。
常见问题
用户如何获取其邀请码？
邀请码为每位用户在注册时自动生成，并在其账户设置下的 /dashboard/account/invite 中显示。
没有邀请码的新用户可以注册吗？ 可以，注册向所有用户开放。邀请码提供可选的推荐归因和奖励。
奖励如何发放？ 奖励以积分形式记入邀请人和新用户的账户。积分可用于订阅购买或其他平台功能。
如何防止同一推荐产生重复奖励？ 系统使用幂等操作——每个邀请码只能用于一次注册，防止重复支付。
配置
奖励金额可在管理面板中配置，位于 /dashboard/admin/credits/invite-reward。邀请系统需要：
- 用户认证（邀请人必须登录）
- 用于邀请投递的邮件服务（可选，通过邮件营销模块）
- 用于奖励发放的积分系统
除了标准平台配置外，不需要额外的环境变量。