create-nextdevtpl 2.6.0

package/template/src/features/support/schemas/ticket.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+/**
+ * 工单类别选项
+ */
+export const ticketCategories = [
+  { value: "billing", label: "账单问题" },
+  { value: "technical", label: "技术支持" },
+  { value: "bug", label: "Bug 报告" },
+  { value: "feature", label: "功能建议" },
+  { value: "other", label: "其他" },
+] as const;
+
+/**
+ * 工单优先级选项
+ */
+export const ticketPriorities = [
+  { value: "low", label: "低", color: "bg-success" },
+  { value: "medium", label: "中", color: "bg-warning" },
+  { value: "high", label: "高", color: "bg-destructive" },
+] as const;
+
+/**
+ * 工单状态选项
+ */
+export const ticketStatuses = [
+  { value: "open", label: "待处理", color: "bg-primary" },
+  { value: "in_progress", label: "处理中", color: "bg-warning" },
+  { value: "resolved", label: "已解决", color: "bg-success" },
+  { value: "closed", label: "已关闭", color: "bg-muted-foreground" },
+] as const;
+
+/**
+ * 创建工单 Schema
+ */
+export const createTicketSchema = z.object({
+  /** 工单主题 */
+  subject: z
+    .string()
+    .min(5, "主题至少需要5个字符")
+    .max(200, "主题最多200个字符"),
+  /** 工单类别 */
+  category: z.enum(["billing", "technical", "bug", "feature", "other"]),
+  /** 优先级 */
+  priority: z.enum(["low", "medium", "high"]).default("medium"),
+  /** 初始消息内容 */
+  message: z
+    .string()
+    .min(10, "消息内容至少需要10个字符")
+    .max(5000, "消息内容最多5000个字符"),
+});
+
+/**
+ * 添加工单消息 Schema
+ */
+export const addTicketMessageSchema = z.object({
+  /** 工单 ID */
+  ticketId: z.string().min(1, "工单ID不能为空"),
+  /** 消息内容 */
+  content: z
+    .string()
+    .min(1, "消息内容不能为空")
+    .max(5000, "消息内容最多5000个字符"),
+});
+
+/**
+ * 更新工单状态 Schema (管理员)
+ */
+export const updateTicketStatusSchema = z.object({
+  /** 工单 ID */
+  ticketId: z.string().min(1, "工单ID不能为空"),
+  /** 新状态 */
+  status: z.enum(["open", "in_progress", "resolved", "closed"]),
+});
+
+/**
+ * 类型导出
+ */
+export type CreateTicketInput = z.infer<typeof createTicketSchema>;
+export type AddTicketMessageInput = z.infer<typeof addTicketMessageSchema>;
+export type UpdateTicketStatusInput = z.infer<typeof updateTicketStatusSchema>;

package/template/src/hooks/index.ts

@@ -0,0 +1,2 @@
+// Custom React hooks
+export {};

package/template/src/i18n/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 国际化模块统一导出
+ */
+
+export {
+  getPathname,
+  Link,
+  redirect,
+  routing,
+  usePathname,
+  useRouter,
+} from "./routing";

package/template/src/i18n/request.ts

@@ -0,0 +1,24 @@
+import { getRequestConfig } from "next-intl/server";
+
+import { routing } from "./routing";
+
+/**
+ * 请求级别的国际化配置
+ *
+ * 根据请求的语言加载对应的翻译消息
+ */
+export default getRequestConfig(async ({ requestLocale }) => {
+  // 获取请求的语言
+  let locale = await requestLocale;
+
+  // 验证语言是否有效，无效则使用默认语言
+  if (!locale || !routing.locales.includes(locale as "en" | "zh")) {
+    locale = routing.defaultLocale;
+  }
+
+  return {
+    locale,
+    // 动态加载对应语言的翻译文件
+    messages: (await import(`../../messages/${locale}.json`)).default,
+  };
+});

package/template/src/i18n/routing.ts

