create-nextdevtpl 2.6.0

package/template/src/db/index.ts

@@ -0,0 +1,71 @@
+import { Pool as NeonPool, neonConfig } from "@neondatabase/serverless";
+import { drizzle as drizzleNeonWs } from "drizzle-orm/neon-serverless";
+import { drizzle as drizzlePg } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+
+import * as schema from "./schema/index";
+
+/**
+ * 数据库连接配置
+ *
+ * 支持两种模式:
+ * 1. Neon Serverless WebSocket (生产/测试环境) - 支持事务，兼容 Node.js 和 Edge Runtime
+ * 2. 标准 PostgreSQL (本地开发/Docker) - 使用连接池
+ *
+ * 注意: Neon 始终使用 WebSocket 模式以支持事务
+ * - Node.js 环境: 需要 ws 包提供 WebSocket
+ * - Edge Runtime (CF Workers/Vercel Edge): 使用原生 WebSocket API
+ */
+
+// 确保环境变量存在
+if (!process.env.DATABASE_URL) {
+  throw new Error(
+    "DATABASE_URL 环境变量未设置，请在 .env 文件中配置数据库连接"
+  );
+}
+
+const databaseUrl = process.env.DATABASE_URL;
+
+/**
+ * 检测是否使用 Neon Serverless
+ */
+const isNeon = databaseUrl.includes("neon.tech");
+
+/**
+ * 检测是否在 Node.js 环境
+ * Edge Runtime (CF Workers, Vercel Edge) 没有 process.versions.node
+ */
+const isNodeJs = typeof process !== "undefined" && process.versions?.node;
+
+/**
+ * 创建数据库实例
+ * - Neon: 使用 WebSocket 连接 (支持事务，兼容 Node.js 和 Edge)
+ * - 标准 PG: 使用连接池 (本地开发/Docker)
+ */
+function createDatabaseConnection() {
+  if (isNeon) {
+    // Node.js 环境需要手动设置 WebSocket 构造函数
+    // Edge Runtime (CF Workers, Vercel Edge) 有原生 WebSocket，无需设置
+    if (isNodeJs) {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const ws = require("ws");
+      neonConfig.webSocketConstructor = ws;
+    }
+
+    // 使用 WebSocket 连接池，支持事务
+    const pool = new NeonPool({ connectionString: databaseUrl });
+    return drizzleNeonWs(pool, { schema });
+  }
+
+  // 标准 PostgreSQL 连接池 (本地开发/Docker)
+  const pool = new Pool({
+    connectionString: databaseUrl,
+  });
+  return drizzlePg(pool, { schema });
+}
+
+// 导出数据库实例
+export const db = createDatabaseConnection();
+
+// 导出 Schema 以便在其他地方使用
+export * from "./schema/index";

package/template/src/db/schema/auth.ts

