Creem 接入

Creem 是 Starter 内置的两个支付适配器之一。该集成负责创建托管结账、生成客户门户链接、安排订阅取消，并把带签名的 Webhook 统一转换成与 Stripe 相同的账单事件。

1. 创建商品

为应用展示的每个订阅周期和积分包分别创建 Creem 商品。默认商品目录需要以下配置：

CREEM_PRODUCT_STARTER_MONTHLY=prod_xxx
CREEM_PRODUCT_STARTER_ANNUAL=prod_xxx
CREEM_PRODUCT_PRO_MONTHLY=prod_xxx
CREEM_PRODUCT_PRO_ANNUAL=prod_xxx
CREEM_PRODUCT_CREDITS_SMALL=prod_xxx
CREEM_PRODUCT_CREDITS_MEDIUM=prod_xxx
CREEM_PRODUCT_CREDITS_LARGE=prod_xxx

Enterprise 和落地页商品的环境变量只是扩展点，并不能证明这些商品已经可以销售。Enterprise 不在内置方案目录中，示例落地页权益也必须先实现自定义履约，才能启用结账。

2. 配置测试模式

NEXT_PUBLIC_ENABLE_PAYMENTS=true
PAYMENTS_PROVIDER=creem

CREEM_API_KEY=creem_test_xxx
CREEM_API_BASE=https://test-api.creem.io
CREEM_WEBHOOK_SECRET=replace_with_the_endpoint_signing_secret
# CREEM_SIGNATURE_HEADER=X-Creem-Signature

CREEM_PRODUCT_STARTER_MONTHLY=prod_xxx
CREEM_PRODUCT_STARTER_ANNUAL=prod_xxx
CREEM_PRODUCT_PRO_MONTHLY=prod_xxx
CREEM_PRODUCT_PRO_ANNUAL=prod_xxx
CREEM_PRODUCT_CREDITS_SMALL=prod_xxx
CREEM_PRODUCT_CREDITS_MEDIUM=prod_xxx
CREEM_PRODUCT_CREDITS_LARGE=prod_xxx

CRON_SECRET=replace_with_a_strong_random_server_secret

适配器能根据测试模式 API 密钥推断测试 API，但显式设置 CREEM_API_BASE 更便于审查环境是否正确。生产环境应将生产模式凭证和生产模式 Product ID 与 https://api.creem.io 配套使用。

测试模式 API 密钥、测试模式 Product ID 和测试端点签名密钥必须成套使用。绝不能把 CREEM_API_KEY、CREEM_WEBHOOK_SECRET 或 CRON_SECRET 暴露给浏览器代码。

3. 配置 Webhook

把当前 Creem 端点指向：

https://your-domain.com/api/payments/webhook

验证器接受 Creem 标准签名请求头，也可以通过 CREEM_SIGNATURE_HEADER 覆盖请求头名称。它会针对未经修改的请求体验证 HMAC-SHA256 签名。

请启用商品目录所需的结账、订阅生命周期和支付事件。适配器会统一处理以下事件族：

已完成的结账事件；
subscription creation、update、activation、trial、paid、scheduled cancellation、past-due、unpaid、paused、deleted、canceled、terminated 或 expired 事件；
invoice 成功与失败事件。

未知但签名有效的事件会被确认接收，但不会触发履约。请在测试模式下确认你的账户所用 Creem API 版本实际产生的事件。

4. 结账与返回处理

请使用与服务商无关的端点：

POST /api/payments/checkout
Content-Type: application/json

{ "skuKey": "credits_small" }

POST /api/payments/subscription/checkout
Content-Type: application/json

{ "planKey": "starter", "period": "year" }

结账元数据包含已登录用户、商品目录上下文、SKU 或方案、服务商和请求 ID。订阅结账会复用服务端生成的幂等键，作为 Creem 请求 ID。

Creem 可能在成功回调 URL 后附加带签名的结账参数。客户端会把这些参数发送到 /api/payments/confirm。返回签名缺失或无法验证时，系统会将结果视为待处理（deferred），而不是支付失败；即使签名有效，也不会直接履约。带签名的 Webhook 始终是权威来源。

取消订阅会按计划执行，而不是立即生效。Billing Portal 使用订阅记录中保存的 Creem 客户 ID。这两项操作都会使用订阅记录中的服务商，而不是当前为新结账启用的服务商。

5. 在测试模式验证

npm run preflight
npm run test:unit

可选的冒烟测试会创建真实的 Creem 测试结账，但不会提交付款：

PAYMENT_PROVIDER_SANDBOX_E2E=true \
  E2E_TEST_EMAIL=<existing-test-user-email> \
  E2E_TEST_PASSWORD=<test-user-password> \
  PLAYWRIGHT_BASE_URL=https://<preview-or-test-origin> \
  npm run e2e -- tests/e2e/payment-provider-sandbox.spec.ts --project=chromium

本地服务应设置 PLAYWRIGHT_BASE_URL=http://localhost:3000。缺少任一测试凭证时，该测试会主动 skip，因此命令显示绿色并不足以通过验收：测试摘要必须明确显示 2 passed 和 0 skipped。

完整验收需要一个公网 HTTPS 部署：

完成一笔 Creem 测试支付；
确认带签名的 Webhook 已被接受；
从数据库回读订阅或积分交易；
重放该事件并确认已去重；
验证门户创建和到期取消。

请阅读 Webhook、订阅与积分，了解共用的生命周期契约。