create-nextdevtpl 2.6.0

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

@@ -0,0 +1,112 @@
+/**
+ * 积分过期处理
+ *
+ * 扫描并标记所有过期的批次，同时更新用户余额。
+ * 使用条件更新保证同一批次在并发运行时只会被处理一次。
+ */
+
+import { and, eq, gt, lt, sql } from "drizzle-orm";
+
+import { db } from "@/db";
+import {
+  creditsBalance,
+  creditsBatch,
+  creditsTransaction,
+} from "@/db/schema/credits";
+import { logEvent } from "@/lib/logger";
+
+export async function processExpiredBatches() {
+  const now = new Date();
+
+  const expiredBatches = await db
+    .select({
+      id: creditsBatch.id,
+    })
+    .from(creditsBatch)
+    .where(
+      and(
+        eq(creditsBatch.status, "active"),
+        lt(creditsBatch.expiresAt, now),
+        gt(creditsBatch.remaining, 0)
+      )
+    );
+
+  const results: Array<{
+    batchId: string;
+    userId: string;
+    expiredAmount: number;
+  }> = [];
+
+  for (const batch of expiredBatches) {
+    await db.transaction(async (tx) => {
+      const [expiredBatch] = await tx
+        .update(creditsBatch)
+        .set({
+          status: "expired",
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(creditsBatch.id, batch.id),
+            eq(creditsBatch.status, "active"),
+            gt(creditsBatch.remaining, 0)
+          )
+        )
+        .returning({
+          id: creditsBatch.id,
+          userId: creditsBatch.userId,
+          amount: creditsBatch.amount,
+          remaining: creditsBatch.remaining,
+          expiresAt: creditsBatch.expiresAt,
+        });
+
+      if (!expiredBatch) {
+        return;
+      }
+
+      const transactionId = crypto.randomUUID();
+      await tx.insert(creditsTransaction).values({
+        id: transactionId,
+        userId: expiredBatch.userId,
+        type: "expiration",
+        amount: expiredBatch.remaining,
+        debitAccount: `WALLET:${expiredBatch.userId}`,
+        creditAccount: "SYSTEM:expired",
+        description: `批次 ${expiredBatch.id} 过期`,
+        metadata: {
+          batchId: expiredBatch.id,
+          originalAmount: expiredBatch.amount,
+          expiredAmount: expiredBatch.remaining,
+          expiresAt: expiredBatch.expiresAt,
+        },
+      });
+
+      await tx
+        .update(creditsBalance)
+        .set({
+          balance: sql`${creditsBalance.balance} - ${expiredBatch.remaining}`,
+          updatedAt: new Date(),
+        })
+        .where(eq(creditsBalance.userId, expiredBatch.userId));
+
+      results.push({
+        batchId: expiredBatch.id,
+        userId: expiredBatch.userId,
+        expiredAmount: expiredBatch.remaining,
+      });
+    });
+  }
+
+  if (results.length > 0) {
+    const totalExpired = results.reduce(
+      (sum, item) => sum + item.expiredAmount,
+      0
+    );
+    logEvent("credits.expired", {
+      count: results.length,
+      totalExpired,
+    });
+  }
+
+  return results;
+}

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

