create-nextdevtpl 2.6.0

package/template/src/features/credits/actions.ts

@@ -0,0 +1,427 @@
+"use server";
+
+/**
+ * 积分系统 Server Actions
+ *
+ * 提供积分系统的前端调用接口
+ */
+
+import { z } from "zod";
+
+import { getBaseUrl } from "@/config/payment";
+import { logEvent } from "@/lib/logger";
+import { actionClient, protectedAction } from "@/lib/safe-action";
+import { paymentService } from "@/services/payment";
+
+import {
+  CREDIT_PACKAGES,
+  CREDITS_EXPIRY_DAYS,
+  MONTHLY_SUBSCRIPTION_CREDITS,
+  REGISTRATION_BONUS_CREDITS,
+} from "./config";
+import {
+  AccountFrozenError,
+  consumeCredits,
+  ensureRegistrationBonus,
+  getCreditsBalance,
+  getUserActiveBatches,
+  getUserTransactions,
+  getUserTransactionsCount,
+  grantCredits,
+  InsufficientCreditsError,
+} from "./core";
+
+const withPublicCreditsAction = (name: string) =>
+  actionClient.metadata({ action: `credits.${name}` });
+const withProtectedCreditsAction = (name: string) =>
+  protectedAction.metadata({ action: `credits.${name}` });
+
+// ============================================
+// 公开 Actions
+// ============================================
+
+/**
+ * 注册奖励积分
+ *
+ * 新用户注册时调用，赠送初始积分
+ */
+export const grantRegistrationBonus = withPublicCreditsAction(
+  "grantRegistrationBonus"
+)
+  .schema(
+    z.object({
+      userId: z.string().min(1),
+    })
+  )
+  .action(async ({ parsedInput }) => {
+    const { userId } = parsedInput;
+    const expiresAt = CREDITS_EXPIRY_DAYS
+      ? new Date(Date.now() + CREDITS_EXPIRY_DAYS * 24 * 60 * 60 * 1000)
+      : null;
+
+    const result = await grantCredits({
+      userId,
+      amount: REGISTRATION_BONUS_CREDITS,
+      sourceType: "bonus",
+      debitAccount: "SYSTEM:registration_bonus",
+      transactionType: "registration_bonus",
+      expiresAt,
+      description: "新用户注册奖励",
+      metadata: {
+        bonusType: "registration",
+      },
+    });
+
+    return {
+      success: true,
+      ...result,
+    };
+  });
+
+// ============================================
+// 受保护 Actions（需要登录）
+// ============================================
+
+/**
+ * 获取当前用户积分余额
+ *
+ * 包含懒加载注册奖励机制:
+ * 首次调用时，如果用户没有任何交易记录，会自动发放注册奖励
+ */
+export const getMyCreditsBalance = withProtectedCreditsAction(
+  "getMyCreditsBalance"
+).action(async ({ ctx }) => {
+  const { userId } = ctx;
+
+  // 懒加载: 确保新用户获得注册奖励
+  await ensureRegistrationBonus(
+    userId,
+    REGISTRATION_BONUS_CREDITS,
+    CREDITS_EXPIRY_DAYS
+  );
+
+  // 获取余额
+  const balance = await getCreditsBalance(userId);
+
+  return {
+    balance: balance.balance,
+    totalEarned: balance.totalEarned,
+    totalSpent: balance.totalSpent,
+    status: balance.status,
+  };
+});
+
+/**
+ * 获取当前用户活跃批次
+ */
+export const getMyActiveBatches = withProtectedCreditsAction(
+  "getMyActiveBatches"
+).action(async ({ ctx }) => {
+  const { userId } = ctx;
+  const batches = await getUserActiveBatches(userId);
+
+  return batches.map((batch) => ({
+    id: batch.id,
+    amount: batch.amount,
+    remaining: batch.remaining,
+    issuedAt: batch.issuedAt,
+    expiresAt: batch.expiresAt,
+    sourceType: batch.sourceType,
+  }));
+});
+
+/**
+ * 获取当前用户交易历史
+ */
+export const getMyTransactions = withProtectedCreditsAction("getMyTransactions")
+  .schema(
+    z
+      .object({
+        limit: z.number().min(1).max(100).optional(),
+        offset: z.number().min(0).optional(),
+      })
+      .optional()
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { userId } = ctx;
+    const limit = parsedInput?.limit;
+    const offset = parsedInput?.offset;
+
+    const [transactions, totalCount] = await Promise.all([
+      getUserTransactions(userId, {
+        ...(limit !== undefined && { limit }),
+        ...(offset !== undefined && { offset }),
+      }),
+      getUserTransactionsCount(userId),
+    ]);
+
+    return {
+      transactions: transactions.map((tx) => ({
+        id: tx.id,
+        type: tx.type,
+        amount: tx.amount,
+        debitAccount: tx.debitAccount,
+        creditAccount: tx.creditAccount,
+        description: tx.description,
+        metadata: tx.metadata as Record<string, unknown> | null,
+        createdAt: tx.createdAt,
+      })),
+      totalCount,
+    };
+  });
+
+/**
+ * 消费积分
+ *
+ * 用于 AI 服务等需要消费积分的场景
+ */
+export const useCredits = withProtectedCreditsAction("useCredits")
+  .schema(
+    z.object({
+      amount: z.number().min(1),
+      serviceName: z.string().min(1),
+      description: z.string().optional(),
+      metadata: z.record(z.string(), z.unknown()).optional(),
+    })
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { userId } = ctx;
+    const { amount, serviceName, description, metadata } = parsedInput;
+
+    try {
+      const result = await consumeCredits({
+        userId,
+        amount,
+        serviceName,
+        ...(description !== undefined && { description }),
+        ...(metadata !== undefined && { metadata }),
+      });
+
+      logEvent("credits.consumed", {
+        userId,
+        amount,
+        serviceName,
+      });
+
+      return {
+        success: true,
+        consumedAmount: result.consumedAmount,
+        remainingBalance: result.remainingBalance,
+        transactionId: result.transactionId,
+      };
+    } catch (error) {
+      if (error instanceof InsufficientCreditsError) {
+        return {
+          success: false,
+          error: "insufficient_credits",
+          message: error.message,
+          required: error.required,
+          available: error.available,
+        };
+      }
+      if (error instanceof AccountFrozenError) {
+        return {
+          success: false,
+          error: "account_frozen",
+          message: error.message,
+        };
+      }
+      throw error;
+    }
+  });
+
+/**
+ * 检查用户是否有足够积分
+ */
+export const checkCreditsAvailable = withProtectedCreditsAction(
+  "checkCreditsAvailable"
+)
+  .schema(
+    z.object({
+      amount: z.number().min(1),
+    })
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { userId } = ctx;
+    const { amount } = parsedInput;
+
+    const balance = await getCreditsBalance(userId);
+
+    // balance 由 ensureCreditsBalance 保证不为 undefined
+    return {
+      available: balance.balance >= amount && balance.status === "active",
+      currentBalance: balance.balance,
+      required: amount,
+      status: balance.status,
+    };
+  });
+
+// ============================================
+// 订阅相关积分 Actions
+// ============================================
+
+/**
+ * 发放月度订阅积分
+ *
+ * 在订阅续费时调用
+ */
+export const grantMonthlySubscriptionCredits = withPublicCreditsAction(
+  "grantMonthlySubscriptionCredits"
+)
+  .schema(
+    z.object({
+      userId: z.string().min(1),
+      subscriptionId: z.string().min(1),
+    })
+  )
+  .action(async ({ parsedInput }) => {
+    const { userId, subscriptionId } = parsedInput;
+    // 月度积分，下个月过期
+    const expiresAt = new Date();
+    expiresAt.setMonth(expiresAt.getMonth() + 1);
+
+    const result = await grantCredits({
+      userId,
+      amount: MONTHLY_SUBSCRIPTION_CREDITS,
+      sourceType: "subscription",
+      debitAccount: `SUBSCRIPTION:${subscriptionId}`,
+      transactionType: "monthly_grant",
+      expiresAt,
+      sourceRef: subscriptionId,
+      description: "月度订阅积分",
+      metadata: {
+        subscriptionId,
+        grantType: "monthly",
+      },
+    });
+
+    return {
+      success: true,
+      ...result,
+    };
+  });
+
+/**
+ * 购买积分 (内部函数)
+ *
+ * 由支付 Webhook 调用，在支付成功后发放积分
+ * 注意: 这个函数不应该直接被前端调用
+ */
+export const purchaseCredits = withProtectedCreditsAction("purchaseCredits")
+  .schema(
+    z.object({
+      amount: z.number().min(1),
+      paymentId: z.string().min(1),
+      expiresInDays: z.number().optional(),
+    })
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { userId } = ctx;
+    const { amount, paymentId, expiresInDays } = parsedInput;
+
+    const expiresAt = expiresInDays
+      ? new Date(Date.now() + expiresInDays * 24 * 60 * 60 * 1000)
+      : null;
+
+    const result = await grantCredits({
+      userId,
+      amount,
+      sourceType: "purchase",
+      debitAccount: `PAYMENT:${paymentId}`,
+      transactionType: "purchase",
+      expiresAt,
+      sourceRef: paymentId,
+      description: `购买 ${amount} 积分`,
+      metadata: {
+        paymentId,
+        purchaseType: "direct",
+      },
+    });
+
+    logEvent("credits.purchased", {
+      userId,
+      amount,
+      paymentId,
+      source: "creem",
+    });
+
+    return {
+      success: true,
+      ...result,
+    };
+  });
+
+// ============================================
+// 积分购买 Checkout
+// ============================================
+
+/**
+ * 创建积分购买 Checkout Session
+ *
+ * 创建支付 Checkout Session 用于购买积分套餐
+ * metadata 中包含 type: 'credit_purchase' 和 credits 数量
+ * Webhook 会根据这些信息发放积分
+ */
+export const createCreditsPurchaseCheckout = withProtectedCreditsAction(
+  "createCreditsPurchaseCheckout"
+)
+  .schema(
+    z.object({
+      packageId: z.enum(["lite", "standard", "pro"]),
+      successUrl: z.string().optional(),
+      cancelUrl: z.string().optional(),
+    })
+  )
+  .action(async ({ parsedInput, ctx }) => {
+    const { packageId, successUrl } = parsedInput;
+    const { userId } = ctx;
+
+    // 查找套餐配置
+    const pkg = CREDIT_PACKAGES.find((p) => p.id === packageId);
+    if (!pkg) {
+      throw new Error("无效的积分套餐");
+    }
+
+    const baseUrl = getBaseUrl();
+
+    logEvent("payment.checkout.started", {
+      userId,
+      packageId: pkg.id,
+      credits: pkg.credits,
+      provider: paymentService.provider,
+      checkoutType: "credits",
+    });
+
+    const checkout = await paymentService.createCheckout({
+      productId: `credits_${packageId}`,
+      mode: "one-time",
+      successUrl:
+        successUrl ??
+        `${baseUrl}/dashboard/settings?tab=usage&success=true&credits=${pkg.credits}`,
+      requestId: `credit_purchase_${userId}_${Date.now()}`,
+      metadata: {
+        userId,
+        type: "credit_purchase",
+        credits: String(pkg.credits),
+        packageId: pkg.id,
+      },
+    });
+
+    return { url: checkout.url };
+  });
+
+/**
+ * 获取积分套餐列表
+ */
+export const getCreditPackages = withProtectedCreditsAction(
+  "getCreditPackages"
+).action(async () => {
+  return CREDIT_PACKAGES.map((pkg) => ({
+    id: pkg.id,
+    name: pkg.name,
+    credits: pkg.credits,
+    price: pkg.price,
+    description: pkg.description,
+    popular: "popular" in pkg ? pkg.popular : false,
+  }));
+});

