销售产品和方案

你的产品带着价格出现在前台;买家购买后获得授权,并用 GitHub 用户名激活。

商店的售卖内容在后台定义。产品是买家获得授权的对象。方案是该产品在某一种语言下的一个价格。结账始终按方案上保存的价格收费。

准备工作

  • 拥有 products.read 和 products.write 的管理员账号,内置的 Commerce Manager 角色已包含这两项。
  • 要收取真实款项,需要先接入支付服务商,见 接入支付服务商。

从预置目录开始

刚完成迁移的数据库没有任何商品,店面是空的。先写入售卖站自带的目录(Kernlift Premium 会员和各个业务模板),然后在此基础上修改:

pnpm db:seed-storefront

该命令只插入缺失的行,重复执行不会产生变化,也不会覆盖你改过的文案与价格。预置价格只是示例,请按下面的步骤改成自己的定价。目录定义在 scripts/db/storefront-catalog.ts,售卖自己的产品时替换这个文件。

创建产品

打开表单

进入 商业化 → 产品(/admin/products),点击 新建产品。

描述产品

  • 键:稳定的标识,只能使用小写字母、数字、连字符或下划线,例如 cms。保存后不能修改。
  • 类型:底座 即会员商品(附带底座仓库,并解锁会员价);模板 是单独出售的业务模板。模块 和 全家桶 保留给按那种方式售卖的目录。
  • 状态:在售 的产品会在前台列出;隐藏 和 下架 不会。
  • 交付仓库(owner/name):买家激活后被邀请进入的 GitHub 私有仓库,例如 kernlift/image-studio。没有填写的商品会显示为尚未开放,无法购买。
  • 依赖(逗号分隔的产品键) 与 全家桶(持有者可使用全部在售产品):会员和模板留空、不勾选。
  • 每种语言的 名称、一句话卖点 和 描述。

保存

点击 保存产品,页面会打开该产品,以便继续添加方案。

添加方案

每个方案是一种语言下的一个价格,所以同时以英文和中文销售的产品,每种语言各有一行方案。

业务模板在每种语言下有两个方案:<key>-lifetime 是任何人都能支付的原价,<key>-member 是会员价。键以 -member 结尾的方案只有持有会员授权的账号可以结账,否则服务端会拒绝。

新建方案

在产品页面的 定价方案 卡片中点击 + 方案键。要编辑已有方案,点击它的按钮(显示为 方案键 · 语言)。

设置价格

  • 方案键(例如 pro_monthly)和 语言,保存后都不能修改。
  • 价格(分) 和 币种,例如 4900 和 usd。
  • 周期:按月、按年、终身 或 一次性,显示在价格旁边。
  • 结账模式:payment 为一次性收费,subscription 为周期性收费。Stripe 创建的订阅按月计费。
  • 包含积分:该方案的订单付款后发放一次的积分,见 用积分对用量计费。
  • 方案状态:active 可以购买,deferred 不能购买。

填写卡片文案

填写 名称、描述、按钮文案 和 按钮链接,可选填 AI 额度说明。在 功能列表(每行一项,以 - 开头表示不包含) 中每行写一项功能。

保存

点击 保存方案,页面显示 方案已保存。,结账立即使用新价格。每种语言重复一次。

产品在哪里展示

只有 状态 为 在售 的产品才会列出。/pricing 用一张卡片展示会员,并列出各模板的原价和会员价。访问者是会员时结账用会员价方案,否则用原价方案。访问者语言下没有价格大于零的启用方案时显示 暂未定价。

了解购买会获得什么

服务商确认付款后,买家会获得:

  • /app/billing 中的发票;subscription 方案还会生成一条订阅。
  • 方案的 包含积分,每笔订单只发放一次。
  • /app/licences(已购模板)中该方案产品的授权。

拿到授权还不等于拿到代码。买家在该页面填写自己的 GitHub 用户名并点击 激活,售卖站随即把该账号以只读权限邀请进商品的交付仓库。用户名在首次激活后不可更改;GitHub 的邀请 7 天后过期,可以在同一页面重新发送。

激活即视为交付:授权已激活的订单不能再退款;从未激活的订单可以退款,全额退款会撤销它的授权。在 商业化 → 授权 中撤销一条已激活的授权,会把该账号移出仓库。

邀请由你保存在 商业化 → 产品 页「GitHub 交付」区域的 GitHub 令牌发出,令牌需要对每个交付仓库有管理权限。没有令牌时,买家激活会被告知交付尚未配置,且不会记录任何状态。

要不经购买直接授予授权,在 商业化 → 授权(/admin/licences,需要 licences.write)中使用 授予授权。账号不能重复购买已持有的商品。

在自己的页面添加购买按钮

定价卡片会向结账 API 发起请求,你也可以在任意已登录页面这样做。请原样传入方案的价格、币种和模式,值不一致的请求会被拒绝。

src/components/billing/buy-button.tsx
const response = await fetch("/api/billing/checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    planKey: "growth",
    checkoutMode: "subscription",
    amountCents: 9900,
    currency: "usd",
    locale: "zh",
  }),
});
const result = await response.json();

if (response.status === 409 && result.message) {
  // result.status 为 unknown_plan、plan_inactive、amount_mismatch、
  // product_mismatch、membership_required 或 already_owned
  throw new Error(result.message);
}
if (result.checkoutUrl) window.location.assign(result.checkoutUrl);

成功时 API 返回 201 和服务商站点上的 checkoutUrl。付款后买家回到 成功 URL,查询参数中带有 billing_order_id、billing_status 和 provider。不要把这些参数当作付款凭证,应以订单状态为准。

验证

在每种语言下打开 /pricing,确认显示了方案的价格。用测试卡购买,然后在 商业化 → 订单 中确认订单已付款,并在买家的 /app/licences 中看到可激活的授权。pnpm validate:github-delivery 检查会员价、激活、退款规则与撤销;pnpm validate:billing 检查结算只发放一次方案积分。

常见问题

产品没有出现在前台

产品的 状态 不是 在售。改为 在售 并点击 保存产品。

卡片显示暂未定价

该语言下没有价格大于零、状态为 active 的方案。为该语言添加或修改方案。

结账返回 409 和 amount_mismatch

请求中的金额、币种或模式与方案不一致。请原样传入方案的值。在后台修改方案后,期望金额立即变化。

结账返回 409 和 membership_required

请求使用了会员价方案(<key>-member),而账号没有会员授权。买家可以先成为会员,或用原价方案购买该模板。

结账返回 409 和 already_owned

账号已持有该商品的有效授权。请引导买家到 /app/licences 激活。

激活时提示交付尚未配置

商品没有填写 交付仓库,或没有保存 GitHub 令牌。在 商业化 → 产品 中补齐两者,再用「验证已保存的令牌」确认 GitHub 接受该令牌。

参考

下一步