@@ -0,0 +1,168 @@
+/**
+ * 积分发放逻辑
+ *
+ * 在事务中执行：
+ * 1. 创建积分批次
+ * 2. 记录交易（双重记账）
+ * 3. 更新余额
+ */
+
+import { eq, sql } from "drizzle-orm";
+
+import { db } from "@/db";
+import {
+  creditsBalance,
+  creditsBatch,
+  creditsTransaction,
+} from "@/db/schema/credits";
+
+import { AccountFrozenError } from "./errors";
+import type { GrantCreditsParams } from "./types";
+
+/**
+ * 发放积分
+ */
+export async function grantCredits(params: GrantCreditsParams) {
+  const {
+    userId,
+    amount,
+    sourceType,
+    debitAccount,
+    transactionType,
+    expiresAt = null,
+    sourceRef,
+    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);
+
+    let currentBalance = balanceRecord;
+
+    if (!currentBalance) {
+      const [newBalance] = await tx
+        .insert(creditsBalance)
+        .values({
+          id: crypto.randomUUID(),
+          userId,
+          balance: 0,
+          totalEarned: 0,
+          totalSpent: 0,
+          status: "active",
+        })
+        .returning();
+
+      if (!newBalance) {
+        throw new Error("创建积分账户失败");
+      }
+
+      currentBalance = newBalance;
+    }
+
+    if (currentBalance.status === "frozen") {
+      throw new AccountFrozenError(userId);
+    }
+
+    const batchId = crypto.randomUUID();
+    await tx.insert(creditsBatch).values({
+      id: batchId,
+      userId,
+      amount,
+      remaining: amount,
+      issuedAt: new Date(),
+      expiresAt,
+      status: "active",
+      sourceType,
+      sourceRef,
+    });
+
+    const transactionId = crypto.randomUUID();
+    const creditAccount = `WALLET:${userId}`;
+
+    await tx.insert(creditsTransaction).values({
+      id: transactionId,
+      userId,
+      type: transactionType,
+      amount,
+      debitAccount,
+      creditAccount,
+      description,
+      metadata: {
+        ...metadata,
+        batchId,
+        sourceRef,
+      },
+    });
+
+    await tx
+      .update(creditsBalance)
+      .set({
+        balance: sql`${creditsBalance.balance} + ${amount}`,
+        totalEarned: sql`${creditsBalance.totalEarned} + ${amount}`,
+        updatedAt: new Date(),
+      })
+      .where(eq(creditsBalance.userId, userId));
+
+    return {
+      batchId,
+      transactionId,
+      amount,
+      newBalance: currentBalance.balance + amount,
+    };
+  });
+}
+
+/**
+ * 确保用户获得注册奖励
+ *
+ * 懒加载机制：
+ * 1. 检查用户是否已有交易记录
+ * 2. 如果没有任何交易记录，说明是新用户，发放注册奖励
+ */
+export async function ensureRegistrationBonus(
+  userId: string,
+  bonusAmount: number,
+  expiryDays: number | null
+) {
+  const [existingTransaction] = await db
+    .select({ id: creditsTransaction.id })
+    .from(creditsTransaction)
+    .where(eq(creditsTransaction.userId, userId))
+    .limit(1);
+
+  if (existingTransaction) {
+    return { granted: false, reason: "User already has transactions" };
+  }
+
+  const expiresAt = expiryDays
+    ? new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000)
+    : null;
+
+  const result = await grantCredits({
+    userId,
+    amount: bonusAmount,
+    sourceType: "bonus",
+    debitAccount: "SYSTEM:registration_bonus",
+    transactionType: "registration_bonus",
+    expiresAt,
+    description: "新用户注册奖励",
+    metadata: {
+      bonusType: "registration",
+      grantedAt: new Date().toISOString(),
+    },
+  });
+
+  return {
+    granted: true,
+    ...result,
+  };
+}

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

@@ -0,0 +1,6 @@
+// Credits System
+export * from "./actions";
+export * from "./components";
+export * from "./config";
+export * from "./core";
+export { creditsModule } from "./manifest";

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

@@ -0,0 +1,36 @@
+import { defineModule } from "@/core/modules";
+
+export const creditsModule = defineModule({
+  id: "credits",
+  name: "Credits",
+  description: "积分账户、批次、交易与过期处理",
+  kind: "optional",
+  dependencies: ["payment"],
+  routes: [
+    {
+      path: "/dashboard/credits",
+      source: "src/app/[locale]/(dashboard)/dashboard/credits/page.tsx",
+    },
+    {
+      path: "/dashboard/credits/buy",
+      source: "src/app/[locale]/(dashboard)/dashboard/credits/buy/page.tsx",
+    },
+    {
+      path: "/api/jobs/credits/expire",
+      source: "src/app/api/jobs/credits/expire/route.ts",
+    },
+  ],
+  navigation: [
+    {
+      area: "dashboard",
+      group: "dashboard",
+      groupTranslationKey: "nav.dashboard",
+      translationKey: "nav.credits",
+      href: "/dashboard/credits",
+      icon: "coins",
+      order: 20,
+    },
+  ],
+  translations: ["CreditTransactions"],
+  schema: ["credits"],
+});

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

