create-nextdevtpl 2.6.0

package/template/src/lib/logger/index.ts

@@ -0,0 +1,258 @@
+/**
+ * 日志模块
+ *
+ * 使用 Pino 实现结构化日志
+ * 支持 Axiom 云日志服务（可选）
+ * 未配置时回退到 console 输出
+ *
+ * 环境变量:
+ * - AXIOM_TOKEN: Axiom API Token（可选）
+ * - AXIOM_DATASET: Axiom 数据集名称（可选，默认 "nextdevtpl"）
+ */
+
+import pino from "pino";
+
+// ============================================
+// 配置检查
+// ============================================
+
+/**
+ * 检查是否为生产环境
+ */
+function isProduction(): boolean {
+  return process.env.NODE_ENV === "production";
+}
+
+// ============================================
+// Logger 创建
+// ============================================
+
+/**
+ * 创建 Logger 实例
+ *
+ * 日志级别:
+ * - production: info 及以上
+ * - development: debug 及以上
+ *
+ * 输出目标:
+ * - 配置了 Axiom: 发送到 Axiom + console
+ * - 未配置 Axiom: 仅 console（开发环境美化输出）
+ */
+function createLogger(): pino.Logger {
+  const level = isProduction() ? "info" : "debug";
+
+  // 基础配置
+  const baseOptions: pino.LoggerOptions = {
+    level,
+    base: {
+      env: process.env.NODE_ENV,
+      service: "nextdevtpl",
+    },
+    timestamp: pino.stdTimeFunctions.isoTime,
+  };
+
+  // 开发环境：美化输出
+  if (!isProduction()) {
+    try {
+      return pino({
+        ...baseOptions,
+        transport: {
+          target: "pino-pretty",
+          options: {
+            colorize: true,
+            translateTime: "SYS:standard",
+            ignore: "pid,hostname",
+          },
+        },
+      });
+    } catch {
+      // pino-pretty 不可用时降级
+      return pino(baseOptions);
+    }
+  }
+
+  // 生产环境：结构化 JSON 输出到 stdout
+  // 注: pino transport（@axiomhq/pino）在 Turbopack 打包后无法工作
+  // 因为 transport 使用 worker_threads 按字符串路径动态加载模块
+  // 生产环境日志收集建议通过外部采集（如 Axiom 的 Vercel Integration 或 log drain）
+  return pino(baseOptions);
+}
+
+// ============================================
+// Logger 实例（单例）
+// ============================================
+
+/**
+ * 全局 Logger 实例
+ */
+export const logger = createLogger();
+
+// ============================================
+// 便捷方法
+// ============================================
+
+/**
+ * 创建带上下文的子 Logger
+ *
+ * @example
+ * ```ts
+ * const log = createContextLogger({ userId: "123", requestId: "abc" });
+ * log.info("User action");
+ * ```
+ */
+export function createContextLogger(
+  context: Record<string, unknown>
+): pino.Logger {
+  return logger.child(context);
+}
+
+/**
+ * 创建请求级别的 Logger
+ *
+ * @example
+ * ```ts
+ * const log = createRequestLogger(request);
+ * log.info("Processing request");
+ * ```
+ */
+export function createRequestLogger(request: Request): pino.Logger {
+  const url = new URL(request.url);
+
+  return logger.child({
+    requestId: crypto.randomUUID(),
+    method: request.method,
+    path: url.pathname,
+    userAgent: request.headers.get("user-agent")?.slice(0, 100),
+  });
+}
+
+// ============================================
+// 类型化日志辅助
+// ============================================
+
+/**
+ * 业务事件类型
+ */
+export type BusinessEvent =
+  | "user.signup"
+  | "user.login"
+  | "user.logout"
+  | "payment.checkout.started"
+  | "payment.checkout.completed"
+  | "payment.credits.already_granted"
+  | "payment.credits.grant_success"
+  | "payment.subscription.created"
+  | "payment.subscription.canceled"
+  | "payment.subscription.past_due"
+  | "payment.subscription.paused"
+  | "payment.subscription.upserted"
+  | "credits.purchased"
+  | "credits.consumed"
+  | "credits.expired"
+  | "ticket.created"
+  | "ticket.replied"
+  | "ticket.closed"
+  | "email.sent"
+  | "file.uploaded"
+  | "file.deleted"
+  | "admin.user.banned"
+  | "admin.user.unbanned";
+
+/**
+ * 记录业务事件
+ *
+ * @example
+ * ```ts
+ * logEvent("user.signup", { userId: "123", provider: "github" });
+ * logEvent("payment.checkout.completed", { userId: "123", amount: 9.99 });
+ * ```
+ */
+export function logEvent(
+  event: BusinessEvent,
+  data?: Record<string, unknown>
+): void {
+  logger.info({ event, ...data }, `Event: ${event}`);
+}
+
+/**
+ * 记录错误（带堆栈）
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   logError(error, { context: "payment processing" });
+ * }
+ * ```
+ */
+export function logError(
+  error: unknown,
+  context?: Record<string, unknown>
+): void {
+  if (error instanceof Error) {
+    logger.error(
+      {
+        err: {
+          name: error.name,
+          message: error.message,
+          stack: error.stack,
+        },
+        ...context,
+      },
+      error.message
+    );
+  } else {
+    logger.error({ err: error, ...context }, "Unknown error");
+  }
+}
+
+/**
+ * 记录警告
+ */
+export function logWarn(message: string, data?: Record<string, unknown>): void {
+  logger.warn(data, message);
+}
+
+/**
+ * 记录调试信息（仅开发环境）
+ */
+export function logDebug(
+  message: string,
+  data?: Record<string, unknown>
+): void {
+  logger.debug(data, message);
+}
+
+// ============================================
+// API 响应日志
+// ============================================
+
+/**
+ * 记录 API 响应
+ */
+export function logApiResponse(
+  request: Request,
+  response: Response,
+  duration: number
+): void {
+  const url = new URL(request.url);
+  const level =
+    response.status >= 500 ? "error" : response.status >= 400 ? "warn" : "info";
+
+  logger[level](
+    {
+      method: request.method,
+      path: url.pathname,
+      status: response.status,
+      duration,
+    },
+    `${request.method} ${url.pathname} ${response.status} ${duration}ms`
+  );
+}
+
+// ============================================
+// 导出类型
+// ============================================
+
+export type { Logger } from "pino";