package/template/src/features/credits/components/credit-balance-badge.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+/**
+ * 积分余额徽章组件
+ *
+ * 显示在侧边栏中，展示用户当前可用积分
+ */
+
+import { Coins } from "lucide-react";
+import { useAction } from "next-safe-action/hooks";
+import { useEffect } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { getMyCreditsBalance } from "@/features/credits/actions";
+
+/**
+ * 积分余额徽章
+ *
+ * 特性:
+ * - 自动获取用户积分余额
+ * - 显示为闪电图标 + 数字格式
+ * - 支持 Tooltip 显示详情
+ */
+export function CreditBalanceBadge() {
+  const { execute, result, isPending } = useAction(getMyCreditsBalance);
+
+  // 组件挂载时获取余额
+  useEffect(() => {
+    execute();
+  }, [execute]);
+
+  const balance = result.data?.balance ?? 0;
+
+  // 加载状态
+  if (isPending) {
+    return (
+      <Badge variant="secondary" className="gap-1 px-2 py-1">
+        <Coins className="h-3 w-3" />
+        <span className="text-xs">...</span>
+      </Badge>
+    );
+  }
+
+  return (
+    <Badge
+      variant="secondary"
+      className="gap-1 px-2 py-1 bg-warning/15 text-warning hover:bg-warning/25"
+      title="Available Credits"
+    >
+      <Coins className="h-3 w-3" />
+      <span className="text-xs font-medium">{balance.toLocaleString()}</span>
+    </Badge>
+  );
+}