@@ -0,0 +1,67 @@
+import { boolean, pgEnum, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const userRoleEnum = pgEnum("user_role", ["user", "admin"]);
+
+export const user = pgTable("user", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull().unique(),
+  emailVerified: boolean("email_verified").notNull().default(false),
+  image: text("image"),
+  role: userRoleEnum("role").notNull().default("user"),
+  banned: boolean("banned").notNull().default(false),
+  bannedReason: text("banned_reason"),
+  customerId: text("customer_id").unique(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const session = pgTable("session", {
+  id: text("id").primaryKey(),
+  expiresAt: timestamp("expires_at").notNull(),
+  token: text("token").notNull().unique(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+  ipAddress: text("ip_address"),
+  userAgent: text("user_agent"),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+});
+
+export const account = pgTable("account", {
+  id: text("id").primaryKey(),
+  accountId: text("account_id").notNull(),
+  providerId: text("provider_id").notNull(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  accessToken: text("access_token"),
+  refreshToken: text("refresh_token"),
+  idToken: text("id_token"),
+  accessTokenExpiresAt: timestamp("access_token_expires_at"),
+  refreshTokenExpiresAt: timestamp("refresh_token_expires_at"),
+  scope: text("scope"),
+  password: text("password"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const verification = pgTable("verification", {
+  id: text("id").primaryKey(),
+  identifier: text("identifier").notNull(),
+  value: text("value").notNull(),
+  expiresAt: timestamp("expires_at").notNull(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export type User = typeof user.$inferSelect;
+export type NewUser = typeof user.$inferInsert;
+export type UserRole = (typeof userRoleEnum.enumValues)[number];
+export type Session = typeof session.$inferSelect;
+export type NewSession = typeof session.$inferInsert;
+export type Account = typeof account.$inferSelect;
+export type NewAccount = typeof account.$inferInsert;
+export type Verification = typeof verification.$inferSelect;
+export type NewVerification = typeof verification.$inferInsert;

package/template/src/db/schema/credits.ts

@@ -0,0 +1,94 @@
+import {
+  integer,
+  json,
+  pgEnum,
+  pgTable,
+  text,
+  timestamp,
+} from "drizzle-orm/pg-core";
+
+import { user } from "./auth";
+
+export const creditsBalanceStatusEnum = pgEnum("credits_balance_status", [
+  "active",
+  "frozen",
+]);
+export const creditsBatchStatusEnum = pgEnum("credits_batch_status", [
+  "active",
+  "consumed",
+  "expired",
+]);
+export const creditsBatchSourceEnum = pgEnum("credits_batch_source", [
+  "purchase",
+  "subscription",
+  "bonus",
+  "refund",
+]);
+export const creditsTransactionTypeEnum = pgEnum("credits_transaction_type", [
+  "purchase",
+  "consumption",
+  "monthly_grant",
+  "registration_bonus",
+  "admin_grant",
+  "expiration",
+  "refund",
+]);
+
+export const creditsBalance = pgTable("credits_balance", {
+  id: text("id").primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .unique()
+    .references(() => user.id, { onDelete: "cascade" }),
+  balance: integer("balance").notNull().default(0),
+  totalEarned: integer("total_earned").notNull().default(0),
+  totalSpent: integer("total_spent").notNull().default(0),
+  status: creditsBalanceStatusEnum("status").notNull().default("active"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const creditsBatch = pgTable("credits_batch", {
+  id: text("id").primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  amount: integer("amount").notNull(),
+  remaining: integer("remaining").notNull(),
+  issuedAt: timestamp("issued_at").notNull().defaultNow(),
+  expiresAt: timestamp("expires_at"),
+  status: creditsBatchStatusEnum("status").notNull().default("active"),
+  sourceType: creditsBatchSourceEnum("source_type").notNull(),
+  sourceRef: text("source_ref"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const creditsTransaction = pgTable("credits_transaction", {
+  id: text("id").primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  type: creditsTransactionTypeEnum("type").notNull(),
+  amount: integer("amount").notNull(),
+  debitAccount: text("debit_account").notNull(),
+  creditAccount: text("credit_account").notNull(),
+  description: text("description"),
+  metadata: json("metadata").$type<Record<string, unknown>>(),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});
+
+export type CreditsBalance = typeof creditsBalance.$inferSelect;
+export type NewCreditsBalance = typeof creditsBalance.$inferInsert;
+export type CreditsBatch = typeof creditsBatch.$inferSelect;
+export type NewCreditsBatch = typeof creditsBatch.$inferInsert;
+export type CreditsTransaction = typeof creditsTransaction.$inferSelect;
+export type NewCreditsTransaction = typeof creditsTransaction.$inferInsert;
+export type CreditsBalanceStatus =
+  (typeof creditsBalanceStatusEnum.enumValues)[number];
+export type CreditsBatchStatus =
+  (typeof creditsBatchStatusEnum.enumValues)[number];
+export type CreditsBatchSource =
+  (typeof creditsBatchSourceEnum.enumValues)[number];
+export type CreditsTransactionType =
+  (typeof creditsTransactionTypeEnum.enumValues)[number];

package/template/src/db/schema/index.ts

@@ -0,0 +1,5 @@
+export * from "./auth";
+export * from "./credits";
+export * from "./mail";
+export * from "./subscription";
+export * from "./support";

package/template/src/db/schema/mail.ts

@@ -0,0 +1,14 @@
+import { boolean, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+export const newsletterSubscriber = pgTable("newsletter_subscriber", {
+  id: text("id").primaryKey(),
+  email: text("email").notNull().unique(),
+  isSubscribed: boolean("is_subscribed").notNull().default(true),
+  subscribedAt: timestamp("subscribed_at").notNull().defaultNow(),
+  unsubscribedAt: timestamp("unsubscribed_at"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export type NewsletterSubscriber = typeof newsletterSubscriber.$inferSelect;
+export type NewNewsletterSubscriber = typeof newsletterSubscriber.$inferInsert;

package/template/src/db/schema/subscription.ts

@@ -0,0 +1,21 @@
+import { boolean, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+import { user } from "./auth";
+
+export const subscription = pgTable("subscription", {
+  id: text("id").primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  subscriptionId: text("subscription_id").notNull().unique(),
+  priceId: text("price_id").notNull(),
+  status: text("status").notNull().default("incomplete"),
+  currentPeriodStart: timestamp("current_period_start"),
+  currentPeriodEnd: timestamp("current_period_end"),
+  cancelAtPeriodEnd: boolean("cancel_at_period_end").notNull().default(false),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export type Subscription = typeof subscription.$inferSelect;
+export type NewSubscription = typeof subscription.$inferInsert;

package/template/src/db/schema/support.ts

@@ -0,0 +1,56 @@
+import { boolean, pgEnum, pgTable, text, timestamp } from "drizzle-orm/pg-core";
+
+import { user } from "./auth";
+
+export const ticketCategoryEnum = pgEnum("ticket_category", [
+  "billing",
+  "technical",
+  "bug",
+  "feature",
+  "other",
+]);
+export const ticketPriorityEnum = pgEnum("ticket_priority", [
+  "low",
+  "medium",
+  "high",
+]);
+export const ticketStatusEnum = pgEnum("ticket_status", [
+  "open",
+  "in_progress",
+  "resolved",
+  "closed",
+]);
+
+export const ticket = pgTable("ticket", {
+  id: text("id").primaryKey(),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  subject: text("subject").notNull(),
+  category: ticketCategoryEnum("category").notNull().default("other"),
+  priority: ticketPriorityEnum("priority").notNull().default("medium"),
+  status: ticketStatusEnum("status").notNull().default("open"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+  updatedAt: timestamp("updated_at").notNull().defaultNow(),
+});
+
+export const ticketMessage = pgTable("ticket_message", {
+  id: text("id").primaryKey(),
+  ticketId: text("ticket_id")
+    .notNull()
+    .references(() => ticket.id, { onDelete: "cascade" }),
+  userId: text("user_id")
+    .notNull()
+    .references(() => user.id, { onDelete: "cascade" }),
+  content: text("content").notNull(),
+  isAdminResponse: boolean("is_admin_response").notNull().default(false),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});
+
+export type Ticket = typeof ticket.$inferSelect;
+export type NewTicket = typeof ticket.$inferInsert;
+export type TicketMessage = typeof ticketMessage.$inferSelect;
+export type NewTicketMessage = typeof ticketMessage.$inferInsert;
+export type TicketCategory = (typeof ticketCategoryEnum.enumValues)[number];
+export type TicketPriority = (typeof ticketPriorityEnum.enumValues)[number];
+export type TicketStatus = (typeof ticketStatusEnum.enumValues)[number];

package/template/src/db/schema.ts

@@ -0,0 +1,2 @@
+// 兼容旧导入；新代码应从具体 Schema 分组或 schema/index 导入。
+export * from "./schema/index";

package/template/src/features/admin/components/admin-sidebar.tsx

@@ -0,0 +1,213 @@
+"use client";
+
+import { ArrowLeft, ChevronsUpDown, LogOut } from "lucide-react";
+import Link from "next/link";
+import { usePathname, useRouter } from "next/navigation";
+import { useTranslations } from "next-intl";
+import { useState } from "react";
+
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@/components/ui/popover";
+import { Separator } from "@/components/ui/separator";
+import { adminConfig, siteConfig } from "@/config";
+import { ModeToggle } from "@/features/shared";
+import { signOut, useSession } from "@/lib/auth/client";
+import { cn } from "@/lib/utils";
+
+/**
+ * Admin 侧边栏组件
+ *
+ * 根节点挂 `dark` class，让所有 token 类强制解析为暗色值——侧栏永远是
+ * 深色"控制台"调性，与跟随主题的主内容区形成区分（管理后台的视觉信号）。
+ * 红色（destructive）用于 ADMIN 标识，呼应"管理 = 需谨慎"的语义。
+ */
+export function AdminSidebar() {
+  const pathname = usePathname();
+  const router = useRouter();
+  const t = useTranslations("AdminSidebar");
+
+  const getNavTitle = (title: string, translationKey?: string) =>
+    translationKey ? t(translationKey) : title;
+
+  const { data: session } = useSession();
+  const user = session?.user;
+  const [open, setOpen] = useState(false);
+
+  const getInitials = (name: string) =>
+    name
+      .split(" ")
+      .map((n) => n[0])
+      .join("")
+      .toUpperCase()
+      .slice(0, 2);
+
+  const handleSignOut = async () => {
+    setOpen(false);
+    await signOut({
+      fetchOptions: {
+        onSuccess: () => {
+          router.push("/");
+        },
+      },
+    });
+  };
+
+  return (
+    <aside className="dark fixed left-0 top-0 z-40 flex h-screen w-64 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground">
+      {/* Logo - Admin 标识 */}
+      <div className="flex h-14 items-center gap-2 border-b border-sidebar-border px-4">
+        {/* biome-ignore lint/a11y/noSvgWithoutTitle: decorative logo */}
+        <svg
+          className="h-6 w-6 shrink-0 text-primary"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth={2.4}
+          strokeLinecap="round"
+          strokeLinejoin="round"
+        >
+          <path d="M3 17 L9 7 L13 14 L21 4" />
+          <circle cx="9" cy="7" r="1.4" fill="currentColor" stroke="none" />
+          <circle cx="21" cy="4" r="1.4" fill="currentColor" stroke="none" />
+        </svg>
+        <span className="text-base font-bold tracking-tight">
+          {siteConfig.name}
+        </span>
+        <span className="rounded bg-destructive px-1.5 py-0.5 font-mono text-[10px] font-semibold tracking-[0.12em] text-white">
+          {t("badge")}
+        </span>
+      </div>
+
+      {/* 导航菜单 */}
+      <nav className="flex-1 space-y-6 overflow-y-auto p-3">
+        {adminConfig.sidebarNav.map((group) => (
+          <div key={group.title}>
+            <p className="mb-1.5 px-2 font-mono text-[10px] font-semibold tracking-[0.14em] text-sidebar-foreground/40 uppercase">
+              {getNavTitle(group.title, group.translationKey)}
+            </p>
+            <div className="space-y-0.5">
+              {group.items.map((item) => {
+                const isActive = pathname.endsWith(item.href);
+                const Icon = item.icon;
+                return (
+                  <Link
+                    key={item.href}
+                    href={item.href}
+                    className={cn(
+                      "flex items-center gap-3 rounded-md px-2 py-1.5 text-sm font-medium transition-colors",
+                      isActive
+                        ? "bg-primary/10 text-primary"
+                        : "text-sidebar-foreground/70 hover:bg-sidebar-accent/50 hover:text-sidebar-foreground"
+                    )}
+                  >
+                    {Icon && <Icon className="h-4 w-4 shrink-0" />}
+                    {getNavTitle(item.title, item.translationKey)}
+                  </Link>
+                );
+              })}
+            </div>
+          </div>
+        ))}
+
+        {/* 返回用户端链接 */}
+        <div className="border-t border-sidebar-border pt-3">
+          <Link
+            href="/dashboard"
+            className="flex items-center gap-3 rounded-md px-2 py-1.5 text-sm font-medium text-sidebar-foreground/70 transition-colors hover:bg-sidebar-accent/50 hover:text-sidebar-foreground"
+          >
+            <ArrowLeft className="h-4 w-4" />
+            {t("returnToUser")}
+          </Link>
+        </div>
+      </nav>
+
+      {/* 用户信息区域 */}
+      <div className="border-t border-sidebar-border p-3">
+        {user ? (
+          <Popover open={open} onOpenChange={setOpen}>
+            <PopoverTrigger asChild>
+              <button
+                type="button"
+                className="flex w-full items-center gap-3 rounded-md px-2 py-1.5 transition-colors hover:bg-sidebar-accent/50"
+              >
+                <Avatar className="h-8 w-8 shrink-0">
+                  <AvatarImage src={user.image || undefined} alt={user.name} />
+                  <AvatarFallback className="bg-destructive text-xs text-white">
+                    {getInitials(user.name)}
+                  </AvatarFallback>
+                </Avatar>
+                <div className="flex-1 truncate text-left">
+                  <div className="flex items-center gap-2">
+                    <p className="text-sm font-medium">{user.name}</p>
+                    <span className="rounded bg-destructive/15 px-1.5 py-0.5 font-mono text-[10px] font-semibold text-destructive">
+                      {t("roleBadge")}
+                    </span>
+                  </div>
+                  <p className="truncate text-xs text-sidebar-foreground/50">
+                    {user.email}
+                  </p>
+                </div>
+                <ChevronsUpDown className="h-4 w-4 text-sidebar-foreground/50" />
+              </button>
+            </PopoverTrigger>
+
+            <PopoverContent
+              side="top"
+              align="start"
+              sideOffset={8}
+              className="w-64 p-0"
+            >
+              <div className="flex items-center gap-3 p-4">
+                <Avatar className="h-10 w-10">
+                  <AvatarImage src={user.image || undefined} alt={user.name} />
+                  <AvatarFallback className="bg-destructive text-white">
+                    {getInitials(user.name)}
+                  </AvatarFallback>
+                </Avatar>
+                <div className="flex-1 truncate">
+                  <p className="font-medium">{user.name}</p>
+                  <p className="truncate text-sm text-muted-foreground">
+                    {user.email}
+                  </p>
+                </div>
+              </div>
+
+              <Separator />
+
+              {/* 主题切换 - 用共享 ModeToggle，真正生效 */}
+              <div className="flex items-center justify-center p-3">
+                <ModeToggle variant="inline" />
+              </div>
+
+              <Separator />
+
+              <div className="p-2">
+                <button
+                  type="button"
+                  onClick={handleSignOut}
+                  className="flex w-full items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors hover:bg-muted"
+                >
+                  <LogOut className="h-4 w-4" />
+                  {t("signOut")}
+                </button>
+              </div>
+            </PopoverContent>
+          </Popover>
+        ) : (
+          // 加载状态
+          <div className="flex items-center gap-3 rounded-md px-2 py-1.5">
+            <div className="h-8 w-8 animate-pulse rounded-full bg-sidebar-accent" />
+            <div className="flex-1 space-y-1">
+              <div className="h-4 w-20 animate-pulse rounded bg-sidebar-accent" />
+              <div className="h-3 w-32 animate-pulse rounded bg-sidebar-accent" />
+            </div>
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+}

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

@@ -0,0 +1,2 @@
+// Admin 组件导出
+export { AdminSidebar } from "./admin-sidebar";

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

@@ -0,0 +1,3 @@
+// Admin Feature
+export * from "./components";
+export { adminModule } from "./manifest";

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

@@ -0,0 +1,41 @@
+import { defineModule } from "@/core/modules";
+
+export const adminModule = defineModule({
+  id: "admin",
+  name: "Admin",
+  description: "管理后台、用户管理与平台运营入口",
+  kind: "optional",
+  dependencies: ["shared", "support"],
+  routes: [
+    {
+      path: "/admin",
+      source: "src/app/[locale]/(admin)/admin/page.tsx",
+    },
+    {
+      path: "/admin/users",
+      source: "src/app/[locale]/(admin)/admin/users/page.tsx",
+    },
+  ],
+  navigation: [
+    {
+      area: "admin",
+      group: "control-panel",
+      groupTranslationKey: "nav.controlPanel",
+      translationKey: "nav.dashboard",
+      href: "/admin",
+      icon: "dashboard",
+      order: 10,
+    },
+    {
+      area: "admin",
+      group: "control-panel",
+      groupTranslationKey: "nav.controlPanel",
+      translationKey: "nav.userManagement",
+      href: "/admin/users",
+      icon: "users",
+      order: 20,
+    },
+  ],
+  translations: ["AdminSidebar"],
+  schema: [],
+});

package/template/src/features/analytics/components/analytics.tsx

@@ -0,0 +1,62 @@
+"use client";
+
+import { GoogleAnalytics } from "@next/third-parties/google";
+import { useEffect, useState } from "react";
+
+import {
+  COOKIE_CONSENT_CHANGE_EVENT,
+  COOKIE_CONSENT_KEY,
+} from "@/lib/cookie-consent";
+
+/**
+ * Analytics 组件
+ *
+ * 功能:
+ * - 条件渲染 Google Analytics
+ * - 仅在用户接受 Cookie 时加载
+ * - 监听 localStorage 变化以响应用户偏好更改
+ */
+export function Analytics() {
+  const [hasConsent, setHasConsent] = useState(false);
+  const gaId = process.env.NEXT_PUBLIC_GA_ID;
+
+  useEffect(() => {
+    // 检查初始同意状态
+    const checkConsent = () => {
+      const consent = localStorage.getItem(COOKIE_CONSENT_KEY);
+      setHasConsent(consent === "all");
+    };
+
+    checkConsent();
+
+    // 监听 storage 事件以响应其他标签页的更改
+    const handleStorageChange = (e: StorageEvent) => {
+      if (e.key === COOKIE_CONSENT_KEY) {
+        checkConsent();
+      }
+    };
+
+    // 监听自定义事件以响应同一页面的更改
+    const handleConsentChange = () => {
+      checkConsent();
+    };
+
+    window.addEventListener("storage", handleStorageChange);
+    window.addEventListener(COOKIE_CONSENT_CHANGE_EVENT, handleConsentChange);
+
+    return () => {
+      window.removeEventListener("storage", handleStorageChange);
+      window.removeEventListener(
+        COOKIE_CONSENT_CHANGE_EVENT,
+        handleConsentChange
+      );
+    };
+  }, []);
+
+  // 未配置 GA ID 或未同意时不渲染
+  if (!gaId || !hasConsent) {
+    return null;
+  }
+
+  return <GoogleAnalytics gaId={gaId} />;
+}

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

@@ -0,0 +1,2 @@
+// Analytics Components
+export { Analytics } from "./analytics";

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

@@ -0,0 +1,3 @@
+// Analytics System
+export * from "./components";
+export { analyticsModule } from "./manifest";