Civitai 推荐计划Referral Program v2设计全解消费触发的双赢奖励体系与工程实现【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai导读本文基于 docs/features/referral-program.md 的设计文档结合 Civitai 仓库中已落地的 referral.service.ts 实现完整拆解这套以消费spend而非注册signup为触发点的推荐奖励体系每个用户拥有专属可分享推荐码被推荐人消费后推荐人与被推荐人双方获利。你将掌握其 Token 经济模型、Blue Buzz 返佣与里程碑机制、结算状态机、退款chargeback处理策略、归属与欺诈日志体系、调试端点以及推荐订阅与付费订阅共存的队列式权益叠加方案。一、概述为什么把奖励从注册改为消费Civitai 的第一版推荐系统是注册即奖励signup-only但注册并不代表平台获得了真实收入。v2 的核心变化是奖励与真实收入事件绑定而非账号创建。一次完整的奖励链路如下被推荐人Referee通过带?ref_codeXYZ的链接访问 → Cookie 记录默认 30 天→ 注册时绑定UserReferral行 → 完成第一笔付费会员支付。推荐人Referrer在被推荐人每笔合格会员付款时获得Referral Tokens可在推荐商店兑换限时会员权益并在被推荐人购买 Buzz 时获得Blue Buzz 返佣。被推荐人在首次付费事件时获得一次性 Blue Buzz 奖励推荐人等级的月 Buzz 额的 25%。Goals设计目标通过同伴推荐peer advocacy驱动付费会员转化。让社区成员有不花现金也能获得高级权益的有机途径。激励具备 NSFW 生成能力的受众参与推荐通过 Blue Buzz 会员权益的组合。复用既有基础设施UserReferralCode、可兑换码服务、信号服务以降低构建成本。Non-Goalsv1 明确不做多级 / MLM 式级联奖励规避 FTC 金字塔骗局红线。现金 payout奖励只留在平台内Token、Blue Buzz。跨域推荐v1 仅限.com主域。主动欺诈拦截v1 只做日志记录供事后人工审查。二、机制总览从点击链接到奖励结算设计文档给出的完整机制流如下Referee flow: Visit link with ?ref_codeXYZ → cookie stored (5 days) // v1 中已提升为 30 天 Sign up (binds UserReferral row) Make first paid membership charge → Referee receives: 25% of tiers monthlyBuzz as Blue Buzz (one-time) → Referrer receives: 1-3 Referral Tokens (pending settlement) Each subsequent membership renewal (up to month 3) → Referrer receives: 1 token per paid month (tier-based: Bronze1, Silver2, Gold3) Each buzz purchase by referee → Referrer receives: 10% of purchase amount as Blue Buzz (pending settlement) Settlement: 7 days after event, reward moves from pending → settled Settled tokens can be spent in the Referral Shop Settled blue buzz is credited to referrers blue buzz account Token redemption: Referrer visits Referral Shop Spends tokens on membership-time bundles (tier × duration) Creates a CustomerSubscription with monthlyBuzz0 (perks only, no buzz stipend) Tokens expire 90 days after earn在源码实现中以上数值全部收敛为 constants.ts 中referrals配置对象referrals: { referralCodeMinLength: 6, referralCodeMaxCount: 1, // 每人仅一个推荐码自生成 cookieDurationDays: 30, // 归因 Cookie 有效期 settlementWindowDays: 7, // 结算窗口 tokenExpiryDays: 90, // Token 过期天数 minReferrerAccountAgeDays: 7, // 推荐人账号最低年龄 maxPaidMonthsPerReferee: 3, // 每个被推荐人最多计入 3 个付费月 tokensPerTier: { bronze: 1, silver: 2, gold: 3 }, pointsPerTierMonth: { bronze: 1_000, silver: 2_500, gold: 5_000 }, maxQueuedDays: 365, // 推荐权益排队上限防止刷到 2038 年 refereeBonusBuzzPct: 0.25, // 被推荐人首付奖励 月Buzz × 25% buzzKickbackPct: 0.1, // 推荐人返佣 被推荐人Buzz购买额 × 10% shopItems: [ ... ], // 推荐商店兑换项 milestones: [ ... ], // Blue Buzz 里程碑 }所有奖励的日期计算都基于这套常量settlementDate()在earnedAt上加settlementWindowDaysexpiryDate()加tokenExpiryDays并通过行内points快照snapshot at write time保证日后调整常量不会追溯重估历史奖励。三、Token 经济赚取、兑换、过期3.1 赚取规则被推荐人事件推荐人获得的 TokenBronze 会员付费月1Silver 会员付费月2Gold 会员付费月3每个被推荐人的付费月数上限3设计文档中有一个关键开放问题上限是每个被推荐人 3 个付费月还是每个被推荐人最多 3 个 Token最终决策锁定为前者——每个被推荐人最多计入 3 个付费月因此一个 Gold 被推荐人最多可为推荐人产出3 3 3 9个 Token。这与 referral.service.ts 中的实现一致recordMembershipPaymentReward在写入前检查ctx.paidMonthCount constants.referrals.maxPaidMonthsPerReferee超限时只记录一条membership_payment_over_cap归属日志并直接返回。3.2 兑换商店Referral Shop花费 Token授予权益12 周 Bronze 权益21 个月 Bronze 权益32 周 Silver 权益41 个月 Silver 权益52 周 Gold 权益61 个月 Gold 权益兑换创建的CustomerSubscription具有monthlyBuzz 0无 Buzz 津贴仅权益且currentPeriodEnd now duration。设计文档指出应复用redeemableCode.service.ts的既有模式。源码实现中兑换走的是redeemTokens({ userId, offerIndex })referral.service.ts在事务内用SELECT ... FOR UPDATE锁定用户所有Settled状态的 MembershipToken 行按expiresAt升序优先消耗最早过期的若余额不足则抛Insufficient tokens回滚整个事务——先授予权益、后扣减 Token任一环节失败都不会造成Token 被扣但权益没给。3.3 过期与预警Token 自赚取之日起90 天过期。每日 cronexpireSettledTokens做两件事对 7 天内EXPIRY_WARN_WINDOW_DAYS 7即将过期的用户按userId分组触发referral:token-expiring-soon信号并发送去重通知key 为referral-token-expiring:{userId}:{yyyy-mm-dd}避免每日 cron 重复轰炸。将已过期 Token 批量标记为Expired。值得注意的实现细节过期 Token 仍计入 lifetime points——过期只是阻断兑换用户历史上确实赚取过这些积分不应因此丢失里程碑进度referral.service.ts 的computeLifetimeReferralPoints注释明确说明这一点。3.4 与付费订阅的交互如果兑换者已有付费订阅兑换等级 付费等级作为独立的CustomerSubscription行叠加有效等级 max(paidTier, referralTier)会话用户取最高。兑换等级 ≤ 付费等级仍允许兑换但付费期内无实际增益且推荐订阅的currentPeriodEnd继续走时不暂停——用户在更高等级付费期内兑换低等级会浪费 Token。UI 会在这种情况下给出警告。3.5 徽章与 Buzz 津贴推荐授予的订阅不提供等级专属徽章显示徽章仍只跟随付费订阅每月 Buzz 津贴产品monthlyBuzz 0与付费等级绑定的 Creator Program 银行倍率。提供所有 feature-flag 门控的权益——NSFW 生成Blue Buzz、私有模型、优先生成、助手人格等。设计文档中的开放问题 3 已锁定此结论推荐订阅授予 Creator Program 倍率后续实现中因倍率实际生效还专门增加了 advanceReferralSubscriptions 中缓存失效逻辑见后文。四、Blue Buzz 返佣10% 与里程碑奖金4.1 返佣比例被推荐人每次购买黄色 Buzz 的 10% → 推荐人的 Blue Buzz。假设 $1 1000 Buzzconstants.buzz.buzzDollarRatio: 1000被推荐人买 $50 的 50k 黄色 Buzz推荐人赚 5k Blue Buzz。该返佣仅适用于 Buzz 购买黄色不适用于会员付款那部分只发 Token打赏收入、创作者收益或其他非购买性质的 Buzz 流转。实现中recordBuzzPurchaseKickbackreferral.service.ts还有一个隐藏门槛只有ctx.firstPaidAt已设置即被推荐人已经至少付过一次会员费才会产生返佣否则记录buzz_kickback_skipped_no_membership归属日志。这一设计有效阻止免费账号买 Buzz 无限刷返佣的漏洞——退款场景下见第六章firstPaidAt也会被清空。4.2 里程碑奖金推荐人通过返佣累计的终身 Blue Buzz触发一次性奖金终身累计奖金1,00050010,0002,50050,00015,000200,00050,0001,000,000250,000 Top Affiliate 装饰徽章里程碑是永久一次性的——每个用户每个里程碑最多命中一次终身累计数不会重置。首个里程碑1,000的校准依据是被推荐人一次 $10 的 Buzz 购买即可命中提供即时反馈。实现中awardMilestonesreferral.service.ts在每次 BuzzKickback 结算后触发通过事务创建ReferralMilestone行 MilestoneBonus奖励并利用unique([userId, threshold])约束天然防重100 万阈值还会通过grantCosmetics发放 Top Affiliate 徽章当前实现用最新创建的 Cosmetic 作为占位符等待专属设计。五、数据模型设计与落地的演进5.1 设计文档的原始建模设计文档给出了三张新表的 Prisma 建模ReferralTokenToken 奖励、ReferralBlueBuzzEarningBlue Buzz 返佣、ReferralMilestone里程碑并定义了枚举ReferralTokenStatuspending | settled | redeemed | expired | revoked。5.2 实际落地统一 ReferralReward 表从 referral.service.ts 的 importReferralRewardKind, ReferralRewardStatus来自~/shared/utils/prisma/enums看实际实现将 Token 与 Blue Buzz 奖励合并为一张统一的ReferralReward表用kind枚举区分RefereeBonus被推荐人首付欢迎奖励Blue BuzzBuzzKickback被推荐人 Buzz 购买返佣Blue BuzzMilestoneBonus里程碑奖金Blue BuzzMembershipToken会员 Token独立跟踪不发 Buzz。每种 kind 都有对应的奖励描述文案REWARD_DESCRIPTIONS并且所有 Blue Buzz 奖励都包含points字段——Referral Points推荐积分同时驱动里程碑阶梯与 Recruiter Score1 点 1 Blue Buzz会员月另有等级加权块bronze 1,000 / silver 2,500 / gold 5,000。对既有表的扩展与设计一致UserReferral增加firstPaidAt DateTime?防止首笔付费被重复奖励和paidMonthCount计数器UserReferralCode无需改动。5.3 Cookie 持久化变更设计文档明确原 Cookie 为 5 天对应ReferralsProvider.tsx:48v1 提升为30 天理由是点击链接、稍后购买的转化周期远超 5 天30 天是行业标准。落地后的 ReferralsProvider.tsx 使用constants.referrals.cookieDurationDays即 30计算过期时间并解析 URL 中的ref_id/ref_code/ref_source三个参数写入 Cookieref_code、ref_source、ref_landing_page且仅在用户尚未绑定推荐码!user?.referral时写入。六、信号事件Signal Events所有信号经 signal-client.ts 的signalClient.send({ userId, target, data })发送。设计文档要求在SignalMessages枚举中新增以下信号信号Target载荷触发时机referral:clickReferralClick{ count, last24h }链接点击的聚合日摘要referral:checkout-viewedReferralCheckoutViewed{ anonymous: true }携带推荐码者进入结账页每人每 5 分钟限 1 条referral:purchase-pendingReferralPurchasePending{ type: membership \| buzz, tokens?, blueBuzz?, settlesAt }购买成功、奖励待结算referral:settledReferralSettled{ type, tokens?, blueBuzz? }7 天期满、奖励可消费referral:milestoneReferralMilestone{ threshold, bonusAmount }终身 Blue Buzz 跨越阈值referral:tier-grantedReferralTierGranted{ tier, durationDays }成功兑换 Tokenreferral:clawbackReferralClawback{ reason, tokens?, blueBuzz? }退款 / 欺诈检测referral:token-expiring-soonReferralTokenExpiring{ count, expiresAt }Token 批量过期前 7 天客户端 hook 的用法useSignalConnection(SignalMessages.ReferralSettled, onSettled)位于 ReferralSignals.ts。实现中信号发送被封装为emitSignalreferral.service.ts失败时降级写入 Axiom 日志绝不阻塞主奖励流程。七、结算状态机与退款处理7.1 状态机event fires → PENDING (settlement timer starts, 7 days) │ ├─ 7 days elapsed, no chargeback → SETTLED │ │ │ ├─ user redeems tokens → REDEEMED │ └─ 90 days elapsed, unredeemed → EXPIRED (tokens only) │ └─ chargeback within 7 days → REVOKED (reward never credited) └─ chargeback AFTER 7 days → REVOKED deduct from future (or negative balance)实现中的settleDueRewardscron 批量捞取Pending且settledAt now的奖励每批 500 条逐条调用settleRewardRow。settleRewardRow的关键工程细节先授信、后改状态用updateMany({ where: { id, status: Pending } })做 CAScompare-and-swap抢占只有抢到count 0的调用者才继续Buzz 转账失败则把状态回滚为Pending并记录revokedReason留给下一轮 cron 重试——天然防止 cron 重复执行导致双花。从中央银行铸造Blue Buzz 奖励从REFERRAL_SYSTEM_ACCOUNT_ID 0中央银行铸造到接收者的蓝色账户toAccountType: blue绕过余额检查。文件头注释记录了一次历史事故曾用账户 -1蓝色账户发放导致约 190 笔奖励因余额不足被卡住referral-v2 #2178 的by-design 回归。7.2 退款Chargeback策略7 天内干净撤销——奖励从未进入推荐人余额无需追讨。7 天后推荐人可能已花掉。设计文档给出按成本从低到高的策略先从 pending/settled Token 余额扣除 → 不足则从未来收益扣除债务队列→ 仍不足则核销视为营销成本。最终 v1 决策开放问题 4、9 锁定v1 采用7 天窗口内撤销 pending 奖励 窗口后核销策略不实现债务队列。窗口后的损失写入欺诈日志表供人工审查推荐人不欠任何东西。实现中revokeForChargeback({ sourceEventId, reason })referral.service.ts按sourceEventId含referee-bonus:前缀的兄弟行找到所有 Pending/Settled 奖励已结算的 Buzz 奖励从推荐人蓝色账户扣回TransactionType.ChargeBack返还中央银行奖励标记为Revoked并触发referral:clawback信号关键对 MembershipToken 类奖励逐被推荐人递减其UserReferral.paidMonthCount若归零则清空firstPaidAt——否则退款后firstPaidAt仍置位会让推荐人继续在免费账号的 Buzz 购买上收返佣。整个递减过程用FOR UPDATE行锁防止并发退款互相丢失。八、归属Attribution与欺诈检测v1 按 Justin 的方向不做主动拦截只做日志供日后审查。每条奖励事件记录推荐人 被推荐人的userId、createdAt、emailDomain设备指纹一致性同设备 标记IP 匹配 / CIDR 重叠支付方式指纹StripePaymentMethod.fingerprint首次 payout 前被推荐人的订阅时长 3 个月 标记注册与首购间隔 1 小时 标记推荐人历史奖励对收入比率离群 标记。实现中所有事件写入 PostgresReferralAttribution表recordAttributionreferral.service.ts每行记录referralCodeIdFK 到UserReferralCode、refereeId、事件类型、Stripe 的 PI/invoice/charge ID、卡片指纹、IP 与 JSON metadata 大字段。事件类型包括membership_payment、membership_payment_over_capbuzz_kickback、buzz_kickback_skipped_no_membershipreferrer_too_young推荐人账号不足 7 天时记录索引设计(referralCodeId, createdAt)、(refereeId)、(paymentMethodFingerprint)、(ipAddress)、(stripePaymentIntentId)面向显示与该推荐码/卡片/IP 关联的所有内容这类审查查询。写入失败不影响主流程best-effort降级 Axiom 日志。Paddle 事件不归属Paddle 已弃用见 paddle.ts 头注释。九、UI 表面9.1 推荐仪表盘/user/referralsHero 区大号推荐码 复制按钮分享按钮Twitter、Reddit、Discord、复制链接实时计数器有人正在带着你的码查看结账页适用时。统计卡近 30 天总点击、成功转化付费的唯一被推荐人、终身 Blue Buzz、下一里程碑进度条。Token 面板可消费的 settled 余额、pending 数含结算 ETA、7 天内即将过期的警告、兑换CTA 打开商店弹窗。商店弹窗等级 × 时长选项网格与价格确认即创建推荐订阅。活动流匿名化有被推荐人订阅了 Silver——2 Token 待结算有被推荐人买了 10k Buzz——1k Blue Buzz 待结算里程碑达成终身 10k——2.5k 奖金。不展示任何被推荐人身份仅聚合信息。实现对应组件ReferralDashboard.tsx、ReferralDashboardFull.tsx、ReferralTimelineProgress.tsx 等。9.2 结账流程码输入结账页手动输入框若ref_codeCookie 已设则预填并锁定可清除/替换无 Cookie 则为可选空字段。有效码横幅展示被推荐人将获得的奖励。文案示例Using code XYZ. Youll receive 2,500 Blue Buzz on completion — enough for ~250 generations.奖励 selectedTier.monthlyBuzz * 0.25生成次数按现有配置的平均单次生成成本常量计算。文案不得提及成人/NSFW 内容保持通用。横幅渲染时向推荐人发出referral:checkout-viewed信号限流。实现对应组件ReferralCheckoutBanner.tsx通过monthlyBuzzByTier与 25% 比例实时计算奖励展示。9.3 注册与用户导航注册流程已通过 OnboardingBuzz.tsx 捕获ref_code保持现状新增首付后 toast你使用了推荐码——享受你的奖励吧用户菜单新增 Referrals 入口存在未消费的 settled Token 时图标显示角标。十、计划条款Program Terms独立页面/referrals/terms主 TOS 以单行引用链接。条款覆盖资格Civitai 账号状态良好推荐人账号至少 7 天龄才有资格赚取把刚注册的小号挡在门外。赚取规则被推荐人付费会员月前 3 个月发 Token被推荐人黄色 Buzz 购买返 10% Blue Buzz7 天结算。不可转让Token 与 Blue Buzz 不可转让、不可退款、无现金价值。过期Token 赚取后 90 天过期未使用即作废。禁止行为自动化欺诈、未披露的付费广告网络点击激励、被封禁/暂停账号使用推荐码。执行Civitai 可单方面撤回奖励、终止参与资格或封禁滥用者。修改Civitai 可提前 30 天通知后修改或终止计划。设计文档中的法律审查问题最终决定v1 自行起草样板条款不可转让、过期、反滥用条款正式法务审查等真实规模或新司法管辖区扩展时再做。十一、上线计划与监控11.1 功能开关与灰度使用 Flipt 开关referral-program-v2按用户粒度分阶段放量Internal仅 Civitai 团队5-10 人dogfood 1 周Alpha重度创作者 opt-in 等待名单100 人2 周Beta付费用户群 10%2 周监控欺诈指标GA全量用户。Kill switch开关关闭 不再产生新收益、既有余额保留、商店禁用。11.2 迁移与监控无需数据迁移旧版UserReferral行原样保留注册奖励已在代码中停用仅留注释。监控面Grafana每日 Token 赚取/兑换数、每日 Blue Buzz 返佣、Top 20 推荐人、欺诈标记率Axiom所有referral:*信号事件流ClickHousereferralAttribution表供欺诈分析查询。11.3 成功指标归因于推荐的付费会员占比v1 目标 5%点击 → 被推荐人注册 → 付费会员的转化率Blue Buzz 返佣池占黄色 Buzz 收入的比例计划成本指标被推荐人 vs 非被推荐人群组的流失差异churn delta。十二、实现阶段划分阶段内容Phase 1核心赚取 结算后端DB 迁移、ReferralToken/ReferralBlueBuzzEarning/ReferralMilestone表实际合并为ReferralReward、Stripe/Paddle webhook 钩子、7 天结算 cron、退款逻辑、信号发射Phase 2商店 兑换商店 tRPC router、复用redeemableCode.service.ts授予等级、兑换 UI 弹窗Phase 3仪表盘 信号/user/referrals页面、客户端信号 hook、点击跟踪 匿名活动流、用户导航集成Phase 4结账归属ref_codeCookie 提升至 30 天、结账横幅、referral:checkout-viewed信号接线Phase 5欺诈日志 运维ClickHousereferralAttributionschema、审核仪表盘、人工审查 runbookPhase 6条款 营销条款页、邮件 / 应用内推广、Discord 公告十三、调试端点不花钱模拟整个计划POST /api/testing/referrals是隐藏调试端点由WEBHOOK_TOKEN头门控用于在真实付费前实验整套流程export Tyour WEBHOOK_TOKEN curl -s -X POST https://civitai.com/api/testing/referrals \ -H Authorization: Bearer $T \ -H Content-Type: application/json \ -d {action:dump,userId:YOUR_USER_ID} | jq支持的 actionaction必填作用dumpuserId完整推荐状态码、UserReferral、奖励、里程碑、兑换、归属、活跃订阅、余额bind-codeuserId, code把推荐码绑定到用户的UserReferralgrant-tokensuserId, tier, tokens插入 MembershipToken 奖励settleImmediatelytrue跳过 7 天等待grant-blue-buzzuserId, blueBuzz插入 BuzzKickback 奖励enqueue-chunkuserId, tier, durationDays向用户的活跃推荐订阅队列推入一个 chunksimulate-membership-paymentrefereeId, tier模拟 Stripe 触发invoice.paid执行recordMembershipPaymentRewardsimulate-buzz-purchaserefereeId, blueBuzz执行recordBuzzPurchaseKickbacksimulate-chargebacksourceEventId执行revokeForChargebacksettle-alluserId作用域快进 Pending 奖励并运行结算 cronadvance-subsuserId可选使推荐订阅过期并运行推进 cronexpire-tokensuserId使该用户所有 settled Token 过期resetuserId, confirmtrue清空用户全部推荐数据回到干净状态典型实验流程# 1. 给自己 6 个已结算 Token curl ... -d {action:grant-tokens,userId:123,tier:gold,tokens:6,settleImmediately:true} # 2. 访问 /user/referrals —— 兑换1 个月 Gold 权益 # 3. 入队一个 Bronze chunk 测试队列晋升 curl ... -d {action:enqueue-chunk,userId:123,tier:bronze,durationDays:14} # 4. 快进 Gold 过期 → Bronze 接管 curl ... -d {action:advance-subs,userId:123} # 5. 清空重来 curl ... -d {action:reset,userId:123,confirm:true}该端点的访问本身有测试保障见 route-guards.testing-stall.test.ts 与 testing-route-access.test.ts 中对/api/testing/referrals的门控断言。十四、重叠堆叠方案推荐权益与付费订阅共存CustomerSubscription有unique([userId, buzzType])约束付费订阅使用yellow.com、green.green、blue.red。若推荐授予使用其中任意一种就会与同 flavor 的付费订阅冲突。v1 方案推荐授予写入CustomerSubscription.buzzType referral。该列是String非枚举会话用户遍历所有订阅行通过constants.memberships.tierOrder取跨 buzzType 的最高等级——一个用户可以同时持有付费 yellow 付费 green 推荐 Goldfeature flags / 权益检查按 Gold 生效。这与 referral.service.ts 中的REFERRAL_BUZZ_TYPE referral常量完全对应。14.1 队列式权益Chunk Queue用户已有活跃推荐订阅时再次兑换的行为同等级或更低等级从现有结束日期起currentPeriodEnd延长durationDays更高等级productId切换到新等级、currentPeriodStart重置为 now、currentPeriodEnd now durationDays。实现用tier-time chunks队列解决了一个被明确点名的漏洞防止堆廉价 Bronze 一个 Gold 全程 Gold的利用。grantReferralSubscriptionreferral.service.ts把当前活跃 chunk 的剩余天数 队列中所有 chunk 新兑换合并成 pool经collapseTierQueue排序折叠纯函数见 referral.service.test.ts 的collapseTierQueue测试组按tierOrder降序、同等级连续项合并、零时长项丢弃最高等级最先激活到期后由advanceReferralSubscriptionscron 晋升下一 chunk。同时设了maxQueuedDays: 365的硬上限防止热门推荐人排队数年权益最终触发 Stripe 的 2038 日期上限。行锁FOR UPDATE保证并发兑换与推进 cron 不会互相覆盖队列元数据。14.2 倍率缓存失效的坑advanceReferralSubscriptions中有一个值得借鉴的运维细节推荐订阅推进导致等级变化后必须调用invalidateSubscriptionCaches刷新用户倍率缓存——userMultipliersCache有 1 天 TTL 且该路径无其他失效点若不显式失效降级或取消的推荐订阅会继续按旧倍率多付最多 24 小时的 BuzzClickUp 868kv5az9。失效失败会记录到 Axiom绝不静默吞掉。14.3 v2 后续不阻塞上线增加activatesAt字段或 metadata 标志让推荐授予可在付费订阅过期后排队激活仪表盘在兑换等级 ≤ 活跃付费等级时给出警告支持多个排队中的推荐授予metadata 堆叠每次过期后推进。十五、通知体系推荐奖励事件同时触发信号实时 UI 更新与通知持久化应用内 订阅邮件事件信号通知待结算购买referral:purchase-pending—推荐人奖励结算referral:settledreferral-reward-settled被推荐人欢迎奖励结算—referral-welcome-bonus里程碑达成referral:milestonereferral-milestone-hitToken 7 天后过期referral:token-expiring-soonreferral-token-expiring每日 cron按用户×过期日去重兑换授予等级referral:tier-granted—点击 / 查看结账referral:click、referral:checkout-viewed—退款撤销referral:clawback—实现中settleRewardRow在结算成功时按奖励 kind 分流RefereeBonus发referral-welcome-bonus被推荐人即时可见跳过 7 天窗口——平台欢迎礼无退款路径无等待必要且结算用 CAS 保证并发 cron 不会双发其余发referral-reward-settled通知 ReferralSettled信号。十六、关键决策复盘开放问题 → 锁定结论设计文档末尾的开放问题及其最终决策值得作为团队决策记录每人上限3 个付费月/被推荐人Gold 最多 9 Token。Cookie TTL5 → 30 天。推荐订阅的权益范围授予 Creator Program 倍率、NSFW Blue Buzz、私有模型、优先生成排除月 Buzz 津贴与等级徽章。退款强度7 天窗口内撤销 pending 奖励窗口后核销不做债务队列。条款法务v1 自行起草正式法务审查延后。返佣比例锁定 10%。推荐码数量每用户单一自动生成码 管理员可为特殊用户创建自定义码referralCodeMaxCount降为 1自定义码复用UserReferralCode表v1 通过管理员 DB 更新覆盖码串如X3K7P9 → JUSTINM。被推荐人奖励锁定为 C 方案——首次付费会员时奖励该等级月 Buzz 的 25% 为 Blue BuzzBronze 2.5k / Silver 6.25k / Gold 12.5k并在结账时展示作为转化杠杆而非事后惊喜零现金成本。窗口后退款核销欺诈表记录推荐人不欠款。自定义码管理 UXv1 用 DB/脚本v2 再做审核后台表单。被推荐人奖金金额随等级缩放Product.metadata.monthlyBuzz * 0.25仅首次付费续费不给。结账码注入通过ReferralCheckoutBanner在/pricing实现Stripe 结账会话经subscription_data.metadata携带ref_code在invoice.paidwebhook 上对账。结语Civitai 推荐计划 v2 是一套典型的收入事件驱动增长工程用统一的ReferralReward表 kind 枚举承载两类资产Token 与 Blue Buzz用 7 天结算窗口 CAS 抢占保证奖励发放的幂等与安全用buzzTypereferral的独立订阅行与 chunk 队列解决多订阅叠加的建模难题用ReferralAttribution全量日志为未来的自动化风控留足数据。对于任何希望搭建消费触达 平台内激励型推荐系统的团队这份设计文档与其源码落地是极佳的对照范本设计上的每一个待确认都对应着实现里的一个明确常量或分支。延伸阅读设计全文见 docs/features/referral-program.md核心实现见 referral.service.ts参数配置见 constants.ts测试覆盖见 referral.service.test.ts。【免费下载链接】civitaiA repository of models, textual inversions, and more项目地址: https://gitcode.com/GitHub_Trending/ci/civitai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考