运营联盟推广计划
在管理后台设置计划条款、为推广者发放推荐码、把推广订单转成佣金并审核提现。
联盟推广模块为推广者发放推荐码,把他们带来的订单转成佣金,并记录你对每笔提现申请的决定。提现由人工审核,模块不会实际转账。
准备工作
- 一个能在本地运行的项目,见快速开始。
affiliate模块已经在底座仓库里;pnpm db:bootstrap-super-admin会写入affiliates.read、affiliates.write权限和默认推广计划。 - 管理员账号:
affiliates.read用于打开页面,提交任何表单还需要affiliates.write。 - 推广者的用户 ID,即其
/admin/users/<id>地址的最后一段。
侧边栏没有推广入口,请直接访问 /zh/admin/affiliates(英文后台为 /admin/affiliates)。
授予推广权限
分配 Commerce Manager 角色
进入 概览 → 用户(/admin/users/dashboard),打开用户详情,点击 角色,勾选 Commerce Manager 后点击 保存角色。该角色还包含订单、订阅、产品、授权和积分权限。
或者把权限加到自己的角色
进入 运营 → 角色(/admin/roles),在角色上点击 编辑,在 权限 的 Other 分组中勾选 affiliates.read 和 affiliates.write,点击 保存角色。
设置计划条款
默认计划:佣金 20%,Cookie 窗口 30 天,最低提现 $50.00,币种 USD。
打开计划设置
打开 计划设置 标签页(/zh/admin/affiliates/settings),卡片中显示当前条款。
填写计划条款
- 佣金比例 (%):按订单金额计算佣金的比例,例如
20,不能超过 100%。 - Cookie 窗口 (天):1 到 365。只有在推荐创建后的这些天数内才能记录转化。
- 最低提现金额:可接受的最小提现申请金额,例如
50.00。 - 币种:三位字母的 ISO 4217 代码,例如
USD。 - 状态:进行中,或 已暂停(不再记录转化,也不接受提现申请)。
保存
点击 保存计划设置,页面显示 计划设置已保存并记录审计日志。
新条款作用于之后的转化和提现申请,已记录的佣金金额不变。
创建推荐码
找到创建推荐表单
在 总览 或 推荐 标签页找到 创建推荐 表单。
填写表单
- 推广用户:推广者的用户 ID。
- 推荐码:推广者对外分享的码。保存时会转成大写并把空格换成连字符,
partner acme会保存为PARTNER-ACME。 - 被推荐邮箱:可选。
点击 创建推荐。推荐码已存在时会保留原记录,且不报错。
记录转化
结账流程不会自动把订单归因到推荐码,所以需要逐笔记录推广订单。
确认订单已支付
在 商业化 → 订单(/admin/orders)中查看该订单。
填写记录转化
在 佣金 或 总览 标签页填写 推荐码、订单 ID 和 订单金额 cents($290.00 填 29000),点击 记录转化。
佣金按订单金额乘以计划比例向下取整,初始状态为待审核。
如果想自动归因,在服务商 Webhook 确认订单后,从你的结算代码调用服务:
import { recordConversion } from "@/server/services/affiliate-operations.service";
await recordConversion({
referralCode: "PARTNER-ACME",
orderId: order.id,
orderAmountCents: order.amountCents,
});审核提现
提现申请显示在 提现 标签页。后台没有创建提现申请的页面,提现申请由你自己的服务端代码创建。
找到提现 ID
从 提现 标签页表格的 提现 列复制。
做出决定
进入 审核 标签页,填写 提现 ID 和 审核备注,点击 批准提现 或 拒绝提现。保存时审核人记为你。
给推广者打款
通过你自己的支付渠道打款。模块只记录审核决定。
验证
- 用你自己的用户 ID 和推荐码
TEST-PARTNER创建一个推荐。 - 为
TEST-PARTNER记录一笔转化,订单金额 cents 填30000。 - 按默认 20% 比例,佣金 出现一笔 $60.00 的待审核佣金,推荐 中该推荐显示为已转化,安全 → 审计(
/admin/audit)记录了这两次操作。
在仓库中运行 pnpm validate:affiliate。
常见问题
出现 "Affiliate program is not configured",或页面显示「暂无 Affiliate 记录」
推广计划还不存在。运行 pnpm db:seed-baseline 创建默认计划;再次运行不会覆盖你的设置。
出现 "Referral code is not active"
没有使用该推荐码的推荐。比对前推荐码会去空白、转大写、空格改连字符,请在 推荐 标签页核对。
出现 "Affiliate program is paused; …"
计划设置 中的 状态 为 已暂停。改为 进行中 并保存。
出现 "Conversion is outside the N-day attribution window for this referral."
推荐创建时间已超过 Cookie 窗口 (天)。请使用较新的推荐,或调大 Cookie 窗口。
出现 "Payout amount is below the program minimum of N cents."
申请金额至少要达到 最低提现金额,或在 计划设置 中调低最低金额。