package/template/src/lib/monitoring/index.ts

@@ -0,0 +1,384 @@
+/**
+ * 错误监控模块
+ *
+ * 使用 Sentry 实现错误监控和性能追踪
+ * 未配置时跳过所有 Sentry 操作（优雅降级）
+ *
+ * 环境变量:
+ * - NEXT_PUBLIC_SENTRY_DSN: Sentry DSN（可选）
+ * - SENTRY_AUTH_TOKEN: Sentry Auth Token（用于 source map 上传，可选）
+ */
+
+import * as Sentry from "@sentry/nextjs";
+
+// ============================================
+// 配置检查
+// ============================================
+
+/**
+ * 检查 Sentry 是否已配置
+ */
+export function isSentryEnabled(): boolean {
+  return !!process.env.NEXT_PUBLIC_SENTRY_DSN;
+}
+
+// ============================================
+// Sentry 初始化
+// ============================================
+
+/**
+ * 初始化 Sentry（服务端）
+ *
+ * 在 instrumentation.ts 中调用
+ */
+export function initSentryServer(): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.init({
+    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+    environment: process.env.NODE_ENV,
+
+    // 性能监控采样率
+    tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
+
+    // 错误采样率
+    sampleRate: 1.0,
+
+    // 调试模式（仅开发环境）
+    debug: process.env.NODE_ENV === "development",
+
+    // 忽略常见的无害错误
+    ignoreErrors: [
+      // 网络错误
+      "Network request failed",
+      "Failed to fetch",
+      "NetworkError",
+      "AbortError",
+      // 用户取消
+      "User cancelled",
+      "User denied",
+      // 常见的第三方脚本错误
+      "Script error",
+      "Non-Error promise rejection",
+    ],
+
+    // 过滤敏感数据
+    beforeSend(event) {
+      // 过滤掉敏感信息
+      if (event.request?.headers) {
+        delete event.request.headers.authorization;
+        delete event.request.headers.cookie;
+      }
+      return event;
+    },
+  });
+}
+
+/**
+ * 初始化 Sentry（客户端）
+ *
+ * 在 sentry.client.config.ts 中调用
+ */
+export function initSentryClient(): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.init({
+    dsn: process.env.NEXT_PUBLIC_SENTRY_DSN,
+    environment: process.env.NODE_ENV,
+
+    // 性能监控
+    tracesSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 1.0,
+
+    // Replay 配置（可选）
+    replaysSessionSampleRate: 0,
+    replaysOnErrorSampleRate: process.env.NODE_ENV === "production" ? 0.1 : 0,
+
+    // 调试模式
+    debug: false,
+
+    // 忽略常见错误
+    ignoreErrors: [
+      "Network request failed",
+      "Failed to fetch",
+      "Script error",
+      "ResizeObserver loop",
+    ],
+  });
+}
+
+// ============================================
+// 错误捕获 API
+// ============================================
+
+/**
+ * 捕获异常
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   captureError(error, { userId: "123", action: "checkout" });
+ * }
+ * ```
+ */
+export function captureError(
+  error: unknown,
+  context?: Record<string, unknown>
+): void {
+  if (!isSentryEnabled()) {
+    // 未配置时打印到 console
+    console.error("[Error]", error, context);
+    return;
+  }
+
+  if (context) {
+    Sentry.captureException(error, { extra: context });
+  } else {
+    Sentry.captureException(error);
+  }
+}
+
+/**
+ * 捕获消息（非错误事件）
+ *
+ * @example
+ * ```ts
+ * captureMessage("User attempted invalid action", "warning", { userId: "123" });
+ * ```
+ */
+export function captureMessage(
+  message: string,
+  level: Sentry.SeverityLevel = "info",
+  context?: Record<string, unknown>
+): void {
+  if (!isSentryEnabled()) {
+    const logFn =
+      level === "error"
+        ? console.error
+        : level === "warning"
+          ? console.warn
+          : console.log;
+    logFn(`[${level}]`, message, context);
+    return;
+  }
+
+  if (context) {
+    Sentry.captureMessage(message, { level, extra: context });
+  } else {
+    Sentry.captureMessage(message, level);
+  }
+}
+
+// ============================================
+// 用户上下文
+// ============================================
+
+/**
+ * 设置用户上下文
+ *
+ * @example
+ * ```ts
+ * setUser({ id: "123", email: "user@example.com" });
+ * ```
+ */
+export function setUser(
+  user: {
+    id: string;
+    email?: string;
+    username?: string;
+  } | null
+): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.setUser(user);
+}
+
+/**
+ * 清除用户上下文（登出时调用）
+ */
+export function clearUser(): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.setUser(null);
+}
+
+// ============================================
+// 标签和上下文
+// ============================================
+
+/**
+ * 设置标签
+ *
+ * @example
+ * ```ts
+ * setTag("payment_provider", "creem");
+ * ```
+ */
+export function setTag(key: string, value: string): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.setTag(key, value);
+}
+
+/**
+ * 设置额外上下文
+ *
+ * @example
+ * ```ts
+ * setContext("order", { orderId: "123", amount: 99.99 });
+ * ```
+ */
+export function setContext(
+  name: string,
+  context: Record<string, unknown>
+): void {
+  if (!isSentryEnabled()) {
+    return;
+  }
+
+  Sentry.setContext(name, context);
+}
+
+// ============================================
+// 性能追踪
+// ============================================
+
+/**
+ * 开始一个性能 Span
+ *
+ * @example
+ * ```ts
+ * const span = startSpan("database.query", "SELECT * FROM users");
+ * await db.query(...);
+ * span?.end();
+ * ```
+ */
+export function startSpan(
+  operation: string,
+  description?: string
+): Sentry.Span | undefined {
+  if (!isSentryEnabled()) {
+    return undefined;
+  }
+
+  return Sentry.startInactiveSpan({
+    op: operation,
+    name: description ?? operation,
+  });
+}
+
+/**
+ * 包装异步操作并追踪性能
+ *
+ * @example
+ * ```ts
+ * const result = await withSpan("api.call", "Fetch user data", async () => {
+ *   return await fetchUser(userId);
+ * });
+ * ```
+ */
+export async function withSpan<T>(
+  operation: string,
+  description: string,
+  fn: () => Promise<T>
+): Promise<T> {
+  if (!isSentryEnabled()) {
+    return fn();
+  }
+
+  return Sentry.startSpan(
+    {
+      op: operation,
+      name: description,
+    },
+    fn
+  );
+}
+
+// ============================================
+// Server Action 包装器
+// ============================================
+
+/**
+ * 包装 Server Action 以自动捕获错误
+ *
+ * @example
+ * ```ts
+ * export const myAction = withSentryAction(async (input: Input) => {
+ *   // action logic
+ *   return { success: true };
+ * });
+ * ```
+ */
+export function withSentryAction<TInput, TOutput>(
+  action: (input: TInput) => Promise<TOutput>
+): (input: TInput) => Promise<TOutput> {
+  return async (input: TInput) => {
+    try {
+      return await action(input);
+    } catch (error) {
+      captureError(error, { action: action.name, input });
+      throw error;
+    }
+  };
+}
+
+// ============================================
+// API Route 包装器
+// ============================================
+
+/**
+ * 包装 API Route Handler 以自动捕获错误
+ *
+ * @example
+ * ```ts
+ * export const GET = withSentryHandler(async (request) => {
+ *   // handler logic
+ *   return NextResponse.json({ data });
+ * });
+ * ```
+ */
+export function withSentryHandler<T extends Response>(
+  handler: (request: Request) => Promise<T>
+): (request: Request) => Promise<T | Response> {
+  return async (request: Request) => {
+    try {
+      return await handler(request);
+    } catch (error) {
+      const url = new URL(request.url);
+      captureError(error, {
+        method: request.method,
+        path: url.pathname,
+      });
+
+      // 返回通用错误响应
+      return new Response(
+        JSON.stringify({
+          error: "Internal Server Error",
+          message: "服务器内部错误，请稍后重试",
+        }),
+        {
+          status: 500,
+          headers: { "Content-Type": "application/json" },
+        }
+      );
+    }
+  };
+}
+
+// ============================================
+// 重新导出 Sentry 类型
+// ============================================
+
+export type { SeverityLevel } from "@sentry/nextjs";

