运营联盟推广计划

在管理后台设置计划条款、为推广者发放推荐码、把推广订单转成佣金并审核提现。

联盟推广模块为推广者发放推荐码,把他们带来的订单转成佣金,并记录你对每笔提现申请的决定。提现由人工审核,模块不会实际转账。

准备工作

  • 一个能在本地运行的项目,见快速开始。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 确认订单后,从你的结算代码调用服务:

src/server/services/example.service.ts
import { recordConversion } from "@/server/services/affiliate-operations.service";

await recordConversion({
  referralCode: "PARTNER-ACME",
  orderId: order.id,
  orderAmountCents: order.amountCents,
});

审核提现

提现申请显示在 提现 标签页。后台没有创建提现申请的页面,提现申请由你自己的服务端代码创建。

找到提现 ID

从 提现 标签页表格的 提现 列复制。

做出决定

进入 审核 标签页,填写 提现 ID 和 审核备注,点击 批准提现 或 拒绝提现。保存时审核人记为你。

给推广者打款

通过你自己的支付渠道打款。模块只记录审核决定。

验证

  1. 用你自己的用户 ID 和推荐码 TEST-PARTNER 创建一个推荐。
  2. 为 TEST-PARTNER 记录一笔转化,订单金额 cents 填 30000。
  3. 按默认 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."

申请金额至少要达到 最低提现金额,或在 计划设置 中调低最低金额。

参考

下一步