@@ -0,0 +1,65 @@
+/**
+ * 积分查询逻辑
+ */
+
+import { and, asc, eq, gt, isNull, or, sql } from "drizzle-orm";
+
+import { db } from "@/db";
+import { creditsBatch, creditsTransaction } from "@/db/schema/credits";
+
+/**
+ * 获取用户的活跃批次列表
+ */
+export async function getUserActiveBatches(userId: string) {
+  const now = new Date();
+
+  return await db
+    .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));
+}
+
+/**
+ * 获取用户的交易历史
+ */
+export async function getUserTransactions(
+  userId: string,
+  options?: {
+    limit?: number;
+    offset?: number;
+  }
+) {
+  const { limit = 20, offset = 0 } = options ?? {};
+
+  return await db
+    .select()
+    .from(creditsTransaction)
+    .where(eq(creditsTransaction.userId, userId))
+    .orderBy(sql`${creditsTransaction.createdAt} DESC`)
+    .limit(limit)
+    .offset(offset);
+}
+
+/**
+ * 获取用户交易总数
+ */
+export async function getUserTransactionsCount(
+  userId: string
+): Promise<number> {
+  const [result] = await db
+    .select({
+      count: sql<number>`count(*)`.mapWith(Number),
+    })
+    .from(creditsTransaction)
+    .where(eq(creditsTransaction.userId, userId));
+
+  return result?.count ?? 0;
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 积分系统类型定义
+ */
+
+import type {
+  CreditsBatchSource,
+  CreditsTransactionType,
+} from "@/db/schema/credits";
+
+/**
+ * 发放积分参数
+ */
+export interface GrantCreditsParams {
+  userId: string;
+  amount: number;
+  sourceType: CreditsBatchSource;
+  debitAccount: string;
+  transactionType: CreditsTransactionType;
+  expiresAt?: Date | null;
+  sourceRef?: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 消费积分参数
+ */
+export interface ConsumeCreditsParams {
+  userId: string;
+  amount: number;
+  serviceName: string;
+  description?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * 积分消费结果
+ */
+export interface ConsumeCreditsResult {
+  success: boolean;
+  consumedAmount: number;
+  remainingBalance: number;
+  transactionId: string;
+  consumedBatches: Array<{
+    batchId: string;
+    consumedFromBatch: number;
+  }>;
+}

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

@@ -0,0 +1,3 @@
+// Dashboard 外壳组件（布局）
+export { DashboardMainWrapper } from "./main-wrapper";
+export { DashboardSidebar } from "./sidebar";

package/template/src/features/dashboard/components/main-wrapper.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { Menu, PanelLeft, PanelLeftClose } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { useTranslations } from "next-intl";
+
+import { useSidebar } from "@/features/dashboard/context";
+import { cn } from "@/lib/utils";
+
+/**
+ * 从路径名获取页面标题翻译键
+ */
+function getPageTitleKey(pathname: string): string {
+  const path = pathname.replace(/^\/[a-z]{2}\//, "/");
+  const keyMap: Record<string, string> = {
+    "/dashboard": "dashboard",
+    "/dashboard/support": "support",
+    "/dashboard/support/new": "newTicket",
+    "/dashboard/settings": "settings",
+    "/dashboard/credits/buy": "credits",
+  };
+
+  // 精确匹配
+  if (keyMap[path]) {
+    return keyMap[path];
+  }
+
+  // 动态路由：工单详情
+  if (path.startsWith("/dashboard/support/")) {
+    return "ticketDetails";
+  }
+
+  return "dashboard";
+}
+
+/**
+ * Dashboard 主内容区域包装器
+ *
+ * 根据侧边栏折叠状态动态调整左边距
+ * 内容区域为卡片样式，包含 Header 和内容
+ */
+export function DashboardMainWrapper({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const { isCollapsed, toggleSidebar, toggleMobile } = useSidebar();
+  const pathname = usePathname();
+  const t = useTranslations("Dashboard.pages");
+  const pageTitleKey = getPageTitleKey(pathname);
+  const pageTitle = t(pageTitleKey);
+
+  return (
+    <main
+      className={cn(
+        "p-2.5 min-h-screen transition-all duration-300",
+        isCollapsed ? "md:ml-16" : "md:ml-64"
+      )}
+    >
+      {/* 卡片容器 - Linear style: clean background, subtle border */}
+      <div className="min-h-[calc(100vh-20px)] rounded-lg bg-background border border-border flex flex-col">
+        {/* Header - 在卡片内部 */}
+        <header className="flex h-12 items-center gap-3 border-b border-border px-4 shrink-0">
+          {/* 移动端汉堡按钮 */}
+          <button
+            type="button"
+            onClick={toggleMobile}
+            className="flex h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-accent transition-colors cursor-pointer md:hidden"
+          >
+            <Menu className="h-4 w-4 pointer-events-none" />
+          </button>
+
+          {/* 桌面端侧边栏折叠按钮 */}
+          <button
+            type="button"
+            onClick={toggleSidebar}
+            className="hidden h-7 w-7 items-center justify-center rounded-md text-muted-foreground hover:text-foreground hover:bg-accent transition-colors cursor-pointer md:flex"
+          >
+            {isCollapsed ? (
+              <PanelLeft className="h-4 w-4 pointer-events-none" />
+            ) : (
+              <PanelLeftClose className="h-4 w-4 pointer-events-none" />
+            )}
+          </button>
+
+          {/* 分割线 - 与文字等高，淡色 */}
+          <div className="h-4 w-px bg-border" />
+
+          {/* 页面标题 */}
+          <span className="text-sm font-medium text-foreground">
+            {pageTitle}
+          </span>
+        </header>
+
+        {/* 内容区域 */}
+        <div className="flex-1 p-6">{children}</div>
+      </div>
+    </main>
+  );
+}