create-pardx-scaffold 0.1.1 → 0.1.3

package/template/apps/web/lib/api/contracts/client.ts

@@ -41,6 +41,54 @@ import {
 
 const API_BASE_URL = API_CONFIG.baseUrl;
 
+// ============================================================================
+// 错误消息去重机制（模块级别缓存）
+// 在短时间内（2秒）相同的错误消息只显示一次
+// ============================================================================
+const errorMessageCache = new Map<string, number>();
+const ERROR_DEDUP_INTERVAL = 2000; // 2秒
+const MAX_CACHE_SIZE = 50; // 最大缓存数量
+
+/**
+ * 清理过期的错误缓存
+ */
+const cleanupErrorCache = () => {
+  const now = Date.now();
+  for (const [key, timestamp] of errorMessageCache.entries()) {
+    if (now - timestamp >= ERROR_DEDUP_INTERVAL) {
+      errorMessageCache.delete(key);
+    }
+  }
+  // 如果清理后仍超过限制，删除最旧的项
+  if (errorMessageCache.size > MAX_CACHE_SIZE) {
+    const oldestKey = errorMessageCache.keys().next().value;
+    if (oldestKey) errorMessageCache.delete(oldestKey);
+  }
+};
+
+/**
+ * 检查错误消息是否应该被去重（跳过显示）
+ */
+const shouldDeduplicateError = (errorKey: string): boolean => {
+  const now = Date.now();
+  const lastShown = errorMessageCache.get(errorKey);
+
+  // 如果在去重时间窗口内已经显示过相同的错误，则跳过
+  if (lastShown && now - lastShown < ERROR_DEDUP_INTERVAL) {
+    return true;
+  }
+
+  // 记录当前错误消息的显示时间
+  errorMessageCache.set(errorKey, now);
+
+  // 清理过期缓存
+  if (errorMessageCache.size > MAX_CACHE_SIZE) {
+    cleanupErrorCache();
+  }
+
+  return false;
+};
+
 /**
  * Base fetch function with standard headers (no auth check)
  * Used for public endpoints like login, register
@@ -136,13 +184,7 @@ const baseFetch = async (args: ApiFetcherArgs, requireAuth: boolean = true) => {
     throw new VersionMismatchError(minBuild);
   }
 
-  // 错误消息去重机制：记录最近显示的错误消息和时间戳
-  // 在短时间内（2秒）相同的错误消息只显示一次
-  const errorMessageCache = new Map<string, number>();
-  const ERROR_DEDUP_INTERVAL = 2000; // 2秒
-  const MAX_CACHE_SIZE = 50; // 最大缓存数量
-
-  // Global error handling
+  // Global error handling with deduplication
   const handleError = (errorMsg: string, statusCode: number) => {
     if (typeof window === 'undefined') return;
 
@@ -150,42 +192,21 @@ const baseFetch = async (args: ApiFetcherArgs, requireAuth: boolean = true) => {
 
     // 如果已经在登录页面，不需要全局错误处理，由登录组件自己处理
     if (pathname === '/login' || pathname.endsWith('/login')) {
-      // 登录页面的错误（如密码错误、401 等）由登录组件自己处理，不显示 toast
       return;
     }
 
     // 创建错误消息的唯一标识（包含消息内容和状态码）
     const errorKey = `${statusCode}:${errorMsg}`;
-    const now = Date.now();
-    const lastShown = errorMessageCache.get(errorKey);
 
-    // 如果在去重时间窗口内已经显示过相同的错误，则跳过
-    if (lastShown && now - lastShown < ERROR_DEDUP_INTERVAL) {
+    // 使用模块级别的去重机制
+    if (shouldDeduplicateError(errorKey)) {
       return;
     }
 
-    // 记录当前错误消息的显示时间
-    errorMessageCache.set(errorKey, now);
-
-    // 清理过期缓存：达到最大数量时清理所有过期项
-    if (errorMessageCache.size > MAX_CACHE_SIZE) {
-      for (const [key, timestamp] of errorMessageCache.entries()) {
-        if (now - timestamp >= ERROR_DEDUP_INTERVAL) {
-          errorMessageCache.delete(key);
-        }
-      }
-      // 如果清理后仍超过限制，删除最旧的项
-      if (errorMessageCache.size > MAX_CACHE_SIZE) {
-        const oldestKey = errorMessageCache.keys().next().value;
-        if (oldestKey) errorMessageCache.delete(oldestKey);
-      }
-    }
-
     // Handle 401 Unauthorized - clear storage and redirect to login
     if (statusCode === 401) {
       clearToken();
       toast.error(errorMsg || '登录已过期，请重新登录');
-      // 重定向到登录页（公开页面在上面已经提前返回，不会执行到这里）
       window.location.href = '/login';
     } else {
       // Show error toast for other error codes

package/template/apps/web/lib/api/contracts/hooks/index.ts

@@ -15,9 +15,6 @@ export {
   settingKeys,
   useSaveAccount,
   useUpdateAvatar,
-  useGetUsage,
-  useGetBranding,
-  useSaveBranding,
   useSendVerifyEmail,
   useSetPassword,
   useBindEmail,

package/template/apps/web/lib/api/contracts/hooks/notification.ts

@@ -4,62 +4,20 @@
  * Notification API Hooks
  * 基于 ts-rest 契约的通知 API Hooks
  *
- * 性能优化：
- * - 懒加载模式：支持 enabled 选项，仅在需要时加载数据
- * - 减少初始 API 调用和 SSE 数据压力
- *
- * @example
- * ```tsx
- * import {
- *   useNotifications,
- *   useUnreadNotificationCount,
- *   useMarkNotificationRead,
- *   useMarkAllNotificationsRead,
- * } from '@/lib/api/contracts/hooks/notification';
- *
- * function NotificationPanel() {
- *   const [open, setOpen] = useState(false);
- *   // 懒加载：仅当面板打开时加载通知列表
- *   const { data, isLoading } = useNotifications({ limit: 20 }, { enabled: open });
- *   // 未读数量始终加载，用于显示徽章
- *   const { data: unreadCount } = useUnreadNotificationCount();
- *   const markReadMutation = useMarkNotificationRead();
- *   const markAllReadMutation = useMarkAllNotificationsRead();
- *
- *   return (
- *     <div>
- *       <p>未读: {unreadCount?.total}</p>
- *       {data?.list.map(notification => (
- *         <div key={notification.id} onClick={() => {
- *           markReadMutation.mutate({ notificationIds: [notification.id] });
- *         }}>
- *           {notification.content.type}
- *         </div>
- *       ))}
- *       <button onClick={() => markAllReadMutation.mutate({})}>
- *         全部标为已读
- *       </button>
- *     </div>
- *   );
- * }
- * ```
+ * 注意：此文件是脚手架占位符。
+ * 实际项目中需要在 @repo/contracts 中定义 notificationContract，
+ * 并在 client.ts 中导出 notificationApi 和 notificationClient。
  */
 
-import { useQuery, useQueryClient } from '@tanstack/react-query';
-import { notificationApi, notificationClient } from '../client';
-import type {
-  MessageNotificationType,
-  GetNotificationListRequest,
-} from '@repo/contracts';
-
 // ============================================================================
 // Query Keys
 // ============================================================================
 
 export const notificationKeys = {
   all: ['notifications'] as const,
-  list: (params?: Partial<GetNotificationListRequest>) =>
+  list: (params?: Record<string, unknown>) =>
     [...notificationKeys.all, 'list', params] as const,
+  unreadCount: () => [...notificationKeys.all, 'unreadCount'] as const,
 };
 
 // ============================================================================
@@ -67,7 +25,7 @@ export const notificationKeys = {
 // ============================================================================
 
 export interface NotificationsParams {
-  type?: MessageNotificationType;
+  type?: string;
   isRead?: boolean;
   limit?: number;
   page?: number;
@@ -79,102 +37,62 @@ export interface NotificationsOptions {
 }
 
 // ============================================================================
-// Query Hooks
+// Placeholder Hooks
+// 这些 hooks 是占位符，需要在实际项目中实现
 // ============================================================================
 
 /**
- * 获取通知列表
- *
- * 使用 React Query 原生 useQuery 实现 enabled 选项，
- * 支持懒加载模式，仅在需要时加载数据
- *
- * @param params - 查询参数（筛选条件和分页）
- * @param options - 可选配置项，支持 enabled 懒加载
- *
- * @example
- * ```tsx
- * // 懒加载：仅当面板打开时才加载列表
- * const { data, isLoading, refetch } = useNotifications(
- *   { limit: 20 },
- *   { enabled: isPanelOpen }
- * );
- * ```
+ * 获取通知列表 (占位符)
+ * TODO: 实现 notificationContract 后启用
  */
 export function useNotifications(
-  params?: NotificationsParams,
-  options?: NotificationsOptions,
+  _params?: NotificationsParams,
+  _options?: NotificationsOptions,
 ) {
-  const queryParams = {
-    type: params?.type,
-    isRead: params?.isRead,
-    limit: params?.limit || 20,
-    page: params?.page || 1,
+  // 占位符实现
+  return {
+    data: undefined,
+    isLoading: false,
+    error: null,
+    refetch: () => Promise.resolve(),
   };
-
-  const isEnabled = options?.enabled ?? true;
-
-  // 使用 React Query 原生 useQuery，正确支持 enabled 选项
-  return useQuery({
-    queryKey: notificationKeys.list(queryParams),
-    queryFn: async () => {
-      const response = await notificationClient.getList({
-        query: queryParams,
-      });
-      return response;
-    },
-    staleTime: 30 * 1000, // 30 seconds
-    enabled: isEnabled,
-  });
 }
 
-// ============================================================================
-// Mutation Hooks
-// ============================================================================
-
 /**
- * 标记通知已读
+ * 标记通知已读 (占位符)
+ * TODO: 实现 notificationContract 后启用
  */
 export function useMarkNotificationRead() {
-  const queryClient = useQueryClient();
-
-  return notificationApi.markRead.useMutation({
-    onSuccess: () => {
-      // 刷新通知列表和未读数量
-      queryClient.invalidateQueries({
-        queryKey: notificationKeys.all,
-      });
-    },
-  });
+  return {
+    mutate: (_params: { notificationIds: string[] }) => {},
+    mutateAsync: (_params: { notificationIds: string[] }) => Promise.resolve(),
+    isLoading: false,
+    isPending: false,
+  };
 }
 
 /**
- * 标记全部通知已读
+ * 标记全部通知已读 (占位符)
+ * TODO: 实现 notificationContract 后启用
  */
 export function useMarkAllNotificationsRead() {
-  const queryClient = useQueryClient();
-
-  return notificationApi.markAllRead.useMutation({
-    onSuccess: () => {
-      // 刷新通知列表和未读数量
-      queryClient.invalidateQueries({
-        queryKey: notificationKeys.all,
-      });
-    },
-  });
+  return {
+    mutate: () => {},
+    mutateAsync: () => Promise.resolve(),
+    isLoading: false,
+    isPending: false,
+  };
 }
 
 /**
- * 删除通知
+ * 删除通知 (占位符)
+ * TODO: 实现 notificationContract 后启用
  */
 export function useDeleteNotification() {
-  const queryClient = useQueryClient();
-
-  return notificationApi.delete.useMutation({
-    onSuccess: () => {
-      // 刷新通知列表和未读数量
-      queryClient.invalidateQueries({
-        queryKey: notificationKeys.all,
-      });
-    },
-  });
+  return {
+    mutate: (_params: { notificationId: string }) => {},
+    mutateAsync: (_params: { notificationId: string }) => Promise.resolve(),
+    isLoading: false,
+    isPending: false,
+  };
 }

package/template/apps/web/lib/api.ts

@@ -44,6 +44,9 @@ export interface TokenData {
 // Token Management
 // ============================================================================
 
+// Token 刷新队列：防止并发请求时多次刷新 token
+let refreshPromise: Promise<LoginData> | null = null;
+
 // 获取存储的 token（使用新的存储模块）
 export function getToken(): string | null {
   return getAccessToken();
@@ -121,8 +124,10 @@ export async function login(credentials: LoginRequest): Promise<LoginData> {
 /**
  * 刷新 Token API (ts-rest)
  * 使用 signClient.refreshToken
+ *
+ * 注意：此函数内部使用，外部应使用 ensureValidToken
  */
-export async function refreshToken(): Promise<LoginData> {
+async function doRefreshToken(): Promise<LoginData> {
   const refresh = getRefreshToken();
   if (!refresh) {
     throw new Error('没有可用的 refresh token');
@@ -149,6 +154,24 @@ export async function refreshToken(): Promise<LoginData> {
   return data;
 }
 
+/**
+ * 刷新 Token（带队列机制）
+ * 防止并发请求时多次刷新 token
+ */
+export async function refreshToken(): Promise<LoginData> {
+  // 如果已有刷新请求在进行中，等待它完成
+  if (refreshPromise) {
+    return refreshPromise;
+  }
+
+  // 创建刷新 Promise 并共享
+  refreshPromise = doRefreshToken().finally(() => {
+    refreshPromise = null;
+  });
+
+  return refreshPromise;
+}
+
 /**
  * 确保 token 有效（如果过期则自动刷新）
  */

package/template/apps/web/lib/dynamic-import.tsx

@@ -0,0 +1,121 @@
+'use client';
+
+/**
+ * 动态导入工具
+ *
+ * 提供代码分割和懒加载的工具函数
+ * 用于优化首屏加载性能
+ */
+import dynamic from 'next/dynamic';
+import type { ComponentType, ReactNode } from 'react';
+
+/**
+ * 加载状态组件
+ */
+function DefaultLoadingComponent() {
+  return (
+    <div className="flex items-center justify-center p-4">
+      <div className="h-8 w-8 animate-spin rounded-full border-4 border-gray-200 border-t-blue-600" />
+    </div>
+  );
+}
+
+/**
+ * 创建懒加载组件
+ *
+ * @param importFn - 动态导入函数
+ * @param options - 配置选项
+ * @returns 懒加载的组件
+ *
+ * @example
+ * ```tsx
+ * // 基本用法
+ * const HeavyChart = createLazyComponent(() => import('@/components/chart'));
+ *
+ * // 带自定义加载状态
+ * const Editor = createLazyComponent(
+ *   () => import('@/components/editor'),
+ *   { loading: <EditorSkeleton /> }
+ * );
+ *
+ * // 禁用 SSR（用于仅客户端组件）
+ * const ClientOnlyMap = createLazyComponent(
+ *   () => import('@/components/map'),
+ *   { ssr: false }
+ * );
+ * ```
+ */
+export function createLazyComponent<P extends object>(
+  importFn: () => Promise<{ default: ComponentType<P> }>,
+  options: {
+    loading?: ReactNode;
+    ssr?: boolean;
+  } = {},
+) {
+  const { loading, ssr = true } = options;
+
+  return dynamic(importFn, {
+    loading: () => (loading ? <>{loading}</> : <DefaultLoadingComponent />),
+    ssr,
+  });
+}
+
+/**
+ * 预加载组件
+ *
+ * 在用户可能需要组件之前预先加载
+ * 例如：鼠标悬停在链接上时预加载目标页面的组件
+ *
+ * @param importFn - 动态导入函数
+ *
+ * @example
+ * ```tsx
+ * const loadEditor = () => import('@/components/editor');
+ *
+ * // 在鼠标悬停时预加载
+ * <button onMouseEnter={() => preloadComponent(loadEditor)}>
+ *   打开编辑器
+ * </button>
+ * ```
+ */
+export function preloadComponent<T>(
+  importFn: () => Promise<T>,
+): Promise<T> | void {
+  if (typeof window !== 'undefined') {
+    return importFn();
+  }
+}
+
+/**
+ * 常用的懒加载组件示例
+ *
+ * 这些组件通常较大，适合懒加载：
+ * - 富文本编辑器
+ * - 图表库
+ * - 地图组件
+ * - 文件预览器
+ * - 代码编辑器
+ */
+
+// 示例：懒加载图表组件（如果存在）
+// export const LazyChart = createLazyComponent(
+//   () => import('@/components/chart'),
+//   { ssr: false }
+// );
+
+// 示例：懒加载编辑器组件（如果存在）
+// export const LazyEditor = createLazyComponent(
+//   () => import('@/components/editor'),
+//   { ssr: false }
+// );
+
+// 示例：懒加载文件预览器（如果存在）
+// export const LazyFilePreview = createLazyComponent(
+//   () => import('@/components/file-preview'),
+//   { ssr: false }
+// );
+
+export default {
+  createLazyComponent,
+  preloadComponent,
+};

package/template/apps/web/lib/logger.ts

@@ -0,0 +1,113 @@
+/**
+ * Frontend Logger
+ *
+ * 浏览器兼容的日志库，替代 console.log
+ * 支持日志级别控制和生产环境静默
+ */
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+interface LoggerConfig {
+  level: LogLevel;
+  prefix?: string;
+  enableInProduction?: boolean;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+class Logger {
+  private level: LogLevel;
+  private prefix: string;
+  private enableInProduction: boolean;
+
+  constructor(config: Partial<LoggerConfig> = {}) {
+    this.level = config.level ?? this.getDefaultLevel();
+    this.prefix = config.prefix ?? '[App]';
+    this.enableInProduction = config.enableInProduction ?? false;
+  }
+
+  private getDefaultLevel(): LogLevel {
+    if (typeof window === 'undefined') {
+      return 'info';
+    }
+    return process.env.NODE_ENV === 'production' ? 'warn' : 'debug';
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    // 在生产环境中，除非明确启用，否则只记录 warn 和 error
+    if (
+      process.env.NODE_ENV === 'production' &&
+      !this.enableInProduction &&
+      LOG_LEVELS[level] < LOG_LEVELS.warn
+    ) {
+      return false;
+    }
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+
+  private formatMessage(level: LogLevel, message: string): string {
+    const timestamp = new Date().toISOString();
+    return `${timestamp} ${this.prefix} [${level.toUpperCase()}] ${message}`;
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('debug')) {
+      console.debug(this.formatMessage('debug', message), ...args);
+    }
+  }
+
+  info(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('info')) {
+      console.info(this.formatMessage('info', message), ...args);
+    }
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('warn')) {
+      console.warn(this.formatMessage('warn', message), ...args);
+    }
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    if (this.shouldLog('error')) {
+      console.error(this.formatMessage('error', message), ...args);
+    }
+  }
+
+  /**
+   * 设置日志级别
+   */
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  /**
+   * 创建带有自定义前缀的子 logger
+   */
+  child(prefix: string): Logger {
+    return new Logger({
+      level: this.level,
+      prefix: `${this.prefix}:${prefix}`,
+      enableInProduction: this.enableInProduction,
+    });
+  }
+}
+
+// 默认 logger 实例
+export const logger = new Logger();
+
+// 创建模块专用 logger
+export const createLogger = (prefix: string): Logger => {
+  return logger.child(prefix);
+};
+
+// 导出类型
+export type { LogLevel, LoggerConfig };
+export { Logger };
+
+export default logger;