@@ -0,0 +1,23 @@
+import { createNavigation } from "next-intl/navigation";
+import { defineRouting } from "next-intl/routing";
+
+/**
+ * 国际化路由配置
+ *
+ * 定义支持的语言和默认语言
+ */
+export const routing = defineRouting({
+  // 支持的语言列表
+  locales: ["en", "zh"],
+  // 默认语言
+  defaultLocale: "en",
+});
+
+/**
+ * 导出国际化导航组件和钩子
+ *
+ * 使用这些替代 next/link 和 next/navigation
+ * 以确保正确处理语言前缀
+ */
+export const { Link, redirect, usePathname, useRouter, getPathname } =
+  createNavigation(routing);

package/template/src/instrumentation.ts

@@ -0,0 +1,19 @@
+/**
+ * Next.js Instrumentation Hook
+ *
+ * 用于在服务器启动时执行初始化逻辑
+ * https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation
+ */
+
+export async function register() {
+  // 服务端初始化
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    // Sentry 服务端初始化
+    await import("../sentry.server.config");
+  }
+
+  // Edge Runtime 初始化
+  if (process.env.NEXT_RUNTIME === "edge") {
+    await import("../sentry.edge.config");
+  }
+}

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

@@ -0,0 +1,16 @@
+import type { AICompletionInput, AIMessage } from "@/core/services";
+import { aiService, getAIModel, getAIProvider } from "@/services/ai";
+
+export type { AIMessage };
+export { getAIModel, getAIProvider };
+
+export async function chatCompletion(
+  messages: readonly AIMessage[],
+  options?: Omit<AICompletionInput, "messages">
+): Promise<string> {
+  const result = await aiService.complete({
+    messages,
+    ...options,
+  });
+  return result.content;
+}

package/template/src/lib/api-logger.ts

@@ -0,0 +1,24 @@
+import { logApiResponse, logError } from "@/lib/logger";
+
+// biome-ignore lint/suspicious/noExplicitAny: wrapper must accept both Request and NextRequest
+type ApiHandler = (request: any, context?: any) => Promise<Response>;
+
+export function withApiLogging<T extends ApiHandler>(handler: T): T {
+  const wrapped = async (request: Request, context?: unknown) => {
+    const startTime = Date.now();
+    try {
+      const response = await handler(request, context);
+      logApiResponse(request, response, Date.now() - startTime);
+      return response;
+    } catch (error) {
+      logError(error, {
+        source: "api",
+        method: request.method,
+        path: new URL(request.url).pathname,
+        duration: Date.now() - startTime,
+      });
+      throw error;
+    }
+  };
+  return wrapped as T;
+}

package/template/src/lib/auth/admin.ts

@@ -0,0 +1,54 @@
+import { redirect } from "next/navigation";
+
+import { getServerSession } from "@/lib/auth/server";
+
+/**
+ * Admin 权限检查
+ *
+ * 用于保护管理员路由
+ * 如果用户未登录或不是管理员，重定向到首页
+ *
+ * @returns 当前用户会话 (如果是管理员)
+ * @throws Redirect to "/" if not admin
+ *
+ * @example
+ * ```ts
+ * // 在 Admin 布局或页面中使用
+ * export default async function AdminLayout({ children }) {
+ *   await checkAdmin();
+ *   return <>{children}</>;
+ * }
+ * ```
+ */
+export async function checkAdmin() {
+  const session = await getServerSession();
+
+  // 检查用户是否登录
+  if (!session || !session.user) {
+    redirect("/sign-in");
+  }
+
+  // 检查用户是否是管理员
+  if (session.user.role !== "admin") {
+    redirect("/");
+  }
+
+  return session;
+}
+
+/**
+ * 检查当前用户是否是管理员 (不重定向)
+ *
+ * 用于需要检查管理员权限但不想重定向的场景
+ *
+ * @returns 是否是管理员
+ */
+export async function isAdmin(): Promise<boolean> {
+  const session = await getServerSession();
+
+  if (!session || !session.user) {
+    return false;
+  }
+
+  return session.user.role === "admin";
+}

