积分 | MkSaaS - 快速构建 AI SaaS 产品

MkSaaS 提供了一个灵活、模块化的积分系统，用于奖励用户、启用按使用付费功能，并支持各种商业模式。本文档解释了如何在 MkSaaS 中启用、配置和使用积分系统。

设置

要在 MkSaaS 中设置积分系统，请按照以下步骤配置必要的环境变量：

在配置中启用积分

打开 src/config/website.tsx 并找到 credits 部分。

设置 enableCredits: true 以启用积分系统。
设置 enablePackagesForFreePlan，默认只有付费订阅用户可以购买积分套餐，如果设置为 true，则免费用户也可以购买积分套餐。
设置 registerGiftCredits，配置注册时是否赠送积分，赠送的积分数量和有效期。

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  credits: {
    enableCredits: true, // 启用积分系统
    enablePackagesForFreePlan: false, // 不允许免费用户购买积分
    registerGiftCredits: {
      enable: true, // 注册时赠送积分
      amount: 10, // 赠送的积分数量
      expireDays: 30, // 可选：积分过期天数
    },
    packages: {
      basic: {
        id: 'basic',
        credits: 100,
        price: {
          priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
          amount: 990,
          currency: 'USD',
        },
        popular: false,
      },
      // ...其他套餐
    },
  },
  // ...其他配置
}

配置产品价格计划中的积分

在 src/config/website.tsx 中找到 price.plans 部分。

设置 credits 字段为 true 以启用这个价格计划中的积分。
设置 amount 字段为 100 以设置这个价格计划中的积分数量。

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  price: {
    plans: {
      free: {
        id: 'free',
        // ...其他配置
        isFree: true,
        isLifetime: false,
        credits: {
          enable: true,
          amount: 50,
          expireDays: 30,
        },
      },
      // ...其他价格计划
    },
  },
  // ...其他配置
}

配置积分套餐

在 credits.packages 下定义积分套餐，默认有 4 个积分套餐。

每个套餐包括 id、积分数量、价格（Stripe priceId，见下面的 设置 Stripe 价格 ID）和可选字段如 popular、expireDays。
货币单位为美元，目前仅支持美元。

src/config/website.tsx

packages: {
  basic: {
    id: 'basic',
    amount: 100,
    price: {
      priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
      amount: 990,
      currency: 'USD',
    },
    popular: false,
    expireDays: 30,
  },
  // ...
}

设置 Stripe 价格 ID

Stripe 价格 ID 用于将积分套餐链接到 Stripe 产品和价格。

在 Stripe Dashboard 中创建一个新产品，并为每个积分套餐设置4个价格。
将每个积分套餐的 Stripe 价格 ID 添加到环境变量文件中：

.env

NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STANDARD=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PREMIUM=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_ENTERPRISE=price_...

Credits

为积分套餐设置翻译

在 src/config/credits-config.tsx 中定义积分套餐名称和描述。

对应的是不同语言的翻译文件，例如 src/messages/en.json、src/messages/zh.json 等。

src/config/credits-config.tsx

export function getCreditPackages(): Record<string, CreditPackage> {
  const t = useTranslations('CreditPackages');
  const creditConfig = websiteConfig.credits;
  const packages: Record<string, CreditPackage> = {};

  // 为每个套餐添加翻译内容
  if (creditConfig.packages.basic) {
    packages.basic = {
      ...creditConfig.packages.basic,
      name: t('basic.name'),
      description: t('basic.description'),
    };
  }

  // 在这里添加其他套餐...
  return packages;
}

设置定时任务

请参考定时任务文档，设置定时发放积分和处理积分过期的任务。

如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置

设置环境变量

积分系统架构

积分系统是模块化的，由以下组件组成：

credits.ts

types.ts

client.ts

server.ts

核心功能

购买积分：用户如果积分不足可以购买积分套餐。
注册赠送积分：可选择为新用户赠送初始化积分。
积分过期：为每个套餐或赠品设置积分过期天数。
跟踪积分余额：安全查询和更新当前用户的积分。
积分交易：查看详细的交易历史（购买、使用、过期等）。
自定义套餐：定义任意数量的套餐，具有不同的数量、价格和属性。
国际化：支持翻译的套餐名称和描述。
安全 Server Action：所有积分操作都受到保护和验证。
Zustand Store：在应用程序中全局管理积分状态，并通过 hooks 在 React 组件中使用。

