自定义 Starter

VibeAny 是 Starter，不是成品。你可以替换示例商品目录和文案，但要保留结账、积分、存储和模型路由中与服务商无关的边界。

自定义商品目录

商品目录的唯一事实来源是 src/lib/config/products.ts。它定义：

• 订阅方案和每月积分发放量；
• 积分包及其履约数量；
• 示例一次性购买商品；
• 从环境变量读取的 Stripe Price ID 和 Creem Product ID；
• 图片生成使用的 CREDITS_PER_IMAGE 成本。

展示文案在 src/i18n/locales/* 中独立本地化。修改公开商品时，应在同一个变更中同步更新商品目录、翻译、定价 UI、服务商后台对象、环境变量和测试。

新增或删除订阅方案

1. 在 PLANS 中新增或删除方案。
2. 定义实际展示的每个计费周期。
3. 添加 Stripe 和 Creem 的服务商 ID 映射；如果部署只支持一个服务商，也可以只添加该服务商。
4. 如果内置可见 SKU 集合发生变化，更新服务商就绪检查规则。
5. 更新定价与账单翻译。
6. 验证结账、Webhook 方案解析、每月积分发放、取消订阅和门户行为。

只有环境变量并不能创建一个可用方案。例如，Enterprise 变量名只是扩展点，Enterprise 并不在内置 PLANS 数组中。

新增一次性购买商品

积分包已经内置履约逻辑。它们使用 credits_<package-id> SKU 键，并在结账完成 Webhook 到达后，幂等地增加一个积分批次。

内置落地页商品演示了权益配置，但在实现履约路径前，当前结账目录会拒绝非积分类型的一次性购买商品。公开商品前：

1. 定义它的服务商标识符；
2. 实现持久、幂等的权益或自定义履约适配器；
3. 扩展结账目录，允许该履约类型；
4. 如果商品需要退款或撤销，持久化一条可审计的购买映射；
5. 添加 Webhook 重放测试。

不要把未使用的示例 orders 表当成订单已经自动入库的证明。

功能开关也是运维门禁

依赖尚未就绪时，应保持可选功能关闭：

NEXT_PUBLIC_ENABLE_PAYMENTS=false
NEXT_PUBLIC_ENABLE_IMAGE_GENERATION=false

启用支付还需要配置 PAYMENTS_PROVIDER、所选服务商的凭证和 Webhook 签名密钥、所有可见商品标识符；存在订阅商品时，还需要 CRON_SECRET。

启用图片生成至少需要配置一个模型服务商。生成逻辑在没有存储时仍可返回模型服务商的原始 URL，但持久的生成图片 URL 还需要对象存储。

每次修改环境变量或功能开关后，都要运行 npm run preflight。

保持架构边界

主要依赖方向是：

HTTP/UI adapters
  -> application use cases and ports
    -> infrastructure adapters
      -> provider SDKs and persistence

实践规则：

• 保持 App Router 路由处理器精简；
• 把服务商 SDK 的导入和密钥读取限制在基础设施层；
• 把授权和编排放在应用用例中；
• 把纯积分和订阅规则放在领域代码中；
• 向 UI 组件暴露稳定的功能 API；
• 不要在无关的 UI 或业务模块中判断 Stripe 或 Creem。

新增其他支付服务商

Stripe 和 Creem 共用同一份契约。以后接入 Paddle 等服务商时，应新增适配器，而不是再建一套支付系统：

1. 扩展支付服务商名称联合类型；
2. 在网关端口后实现结账、到期取消和可选的门户行为；
3. 分别实现原始签名验证和事件标准化；
4. 通过商品目录映射各服务商的商品标识符；
5. 在基础设施组合层注册网关和 Webhook 验证器；
6. 添加配置就绪检查和环境变量验证；
7. 为元数据、幂等性、事件顺序、门户、取消和重放添加契约测试。

该扩展不会改变当前运行模式：每个部署仍只为新结账和 Webhook 流量选择一个当前服务商。

验证闭环

npm run preflight
npm run architecture:check
npm run test:unit
npm run typecheck:all
npm run lint
npm run build

只要改动影响结账、履约、订阅、积分或生成资源持久化，就应使用服务商沙盒测试，并回读数据库状态。

接下来可阅读存储与 AI 图片生成，或复查支付运行模式。