package/template/src/lib/auth/api.ts

@@ -0,0 +1,17 @@
+import { toNextJsHandler } from "better-auth/next-js";
+
+import { auth } from "./index";
+
+/**
+ * Better Auth API 处理器
+ *
+ * 用于 API 路由中处理认证请求
+ *
+ * @example
+ * ```ts
+ * // src/app/api/auth/[...all]/route.ts
+ * import { GET, POST } from "@/lib/auth/api";
+ * export { GET, POST };
+ * ```
+ */
+export const { GET, POST } = toNextJsHandler(auth);

package/template/src/lib/auth/client.ts

@@ -0,0 +1,227 @@
+"use client";
+
+import { createAuthClient } from "better-auth/react";
+
+/**
+ * Better Auth 客户端配置
+ *
+ * 此客户端用于在 React 组件中进行认证操作:
+ * - 社交登录 (GitHub, Google)
+ * - 邮箱密码登录
+ * - 会话管理
+ * - 登出
+ */
+export const authClient = createAuthClient({
+  /**
+   * 认证 API 基础 URL
+   * 默认指向 /api/auth，与 API 路由匹配
+   */
+  baseURL: process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000",
+});
+
+/**
+ * 导出常用的认证方法，便于在组件中使用
+ */
+export const {
+  // 会话相关
+  useSession, // Hook: 获取当前会话状态
+  getSession, // 函数: 获取会话 (非 Hook)
+
+  // 登录方法
+  signIn, // 登录 (邮箱密码或社交)
+
+  // 登出方法
+  signOut, // 登出当前会话
+
+  // 注册方法
+  signUp, // 注册新用户 (邮箱密码)
+} = authClient;
+
+function getResponseErrorMessage(value: unknown): string | undefined {
+  if (typeof value !== "object" || value === null || !("message" in value)) {
+    return undefined;
+  }
+  return typeof value.message === "string" ? value.message : undefined;
+}
+
+/**
+ * 发送密码重置邮件
+ * 通过调用 Better Auth API 端点发送重置链接
+ * @param email - 用户邮箱
+ * @param redirectTo - 重置链接的跳转地址
+ */
+export async function forgetPassword(
+  email: string,
+  redirectTo = "/reset-password"
+) {
+  const baseURL = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+
+  const response = await fetch(`${baseURL}/api/auth/forget-password`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      email,
+      redirectTo,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to send reset email");
+  }
+
+  return response.json();
+}
+
+/**
+ * 重置密码
+ * @param newPassword - 新密码
+ * @param token - 重置令牌 (从 URL 获取)
+ */
+export async function resetPassword(newPassword: string, token: string) {
+  const baseURL = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+
+  const response = await fetch(`${baseURL}/api/auth/reset-password`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      newPassword,
+      token,
+    }),
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to reset password");
+  }
+
+  return response.json();
+}
+
+/**
+ * 社交登录辅助函数
+ */
+
+/**
+ * 使用 GitHub 登录
+ * @param callbackURL - 登录成功后的跳转地址
+ */
+export async function signInWithGitHub(callbackURL = "/dashboard") {
+  return signIn.social({
+    provider: "github",
+    callbackURL,
+  });
+}
+
+/**
+ * 使用 Google 登录
+ * @param callbackURL - 登录成功后的跳转地址
+ */
+export async function signInWithGoogle(callbackURL = "/dashboard") {
+  return signIn.social({
+    provider: "google",
+    callbackURL,
+  });
+}
+
+/**
+ * 邮箱密码登录
+ * @param email - 用户邮箱
+ * @param password - 用户密码
+ * @param callbackURL - 登录成功后的跳转地址
+ */
+export async function signInWithEmail(
+  email: string,
+  password: string,
+  callbackURL = "/dashboard"
+) {
+  return signIn.email({
+    email,
+    password,
+    callbackURL,
+  });
+}
+
+/**
+ * 邮箱密码注册
+ * @param email - 用户邮箱
+ * @param password - 用户密码
+ * @param name - 用户名称
+ */
+export async function signUpWithEmail(
+  email: string,
+  password: string,
+  name: string
+) {
+  return signUp.email({
+    email,
+    password,
+    name,
+  });
+}
+
+/**
+ * 修改密码（已登录用户）
+ * @param currentPassword - 当前密码
+ * @param newPassword - 新密码
+ */
+export async function changePassword(
+  currentPassword: string,
+  newPassword: string
+) {
+  const baseURL = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+
+  const response = await fetch(`${baseURL}/api/auth/change-password`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    credentials: "include",
+    body: JSON.stringify({
+      currentPassword,
+      newPassword,
+    }),
+  });
+
+  const data: unknown = await response.json();
+
+  if (!response.ok) {
+    throw new Error(
+      getResponseErrorMessage(data) ?? "Failed to change password"
+    );
+  }
+
+  return data;
+}
+
+/**
+ * 重新发送邮箱验证邮件
+ * @param email - 用户邮箱
+ */
+export async function resendVerificationEmail(email: string) {
+  const baseURL = process.env.NEXT_PUBLIC_APP_URL || "http://localhost:3000";
+
+  const response = await fetch(`${baseURL}/api/auth/send-verification-email`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({ email }),
+  });
+
+  if (!response.ok) {
+    throw new Error("Failed to send verification email");
+  }
+
+  return response.json();
+}
+
+/**
+ * 刷新会话
+ * 用于在会话数据更新后强制刷新客户端状态
+ */
+export async function reloadSession() {
+  return getSession();
+}