最佳实践

仅在需要时启用：仅当您的产品商业模式需要积分时才设置 enableCredits: true。
验证所有操作：使用提供的 Server Action 进行所有积分操作以确保安全性和验证。
处理过期：如果您希望积分过期，请为套餐或赠品设置积分过期天数 expireDays。

测试

你可以访问 http://localhost:3000/test 页面来测试积分系统，界面上有积分消耗按钮，点击后会消耗 100 积分，并显示消耗后的积分余额。

视频教程

下一步

现在您了解了如何在 MkSaaS 中使用积分，您可能想要探索这些相关功能：

支付

配置支付和订阅

身份验证

配置用户身份验证

统计分析

配置统计分析服务

电子邮件

配置电子邮件服务

积分

如何在 MkSaaS 中设置和使用积分系统

设置

要在 MkSaaS 中设置积分系统，请按照以下步骤配置必要的环境变量：

在配置中启用积分

打开 src/config/website.tsx 并找到 credits 部分。

设置 enableCredits: true 以启用积分系统。
设置 enablePackagesForFreePlan，默认只有付费订阅用户可以购买积分套餐，如果设置为 true，则免费用户也可以购买积分套餐。
设置 registerGiftCredits，配置注册时是否赠送积分，赠送的积分数量和有效期。

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  credits: {
    enableCredits: true, // 启用积分系统
    enablePackagesForFreePlan: false, // 不允许免费用户购买积分
    registerGiftCredits: {
      enable: true, // 注册时赠送积分
      amount: 10, // 赠送的积分数量
      expireDays: 30, // 可选：积分过期天数
    },
    packages: {
      basic: {
        id: 'basic',
        credits: 100,
        price: {
          priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
          amount: 990,
          currency: 'USD',
        },
        popular: false,
      },
      // ...其他套餐
    },
  },
  // ...其他配置
}

配置产品价格计划中的积分

在 src/config/website.tsx 中找到 price.plans 部分。

设置 credits 字段为 true 以启用这个价格计划中的积分。
设置 amount 字段为 100 以设置这个价格计划中的积分数量。

src/config/website.tsx

export const websiteConfig = {
  // ...其他配置
  price: {
    plans: {
      free: {
        id: 'free',
        // ...其他配置
        isFree: true,
        isLifetime: false,
        credits: {
          enable: true,
          amount: 50,
          expireDays: 30,
        },
      },
      // ...其他价格计划
    },
  },
  // ...其他配置
}

配置积分套餐

在 credits.packages 下定义积分套餐，默认有 4 个积分套餐。

每个套餐包括 id、积分数量、价格（Stripe priceId，见下面的 设置 Stripe 价格 ID）和可选字段如 popular、expireDays。
货币单位为美元，目前仅支持美元。

src/config/website.tsx

packages: {
  basic: {
    id: 'basic',
    amount: 100,
    price: {
      priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC!,
      amount: 990,
      currency: 'USD',
    },
    popular: false,
    expireDays: 30,
  },
  // ...
}

设置 Stripe 价格 ID

Stripe 价格 ID 用于将积分套餐链接到 Stripe 产品和价格。

在 Stripe Dashboard 中创建一个新产品，并为每个积分套餐设置4个价格。
将每个积分套餐的 Stripe 价格 ID 添加到环境变量文件中：

.env

NEXT_PUBLIC_STRIPE_PRICE_CREDITS_BASIC=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_STANDARD=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_PREMIUM=price_...
NEXT_PUBLIC_STRIPE_PRICE_CREDITS_ENTERPRISE=price_...

Credits

为积分套餐设置翻译

在 src/config/credits-config.tsx 中定义积分套餐名称和描述。

对应的是不同语言的翻译文件，例如 src/messages/en.json、src/messages/zh.json 等。

src/config/credits-config.tsx

export function getCreditPackages(): Record<string, CreditPackage> {
  const t = useTranslations('CreditPackages');
  const creditConfig = websiteConfig.credits;
  const packages: Record<string, CreditPackage> = {};

  // 为每个套餐添加翻译内容
  if (creditConfig.packages.basic) {
    packages.basic = {
      ...creditConfig.packages.basic,
      name: t('basic.name'),
      description: t('basic.description'),
    };
  }

  // 在这里添加其他套餐...
  return packages;
}