支付系统概述

NEXTY.DEV 支付系统是一个功能完整、支持多支付提供商的 SaaS 支付解决方案。它支持 Stripe 和 Creem 两个支付提供商，提供了从定价计划管理、支付处理、订阅管理到积分系统的完整功能。

核心特性

1. 多支付提供商支持

• Stripe: 全球流行的支付服务提供商
• Creem: 新兴的支付服务提供商
• 统一接口: 通过统一的代码接口处理不同提供商的支付逻辑

2. 灵活的定价计划

• 一次性支付 (One-time Payment)
• 订阅支付 (Subscription Payment)
  • 月度订阅 (Monthly)
  • 年度订阅 (Yearly)

3. 完整的支付流程

• 支付 Session 创建
• 支付验证
• Webhook 处理
• 订单管理
• 订阅同步

4. 积分系统

• 一次性积分 (One-time Credits)
• 订阅积分 (Subscription Credits)
• 积分使用记录
• 积分余额管理

系统架构

数据库表结构

1. pricing_plans - 定价计划表

存储所有定价计划的信息，包括：

• 基础信息: id, cardTitle, cardDescription
• 支付提供商配置: provider, stripePriceId, creemProductId
• 支付类型: paymentType
  • one_time(Stripe)
  • onetime(Creem)
  • recurring(Stripe and Creem)
• 订阅间隔: recurringInterval
  • month(Stripe)
  • year(Stripe)
  • every-month(Creem)
  • every-year(Creem)
  • once(Creem)
• 价格信息: price, currency, displayPrice, originalPrice
• 优惠券: stripeCouponId, creemDiscountCode
• 多语言支持: langJsonb (JSONB 格式存储多语言内容)
• 权益配置: benefitsJsonb (JSONB 格式存储权益信息，如积分数量)
• 显示设置: isActive, isHighlighted, displayOrder

2. orders - 订单表

存储所有支付订单记录：

• 用户关联: userId
• 支付提供商: provider (stripe/creem)
• 订单类型: orderType
  • one_time_purchase(Stripe)
  • onetime_purchase(Creem)
  • subscription_initial(Stripe)
  • subscription_renewal(Stripe)
  • recurring(Stripe and Creem)
  • refund(Stripe and Creem)
• 订单状态: status (succeeded/pending/failed/refunded/partially_refunded)
• 金额信息: amountSubtotal, amountDiscount, amountTax, amountTotal, currency
• 关联信息: planId, subscriptionId, productId, priceId
• 提供商特定字段: stripePaymentIntentId, stripeInvoiceId, stripeChargeId
• 元数据: metadata (JSONB 格式存储提供商特定的元数据)

3. subscriptions - 订阅表

存储用户订阅信息：

• 用户关联: userId, planId
• 支付提供商: provider
• 订阅标识: subscriptionId, customerId
• 订阅状态: status (active/trialing/past_due/canceled/incomplete/etc.)
• 周期信息: currentPeriodStart, currentPeriodEnd
• 取消信息: cancelAtPeriodEnd, canceledAt, endedAt
• 试用信息: trialStart, trialEnd
• 元数据: metadata (JSONB 格式)

4. usage - 使用量/积分表

存储用户的积分余额和使用情况：

• 用户关联: userId (唯一)
• 积分余额: subscriptionCreditsBalance, oneTimeCreditsBalance
• 余额详情: balanceJsonb (JSONB 格式存储月度/年度分配详情)

5. credit_logs - 积分日志表

记录所有积分变动：

• 用户关联: userId
• 变动金额: amount (正数为增加，负数为减少)
• 变动后余额: oneTimeBalanceAfter, subscriptionBalanceAfter
• 变动类型: type (one_time_purchase/subscription_grant/feature_usage/refund_revoke/etc.)
• 关联订单: relatedOrderId
• 备注: notes

核心模块

1. Actions 层 (actions/)

服务器端操作函数，处理业务逻辑：

• actions/prices/: 定价计划管理（管理员和公开接口）
• actions/stripe/: Stripe 支付相关操作
• actions/creem/: Creem 支付相关操作
• actions/orders/: 订单查询（用户和管理员）
• actions/usage/: 积分管理和查询

2. API 路由 (app/api/)

处理 HTTP 请求和 Webhook：

• app/api/payment/: 支付相关 API
  • checkout-session: 创建结账会话
  • verify-success: 验证支付成功
• app/api/stripe/webhook/: Stripe Webhook 处理
• app/api/creem/webhook/: Creem Webhook 处理

3. 库文件 (lib/)

可重用的工具函数和客户端：

• lib/payments/: 支付相关工具函数
  • provider-utils.ts: 支付提供商工具函数
  • credit-manager.ts: 积分管理
  • webhook-helpers.ts: Webhook 辅助函数
  • types.ts: 类型定义
• lib/stripe/: Stripe 客户端
• lib/creem/: Creem 客户端

4. UI 组件 (components/)

前端展示组件：

• components/home/Pricing.tsx: 定价页面（按类型分类显示）
• components/home/PricingAll.tsx: 定价页面（显示所有计划）
• components/home/PricingCardDisplay.tsx: 定价卡片展示组件
• components/home/PricingCTA.tsx: 定价卡片 CTA 按钮

5. 管理界面 (app/[locale]/(protected)/dashboard/)

• (admin)/prices/: 管理员定价计划管理
• (admin)/orders/: 管理员订单管理
• (user)/my-orders/: 用户订单列表
• (user)/credit-history/: 用户积分历史
• (user)/subscription/: 用户订阅管理

支付流程概览

1. 用户选择计划

用户在定价页面选择计划，点击购买按钮。

2. 创建结账会话

前端调用 /api/payment/checkout-session API，后端根据支付提供商创建相应的结账会话。

3. 跳转到支付页面

用户被重定向到支付提供商的支付页面完成支付。

4. 支付成功回调

支付成功后，用户被重定向回应用 /payment/success 页面，系统验证支付状态。

5. Webhook 处理

支付提供商发送 Webhook 事件(/api/stripe/webhook 或 /api/creem/webhook)，系统处理订单创建、积分授予等操作。

6. 订阅同步

对于订阅支付，系统定期同步订阅状态，处理续费、取消等事件。

支付类型说明

一次性支付 (One-time Payment)

• Stripe: paymentType = 'one_time'
• Creem: paymentType = 'onetime'
• 用户一次性购买，获得一次性积分

订阅支付 (Subscription Payment)

• Stripe: paymentType = 'recurring', recurringInterval = 'month'/'year'
• Creem: paymentType = 'recurring', recurringInterval = 'every-month'/'every-year'
• 用户按月或按年订阅，定期获得积分

环境变量配置

Stripe 配置

STRIPE_SECRET_KEY=sk_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_CUSTOMER_PORTAL_URL=/dashboard/subscription

Creem 配置

CREEM_API_KEY=your_api_key
CREEM_WEBHOOK_SECRET=your_webhook_secret
CREEM_API_BASE_URL=https://api.creem.io/v1  # 可选，默认值

其他配置

NEXT_PUBLIC_PRICING_PATH=/pricing
NEXT_PUBLIC_SITE_URL=https://yourdomain.com
[email protected]