package/template/src/lib/auth/edge.ts

@@ -0,0 +1,84 @@
+/**
+ * Edge Runtime 认证函数
+ *
+ * 用于 Middleware 和 Edge Functions 中验证用户会话
+ * Edge Runtime 环境下无法使用完整的数据库连接，
+ * 因此使用 Cookie 验证方式
+ */
+
+/**
+ * 从请求中获取会话 Token
+ *
+ * @param request - Next.js Request 对象
+ * @returns 会话 Token 或 undefined
+ */
+export function getSessionToken(request: Request): string | undefined {
+  const cookieHeader = request.headers.get("cookie");
+  if (!cookieHeader) return undefined;
+
+  // Better Auth 使用的 Cookie 名称
+  const cookieNames = [
+    "better-auth.session_token",
+    "__Secure-better-auth.session_token", // HTTPS 环境
+  ];
+
+  for (const name of cookieNames) {
+    const match = cookieHeader.match(new RegExp(`${name}=([^;]+)`));
+    if (match) {
+      return match[1];
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * 检查请求是否包含有效的会话 Token
+ *
+ * 注意: 这只是检查 Token 是否存在，不验证 Token 的有效性
+ * 完整的验证需要在服务器端进行
+ *
+ * @param request - Next.js Request 对象
+ * @returns boolean - 是否存在会话 Token
+ */
+export function hasSessionToken(request: Request): boolean {
+  return !!getSessionToken(request);
+}
+
+/**
+ * 受保护路由的路径模式
+ * 用于 Middleware 中判断是否需要认证
+ */
+export const protectedRoutes = [
+  "/dashboard",
+  "/dashboard/:path*",
+  "/settings",
+  "/settings/:path*",
+  "/admin",
+  "/admin/:path*",
+];
+
+/**
+ * 认证页面的路径模式
+ * 已登录用户访问这些页面时应重定向到 Dashboard
+ */
+export const authRoutes = [
+  "/sign-in",
+  "/sign-up",
+  "/forgot-password",
+  "/reset-password",
+];
+
+/**
+ * 公开路由的路径模式
+ * 这些路由不需要认证
+ */
+export const publicRoutes = [
+  "/",
+  "/about",
+  "/pricing",
+  "/blog",
+  "/blog/:path*",
+  "/docs",
+  "/docs/:path*",
+];

package/template/src/lib/auth/errors.ts

@@ -0,0 +1,99 @@
+/**
+ * 认证错误类型
+ */
+export enum AuthErrorCode {
+  /** 未认证 - 用户未登录 */
+  UNAUTHENTICATED = "UNAUTHENTICATED",
+  /** 未授权 - 用户无权限访问 */
+  UNAUTHORIZED = "UNAUTHORIZED",
+  /** 无效凭证 - 邮箱或密码错误 */
+  INVALID_CREDENTIALS = "INVALID_CREDENTIALS",
+  /** 用户已存在 - 邮箱已被注册 */
+  USER_EXISTS = "USER_EXISTS",
+  /** 用户不存在 */
+  USER_NOT_FOUND = "USER_NOT_FOUND",
+  /** 会话过期 */
+  SESSION_EXPIRED = "SESSION_EXPIRED",
+  /** OAuth 错误 */
+  OAUTH_ERROR = "OAUTH_ERROR",
+  /** 邮箱未验证 */
+  EMAIL_NOT_VERIFIED = "EMAIL_NOT_VERIFIED",
+  /** 未知错误 */
+  UNKNOWN = "UNKNOWN",
+}
+
+/**
+ * 认证错误类
+ */
+export class AuthError extends Error {
+  code: AuthErrorCode;
+
+  constructor(code: AuthErrorCode, message?: string) {
+    super(message || getDefaultMessage(code));
+    this.name = "AuthError";
+    this.code = code;
+  }
+}
+
+/**
+ * 获取错误码的默认消息
+ */
+function getDefaultMessage(code: AuthErrorCode): string {
+  const messages: Record<AuthErrorCode, string> = {
+    [AuthErrorCode.UNAUTHENTICATED]: "请先登录后再执行此操作",
+    [AuthErrorCode.UNAUTHORIZED]: "您没有权限执行此操作",
+    [AuthErrorCode.INVALID_CREDENTIALS]: "邮箱或密码错误",
+    [AuthErrorCode.USER_EXISTS]: "该邮箱已被注册",
+    [AuthErrorCode.USER_NOT_FOUND]: "用户不存在",
+    [AuthErrorCode.SESSION_EXPIRED]: "会话已过期，请重新登录",
+    [AuthErrorCode.OAUTH_ERROR]: "第三方登录失败，请重试",
+    [AuthErrorCode.EMAIL_NOT_VERIFIED]: "请先验证您的邮箱",
+    [AuthErrorCode.UNKNOWN]: "发生未知错误，请稍后重试",
+  };
+
+  return messages[code];
+}
+
+/**
+ * 判断是否为认证错误
+ */
+export function isAuthError(error: unknown): error is AuthError {
+  return error instanceof AuthError;
+}
+
+/**
+ * 从未知错误创建 AuthError
+ */
+export function toAuthError(error: unknown): AuthError {
+  if (isAuthError(error)) {
+    return error;
+  }
+
+  if (error instanceof Error) {
+    // 尝试从错误消息推断错误类型
+    const message = error.message.toLowerCase();
+
+    if (message.includes("unauthorized") || message.includes("未授权")) {
+      return new AuthError(AuthErrorCode.UNAUTHORIZED);
+    }
+    if (message.includes("unauthenticated") || message.includes("未登录")) {
+      return new AuthError(AuthErrorCode.UNAUTHENTICATED);
+    }
+    if (message.includes("invalid") || message.includes("credentials")) {
+      return new AuthError(AuthErrorCode.INVALID_CREDENTIALS);
+    }
+    if (message.includes("exists") || message.includes("已存在")) {
+      return new AuthError(AuthErrorCode.USER_EXISTS);
+    }
+    if (message.includes("not found") || message.includes("不存在")) {
+      return new AuthError(AuthErrorCode.USER_NOT_FOUND);
+    }
+    if (message.includes("expired") || message.includes("过期")) {
+      return new AuthError(AuthErrorCode.SESSION_EXPIRED);
+    }
+
+    return new AuthError(AuthErrorCode.UNKNOWN, error.message);
+  }
+
+  return new AuthError(AuthErrorCode.UNKNOWN);
+}