联盟分销

vibestrap 在一个 config 开关后面提供五种联盟方案：三家 SaaS（Affonso、Rewardful、Tolt）、 内置 internal 佣金跟踪器、以及 none。internal 适配任何支付 provider—— 因为它读的是 vibestrap 已经写好的归一化付款事件，不用再额外接什么。

​

前置条件

• SaaS provider：去对应平台注册账号，拿 public API key 或 program ID。
• internal：什么都不用。affiliate_referral 和 affiliate_commission 两张表已经在 schema 里（src/db/affiliate.schema.ts），pnpm db:push 一起迁移。
• 已经配好支付 provider（Stripe、Paddle、Lemon Squeezy 或 Creem 任一）。

​

一步步配置（internal）

1. 在 src/config/site.ts 启用 internal：
   affiliate: {
     enable: true,
     provider: 'internal',
     internalCommissionPct: 20,    // 付款金额的百分比
     referralCookie: 'vbs_ref',    // ?ref=CODE 落地后写的 cookie 名
     referralCookieDays: 60,
   },
   
2. 还没建表就先同步 schema——联盟相关表本来就在默认 schema 里：
   pnpm db:push
   
3. 就这样。流程全自动：
   • 访客打开 ?ref=CODE → middleware 写 vbs_ref cookie。
   • 注册 → recordSignupReferral(userId) 写一行到 affiliate_referral（userId 幂等，重复调用 no-op）。
   • 付款 → 支付 webhook 调 recordCommission()，读出 referral，按你设定的百分比 插一行到 affiliate_commission。
4. 自己做一个 payout 看板——vibestrap 不带。SQL 大致这样：查 affiliate_commission WHERE status = 'pending' 按 referrer_code 分组， 走 Stripe Connect / 转账 / 任何方式付款，再 UPDATE … SET status = 'paid', paid_at = now()。

​

一步步配置（SaaS provider）

1. 在 src/config/site.ts 选 provider：
   affiliate: { enable: true, provider: 'rewardful' },
   
2. 在 .env.local 配对应 env 变量：
   NEXT_PUBLIC_AFFONSO_PROGRAM_ID=...   # Affonso
   NEXT_PUBLIC_REWARDFUL_API_KEY=...    # Rewardful
   NEXT_PUBLIC_TOLT_API_KEY=...         # Tolt
   
3. 在 provider 后台把支付网关接上（Rewardful/Tolt 走 Stripe Connect、 Affonso 走 Paddle 集成等）。SaaS provider 直接从支付网关读事件， vibestrap 不为 SaaS provider 转发任何东西。
4. 重启 pnpm dev 让 public env 生效。

​

怎么挑

​

验证生效（internal）

1. 无痕窗口访问 https://your.app/?ref=alice。
2. devtools → Application → Cookies，确认 vbs_ref=alice，过期时间 60 天。
3. 注册账号。然后查库：
   SELECT * FROM affiliate_referral WHERE referrer_code = 'alice';
   
4. 买点东西。再查：
   SELECT * FROM affiliate_commission WHERE referrer_code = 'alice';
   
   应该有一行，commission_cents = amount_cents * 0.20。

​

常见坑

1. Safari ITP 拦 cookie。同域 ?ref= 落地写的 first-party cookie 没事； 但如果你用跨域跳转（营销子域 → 应用子域），cookie 会被丢。把 referral 落地页 保持跟注册页同 eTLD+1。
2. 退款不会自动反向佣金。v0.1 没自动反向——要么手动插一行退款记录 （commission_cents 写负值，status 设 cancelled），要么在 payout 查询里 UPDATE … SET status = 'cancelled'。
3. 自我推荐。当前没有限制用户用自己的 code。在乎的话在 recordCommission 加一行守卫：if (referral.userId === input.userId) return;。
4. 从 internal 切到 SaaS provider。SaaS provider 在自己后端记账—— affiliate_commission 里的历史数据原地保留，只有新付款才会被 SaaS provider 跟踪。
5. cookie 名冲突。如果你的买家自己加了一些用 vbs_* 前缀的统计 cookie， 把 referralCookie 改成你品牌专属的名字。

​

官方文档

• Affonso：affonso.io/docs
• Rewardful：help.rewardful.com
• Tolt：docs.tolt.io
• 内置 schema：src/db/affiliate.schema.ts
• 内置工具函数：src/affiliate/track.ts