create-nextdevtpl 2.6.0

package/template/src/features/credits/components/transaction-history.tsx

@@ -0,0 +1,346 @@
+"use client";
+
+/**
+ * 积分交易历史组件
+ *
+ * 显示用户的积分交易记录表格
+ */
+
+import {
+  ChevronLeft,
+  ChevronRight,
+  ChevronsLeft,
+  ChevronsRight,
+  Inbox,
+} from "lucide-react";
+import { useLocale, useTranslations } from "next-intl";
+import { useAction } from "next-safe-action/hooks";
+import { useEffect, useState } from "react";
+
+import { Badge } from "@/components/ui/badge";
+import { Button } from "@/components/ui/button";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Separator } from "@/components/ui/separator";
+import { getMyTransactions } from "@/features/credits/actions";
+import { cn } from "@/lib/utils";
+
+/**
+ * 交易类型键
+ */
+type TransactionTypeKey =
+  | "registration_bonus"
+  | "admin_grant"
+  | "monthly_grant"
+  | "purchase"
+  | "consumption"
+  | "expiration"
+  | "refund";
+
+/**
+ * 交易类型变体映射
+ */
+const TRANSACTION_TYPE_VARIANTS: Record<
+  TransactionTypeKey,
+  "default" | "secondary" | "destructive" | "outline"
+> = {
+  registration_bonus: "default",
+  admin_grant: "default",
+  monthly_grant: "default",
+  purchase: "secondary",
+  consumption: "destructive",
+  expiration: "outline",
+  refund: "secondary",
+};
+
+/**
+ * 格式化日期时间
+ */
+function formatDateTime(date: Date | string, locale: string): string {
+  const d = new Date(date);
+  return d.toLocaleString(locale === "zh" ? "zh-CN" : "en-US", {
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+  });
+}
+
+/**
+ * 判断是否为收入类型交易
+ */
+function isIncomeType(type: string): boolean {
+  return [
+    "registration_bonus",
+    "admin_grant",
+    "monthly_grant",
+    "purchase",
+    "refund",
+  ].includes(type);
+}
+
+/**
+ * 交易历史组件
+ */
+export function TransactionHistory() {
+  const t = useTranslations("Settings.usage.transactions");
+  const locale = useLocale();
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(10);
+  const { execute, result, isPending } = useAction(getMyTransactions);
+
+  // 获取交易记录
+  useEffect(() => {
+    execute({ limit: pageSize, offset: (page - 1) * pageSize });
+  }, [execute, page, pageSize]);
+
+  const transactions = result.data?.transactions ?? [];
+  const totalCount = result.data?.totalCount ?? 0;
+  const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
+
+  /**
+   * 获取交易类型标签
+   */
+  const getTypeLabel = (type: string): string => {
+    const typeKey = type as TransactionTypeKey;
+    if (typeKey in TRANSACTION_TYPE_VARIANTS) {
+      return t(`types.${typeKey}`);
+    }
+    return type;
+  };
+
+  /**
+   * 获取本地化的交易描述
+   */
+  const getLocalizedDescription = (tx: {
+    type: string;
+    description: string | null;
+    metadata?: Record<string, unknown> | null;
+  }): string => {
+    const meta = tx.metadata;
+    switch (tx.type) {
+      case "registration_bonus":
+        return t("descriptions.registration_bonus");
+      case "monthly_grant": {
+        const planType = (meta?.planType as string) ?? "";
+        const plan = planType.charAt(0).toUpperCase() + planType.slice(1);
+        const interval = meta?.interval as string;
+        const monthlyCredits = meta?.planType
+          ? ({ starter: "3000", pro: "8000", ultra: "16000" }[planType] ?? "")
+          : "";
+        if (interval === "year") {
+          return t("descriptions.yearly_grant", {
+            plan,
+            monthly: monthlyCredits,
+          });
+        }
+        return t("descriptions.monthly_grant", { plan });
+      }
+      case "consumption":
+        return tx.description ?? t("descriptions.consumption");
+      case "expiration":
+        return t("descriptions.expiration");
+      case "admin_grant":
+        return t("descriptions.admin_grant");
+      case "refund":
+        return t("descriptions.refund");
+      default:
+        return tx.description ?? "-";
+    }
+  };
+
+  /**
+   * 获取交易类型变体
+   */
+  const getTypeVariant = (
+    type: string
+  ): "default" | "secondary" | "destructive" | "outline" => {
+    const typeKey = type as TransactionTypeKey;
+    return TRANSACTION_TYPE_VARIANTS[typeKey] ?? "outline";
+  };
+
+  // 空状态
+  if (!isPending && transactions.length === 0) {
+    return (
+      <div className="space-y-4">
+        {/* 标题 */}
+        <div>
+          <h3 className="text-lg font-semibold">{t("title")}</h3>
+          <p className="text-sm text-muted-foreground">{t("description")}</p>
+        </div>
+
+        {/* 空状态 */}
+        <div className="flex flex-col items-center justify-center py-12 text-center border rounded-lg">
+          <Inbox className="h-12 w-12 text-muted-foreground/50 mb-4" />
+          <p className="text-muted-foreground">{t("noTransactions")}</p>
+          <p className="text-sm text-muted-foreground/70">
+            {t("noTransactionsHint")}
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-4">
+      {/* 标题 */}
+      <div>
+        <h3 className="text-lg font-semibold">{t("title")}</h3>
+        <p className="text-sm text-muted-foreground">{t("description")}</p>
+      </div>
+
+      {/* 表格 */}
+      <div className="rounded-lg border">
+        {/* 表头 */}
+        <div className="grid grid-cols-12 gap-4 px-4 py-3 bg-muted/50 text-sm font-medium text-muted-foreground">
+          <div className="col-span-3">{t("date")}</div>
+          <div className="col-span-2">{t("type")}</div>
+          <div className="col-span-5">{t("transactionDescription")}</div>
+          <div className="col-span-2 text-right">{t("transactionAmount")}</div>
+        </div>
+
+        <Separator />
+
+        {/* 加载状态 */}
+        {isPending ? (
+          <div className="flex items-center justify-center py-8">
+            <div className="animate-pulse text-muted-foreground">
+              {t("loading")}
+            </div>
+          </div>
+        ) : (
+          /* 表格内容 */
+          <div className="divide-y">
+            {transactions.map((tx) => {
+              const isIncome = isIncomeType(tx.type);
+
+              return (
+                <div
+                  key={tx.id}
+                  className="grid grid-cols-12 gap-4 px-4 py-3 text-sm hover:bg-muted/30 transition-colors"
+                >
+                  {/* 日期 */}
+                  <div className="col-span-3 text-muted-foreground">
+                    {formatDateTime(tx.createdAt, locale)}
+                  </div>
+
+                  {/* 类型 */}
+                  <div className="col-span-2">
+                    <Badge
+                      variant={getTypeVariant(tx.type)}
+                      className="text-xs"
+                    >
+                      {getTypeLabel(tx.type)}
+                    </Badge>
+                  </div>
+
+                  {/* 描述 */}
+                  <div
+                    className="col-span-5 truncate"
+                    title={getLocalizedDescription(tx)}
+                  >
+                    {getLocalizedDescription(tx)}
+                  </div>
+
+                  {/* 金额 */}
+                  <div
+                    className={cn(
+                      "col-span-2 text-right font-medium",
+                      isIncome ? "text-success" : "text-destructive"
+                    )}
+                  >
+                    {isIncome ? "+" : "-"}
+                    {tx.amount}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        )}
+      </div>
+
+      {/* 分页 */}
+      <div className="flex items-center justify-between text-sm text-muted-foreground">
+        <div>
+          {t("showing", {
+            from: Math.min((page - 1) * pageSize + 1, totalCount),
+            to: Math.min(page * pageSize, totalCount),
+            total: totalCount,
+          })}
+        </div>
+
+        <div className="flex items-center gap-4">
+          {/* 每页数量选择 */}
+          <div className="flex items-center gap-2">
+            <span>{t("rowsPerPage")}</span>
+            <Select
+              value={String(pageSize)}
+              onValueChange={(v) => {
+                setPageSize(Number(v));
+                setPage(1);
+              }}
+            >
+              <SelectTrigger className="w-16 h-8">
+                <SelectValue />
+              </SelectTrigger>
+              <SelectContent>
+                <SelectItem value="10">10</SelectItem>
+                <SelectItem value="20">20</SelectItem>
+                <SelectItem value="50">50</SelectItem>
+              </SelectContent>
+            </Select>
+          </div>
+
+          {/* 页码信息 */}
+          <span>{t("pageOf", { page, total: totalPages })}</span>
+
+          {/* 分页按钮 */}
+          <div className="flex items-center gap-1">
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-8 w-8"
+              onClick={() => setPage(1)}
+              disabled={page === 1}
+            >
+              <ChevronsLeft className="h-4 w-4" />
+            </Button>
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-8 w-8"
+              onClick={() => setPage((p) => Math.max(1, p - 1))}
+              disabled={page === 1}
+            >
+              <ChevronLeft className="h-4 w-4" />
+            </Button>
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-8 w-8"
+              onClick={() => setPage((p) => Math.min(totalPages, p + 1))}
+              disabled={page === totalPages}
+            >
+              <ChevronRight className="h-4 w-4" />
+            </Button>
+            <Button
+              variant="outline"
+              size="icon"
+              className="h-8 w-8"
+              onClick={() => setPage(totalPages)}
+              disabled={page === totalPages}
+            >
+              <ChevronsRight className="h-4 w-4" />
+            </Button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

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

@@ -0,0 +1,70 @@
+/**
+ * 积分系统配置
+ *
+ * 定义积分系统的常量和套餐配置
+ */
+
+// ============================================
+// 积分配置常量
+// ============================================
+
+/**
+ * 注册奖励积分数量
+ */
+export const REGISTRATION_BONUS_CREDITS = 200;
+
+/**
+ * 订阅用户每月赠送积分数量（默认值，实际按套餐档位）
+ * @deprecated 使用 SUBSCRIPTION_MONTHLY_CREDITS from payment.ts
+ */
+export const MONTHLY_SUBSCRIPTION_CREDITS = 7500;
+
+/**
+ * 积分过期天数（从发放日起）
+ * null 表示永不过期
+ *
+ * 设计理念：Pay as you use - 积分永久有效，用户无需担心过期
+ */
+export const CREDITS_EXPIRY_DAYS = null;
+
+/**
+ * 积分包配置（一次性购买）
+ *
+ * 定价策略：比订阅略贵，鼓励订阅
+ * - Starter 订阅 $2.99 = 4000 积分 (1338 积分/$)
+ * - 积分包约 1000 积分/$（比订阅贵 25%）
+ */
+export const CREDIT_PACKAGES = [
+  {
+    id: "lite",
+    name: "Lite",
+    credits: 3000,
+    price: 3,
+    description: "For a quick study session",
+  },
+  {
+    id: "standard",
+    name: "Standard",
+    credits: 8000,
+    price: 8,
+    popular: true,
+    description: "Most popular top-up",
+  },
+  {
+    id: "pro",
+    name: "Pro",
+    credits: 20000,
+    price: 18,
+    description: "Best value credit pack",
+  },
+] as const;
+
+/**
+ * 积分套餐类型
+ */
+export type CreditPackage = (typeof CREDIT_PACKAGES)[number];
+
+/**
+ * 套餐 ID 类型
+ */
+export type CreditPackageId = CreditPackage["id"];

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

@@ -0,0 +1,140 @@
+/**
+ * 积分消费逻辑 (FIFO)
+ *
+ * 核心 FIFO 逻辑：
+ * 1. 获取所有活跃批次，按过期时间升序排列（最早过期的优先消费）
+ * 2. 循环扣除直到满足需求
+ * 3. 更新批次状态和余额
+ * 4. 记录交易
+ */
+
+import { and, asc, eq, gt, isNull, or, sql } from "drizzle-orm";
+
+import { db } from "@/db";
+import {
+  creditsBalance,
+  creditsBatch,
+  creditsTransaction,
+} from "@/db/schema/credits";
+
+import { AccountFrozenError, InsufficientCreditsError } from "./errors";
+import type { ConsumeCreditsParams, ConsumeCreditsResult } from "./types";
+
+export async function consumeCredits(
+  params: ConsumeCreditsParams
+): Promise<ConsumeCreditsResult> {
+  const { userId, amount, serviceName, description, metadata } = params;
+
+  if (amount <= 0) {
+    throw new Error("消费数量必须大于 0");
+  }
+
+  return await db.transaction(async (tx) => {
+    const [balanceRecord] = await tx
+      .select()
+      .from(creditsBalance)
+      .where(eq(creditsBalance.userId, userId))
+      .limit(1);
+
+    if (!balanceRecord) {
+      throw new InsufficientCreditsError(amount, 0);
+    }
+
+    if (balanceRecord.status === "frozen") {
+      throw new AccountFrozenError(userId);
+    }
+
+    if (balanceRecord.balance < amount) {
+      throw new InsufficientCreditsError(amount, balanceRecord.balance);
+    }
+
+    const now = new Date();
+    const activeBatches = await tx
+      .select()
+      .from(creditsBatch)
+      .where(
+        and(
+          eq(creditsBatch.userId, userId),
+          eq(creditsBatch.status, "active"),
+          gt(creditsBatch.remaining, 0),
+          or(isNull(creditsBatch.expiresAt), gt(creditsBatch.expiresAt, now))
+        )
+      )
+      .orderBy(asc(creditsBatch.expiresAt), asc(creditsBatch.issuedAt));
+
+    let remainingToConsume = amount;
+    const consumedBatches: Array<{
+      batchId: string;
+      consumedFromBatch: number;
+    }> = [];
+
+    for (const batch of activeBatches) {
+      if (remainingToConsume <= 0) {
+        break;
+      }
+
+      const consumeFromThisBatch = Math.min(
+        batch.remaining,
+        remainingToConsume
+      );
+      const newRemaining = batch.remaining - consumeFromThisBatch;
+
+      await tx
+        .update(creditsBatch)
+        .set({
+          remaining: newRemaining,
+          status: newRemaining === 0 ? "consumed" : "active",
+          updatedAt: new Date(),
+        })
+        .where(eq(creditsBatch.id, batch.id));
+
+      consumedBatches.push({
+        batchId: batch.id,
+        consumedFromBatch: consumeFromThisBatch,
+      });
+
+      remainingToConsume -= consumeFromThisBatch;
+    }
+
+    if (remainingToConsume > 0) {
+      throw new InsufficientCreditsError(amount, amount - remainingToConsume);
+    }
+
+    const transactionId = crypto.randomUUID();
+    const debitAccount = `WALLET:${userId}`;
+    const creditAccount = `SERVICE:${serviceName}`;
+
+    await tx.insert(creditsTransaction).values({
+      id: transactionId,
+      userId,
+      type: "consumption",
+      amount,
+      debitAccount,
+      creditAccount,
+      description: description ?? `消费于 ${serviceName}`,
+      metadata: {
+        ...metadata,
+        serviceName,
+        consumedBatches,
+      },
+    });
+
+    const newBalance = balanceRecord.balance - amount;
+    await tx
+      .update(creditsBalance)
+      .set({
+        balance: newBalance,
+        totalSpent: sql`${creditsBalance.totalSpent} + ${amount}`,
+        updatedAt: new Date(),
+      })
+      .where(eq(creditsBalance.userId, userId));
+
+    return {
+      success: true,
+      consumedAmount: amount,
+      remainingBalance: newBalance,
+      transactionId,
+      consumedBatches,
+    };
+  });
+}

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

@@ -0,0 +1,23 @@
+export {
+  ensureCreditsBalance,
+  freezeCreditsAccount,
+  getCreditsBalance,
+  unfreezeCreditsAccount,
+} from "./account";
+export { consumeCredits } from "./consume";
+export {
+  AccountFrozenError,
+  InsufficientCreditsError,
+} from "./errors";
+export { processExpiredBatches } from "./expire";
+export { ensureRegistrationBonus, grantCredits } from "./grant";
+export {
+  getUserActiveBatches,
+  getUserTransactions,
+  getUserTransactionsCount,
+} from "./query";
+export type {
+  ConsumeCreditsParams,
+  ConsumeCreditsResult,
+  GrantCreditsParams,
+} from "./types";

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

@@ -0,0 +1,26 @@
+/**
+ * 积分系统错误类型
+ */
+
+/**
+ * 积分余额错误
+ */
+export class InsufficientCreditsError extends Error {
+  constructor(
+    public required: number,
+    public available: number
+  ) {
+    super(`积分不足: 需要 ${required}，可用 ${available}`);
+    this.name = "InsufficientCreditsError";
+  }
+}
+
+/**
+ * 账户冻结错误
+ */
+export class AccountFrozenError extends Error {
+  constructor(userId: string) {
+    super(`用户 ${userId} 的积分账户已被冻结`);
+    this.name = "AccountFrozenError";
+  }
+}