package/template/src/features/credits/components/credit-usage-section.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+/**
+ * 积分使用情况组件
+ *
+ * Settings > Usage Tab 的主要内容
+ * 包含:
+ * - 可用积分余额
+ * - 购买积分入口
+ * - 即将过期积分提示
+ * - 订阅状态
+ * - 交易历史
+ */
+
+import { Clock, Coins } from "lucide-react";
+import Link from "next/link";
+import { useLocale, useTranslations } from "next-intl";
+import { useAction } from "next-safe-action/hooks";
+import { useEffect } from "react";
+
+import { Button } from "@/components/ui/button";
+import { Separator } from "@/components/ui/separator";
+import {
+  getMyActiveBatches,
+  getMyCreditsBalance,
+} from "@/features/credits/actions";
+
+import { TransactionHistory } from "./transaction-history";
+
+/**
+ * 格式化日期
+ */
+function formatDate(date: Date | string | null, locale: string): string {
+  if (!date) return "Never";
+  const d = new Date(date);
+  return d.toLocaleDateString(locale === "zh" ? "zh-CN" : "en-US", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+}
+
+/**
+ * 积分使用情况组件
+ */
+export function CreditUsageSection() {
+  const t = useTranslations("Settings.usage");
+  const locale = useLocale();
+
+  // 获取积分余额
+  const {
+    execute: fetchBalance,
+    result: balanceResult,
+    isPending: isBalanceLoading,
+  } = useAction(getMyCreditsBalance);
+
+  // 获取活跃批次（用于显示即将过期）
+  const { execute: fetchBatches, result: batchesResult } =
+    useAction(getMyActiveBatches);
+
+  // 组件挂载时获取数据
+  useEffect(() => {
+    fetchBalance();
+    fetchBatches();
+  }, [fetchBalance, fetchBatches]);
+
+  const balance = balanceResult.data?.balance ?? 0;
+  const batches = batchesResult.data ?? [];
+
+  // 找到最近即将过期的批次
+  const expiringBatch = batches
+    .filter((b) => b.expiresAt !== null)
+    .sort((a, b) => {
+      if (!a.expiresAt || !b.expiresAt) return 0;
+      return new Date(a.expiresAt).getTime() - new Date(b.expiresAt).getTime();
+    })[0];
+
+  return (
+    <div className="space-y-8">
+      {/* 标题 */}
+      <div>
+        <h2 className="text-xl font-semibold">{t("title")}</h2>
+        <p className="text-sm text-muted-foreground">{t("description")}</p>
+      </div>
+
+      {/* 可用积分 */}
+      <div className="flex items-center justify-between py-4">
+        <div className="flex items-center gap-3">
+          <div className="flex h-10 w-10 items-center justify-center rounded-full bg-warning/15">
+            <Coins className="h-5 w-5 text-warning" />
+          </div>
+          <span className="font-medium">{t("availableCredits")}</span>
+        </div>
+
+        <div className="text-right">
+          {isBalanceLoading ? (
+            <div className="animate-pulse">
+              <div className="h-10 w-16 bg-muted rounded" />
+            </div>
+          ) : (
+            <>
+              <div className="text-4xl font-bold">
+                {balance.toLocaleString()}
+              </div>
+              <div className="text-sm text-muted-foreground">
+                {t("creditsAvailable")}
+              </div>
+            </>
+          )}
+        </div>
+      </div>
+
+      <Separator />
+
+      {/* 购买更多积分 */}
+      <div className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">{t("getMoreCredits.title")}</h3>
+          <p className="text-sm text-muted-foreground">
+            {t("getMoreCredits.description")}
+          </p>
+        </div>
+
+        <div className="flex gap-3">
+          <Button asChild>
+            <Link href="/#pricing">{t("getMoreCredits.viewPlans")}</Link>
+          </Button>
+        </div>
+      </div>
+
+      {/* 即将过期积分提示 */}
+      {expiringBatch && (
+        <>
+          <Separator />
+          <div className="flex items-center justify-between rounded-lg border border-warning/30 bg-warning/10 px-4 py-3">
+            <div className="flex items-center gap-3">
+              <Clock className="h-5 w-5 text-warning" />
+              <div>
+                <p className="font-medium text-warning">
+                  {t("expiringSoon.title")}
+                </p>
+                <p className="text-sm text-warning">
+                  {t("expiringSoon.message", {
+                    count: expiringBatch.remaining,
+                    date: formatDate(expiringBatch.expiresAt, locale),
+                  })}
+                </p>
+              </div>
+            </div>
+          </div>
+        </>
+      )}
+
+      <Separator />
+
+      {/* 交易历史 */}
+      <TransactionHistory />
+    </div>
+  );
+}

package/template/src/features/credits/components/index.ts

@@ -0,0 +1,7 @@
+/**
+ * 积分系统组件导出
+ */
+
+export { CreditBalanceBadge } from "./credit-balance-badge";
+export { CreditUsageSection } from "./credit-usage-section";
+export { TransactionHistory } from "./transaction-history";