package/template/src/lib/rate-limit/anonymous.ts

@@ -0,0 +1,85 @@
+import { headers } from "next/headers";
+
+import type { UsageQuotaInput } from "@/core/services";
+import { anonymousQuotaService } from "@/services/rate-limit";
+
+const ANONYMOUS_QUOTA = {
+  maxGenerations: 2,
+  namespace: "anonymous",
+  windowSeconds: 24 * 60 * 60,
+} as const;
+
+let requestFingerprint: string | null = null;
+
+export function setFingerprintForRequest(fingerprint: string): void {
+  requestFingerprint = fingerprint;
+}
+
+export async function getClientIdentifier(): Promise<string> {
+  try {
+    if (requestFingerprint) {
+      const fingerprint = requestFingerprint;
+      requestFingerprint = null;
+      return `fp:${fingerprint}`;
+    }
+
+    const headerList = await headers();
+    const fingerprint = headerList.get("x-device-fingerprint");
+    if (fingerprint) {
+      return `fp:${fingerprint}`;
+    }
+
+    const ip =
+      headerList.get("x-forwarded-for") ??
+      headerList.get("x-real-ip") ??
+      headerList.get("cf-connecting-ip") ??
+      "unknown";
+    return `ip:${ip.replace(/(\d+\.\d+\.\d+)\.\d+/, "$1.0")}`;
+  } catch {
+    return `unknown:${Date.now()}`;
+  }
+}
+
+async function quotaInput(): Promise<UsageQuotaInput> {
+  return {
+    identifier: await getClientIdentifier(),
+    limit: ANONYMOUS_QUOTA.maxGenerations,
+    namespace: ANONYMOUS_QUOTA.namespace,
+    windowSeconds: ANONYMOUS_QUOTA.windowSeconds,
+  };
+}
+
+export async function checkAnonymousQuota(): Promise<{
+  allowed: boolean;
+  remaining: number;
+  resetAt?: Date;
+}> {
+  try {
+    const result = await anonymousQuotaService.check(await quotaInput());
+    return {
+      allowed: result.allowed,
+      remaining: result.remaining,
+      ...(result.reset === null ? {} : { resetAt: new Date(result.reset) }),
+    };
+  } catch (error) {
+    console.error("Error checking quota:", error);
+    return { allowed: true, remaining: ANONYMOUS_QUOTA.maxGenerations };
+  }
+}
+
+export async function incrementAnonymousUsage(): Promise<number> {
+  try {
+    return await anonymousQuotaService.increment(await quotaInput());
+  } catch (error) {
+    console.error("Error incrementing usage:", error);
+    return 0;
+  }
+}
+
+export async function getRemainingQuota(): Promise<number> {
+  try {
+    return await anonymousQuotaService.remaining(await quotaInput());
+  } catch {
+    return ANONYMOUS_QUOTA.maxGenerations;
+  }
+}