create-pardx-scaffold 0.1.0

package/template/apps/web/hooks/useNotificationSSE.ts

@@ -0,0 +1,270 @@
+'use client';
+
+/**
+ * useNotificationSSE Hook
+ * 使用 SSE (Server-Sent Events) 实时接收通知更新
+ *
+ * 功能：
+ * - 自动连接到 SSE 端点
+ * - 接收实时未读消息计数更新
+ * - 自动重连机制（指数退避）
+ * - 页面可见性感知（隐藏时暂停，显示时恢复）
+ *
+ * @example
+ * ```tsx
+ * function NotificationBadge() {
+ *   const { unreadCount, isConnected, error } = useNotificationSSE();
+ *
+ *   return (
+ *     <Badge>
+ *       {unreadCount > 0 ? unreadCount : null}
+ *       {!isConnected && <span className="text-yellow-500">!</span>}
+ *     </Badge>
+ *   );
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { /*getToken,*/ ensureValidToken, isTokenExpired } from '@/lib/api';
+import { notificationKeys } from '@/lib/api/contracts/hooks/notification';
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_BASE_URL || '';
+
+interface SSEMessage {
+  t: 'm' | 'p'; // 'm' = message, 'p' = ping
+  data: {
+    total?: number;
+    error?: string;
+    timestamp?: string;
+  };
+}
+
+interface UseNotificationSSEOptions {
+  /** 是否启用 SSE 连接，默认 true */
+  enabled?: boolean;
+  /** 初始重连延迟（毫秒），默认 1000 */
+  initialRetryDelay?: number;
+  /** 最大重连延迟（毫秒），默认 30000 */
+  maxRetryDelay?: number;
+}
+
+interface UseNotificationSSEReturn {
+  /** 未读消息计数 */
+  unreadCount: number;
+  /** 是否已连接 */
+  isConnected: boolean;
+  /** 连接错误 */
+  error: Error | null;
+  /** 手动重连 */
+  reconnect: () => void;
+  /** 断开连接 */
+  disconnect: () => void;
+}
+
+export function useNotificationSSE(
+  options: UseNotificationSSEOptions = {},
+): UseNotificationSSEReturn {
+  const {
+    enabled = true,
+    initialRetryDelay = 1000,
+    maxRetryDelay = 30000,
+  } = options;
+
+  const [unreadCount, setUnreadCount] = useState(0);
+  const [isConnected, setIsConnected] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const retryDelayRef = useRef(initialRetryDelay);
+  const retryTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const tokenCheckIntervalRef = useRef<NodeJS.Timeout | null>(null);
+  const isVisibleRef = useRef(true);
+
+  const queryClient = useQueryClient();
+
+  /**
+   * 清理函数
+   */
+  const cleanup = useCallback(() => {
+    if (eventSourceRef.current) {
+      eventSourceRef.current.close();
+      eventSourceRef.current = null;
+    }
+    if (retryTimeoutRef.current) {
+      clearTimeout(retryTimeoutRef.current);
+      retryTimeoutRef.current = null;
+    }
+    if (tokenCheckIntervalRef.current) {
+      clearInterval(tokenCheckIntervalRef.current);
+      tokenCheckIntervalRef.current = null;
+    }
+    setIsConnected(false);
+  }, []);
+
+  /**
+   * 连接到 SSE 端点
+   */
+  const connect = useCallback(async () => {
+    // 清理现有连接
+    cleanup();
+
+    try {
+      // 确保 token 有效（如果过期则自动刷新）
+      // 这很重要，因为 access_token 有效期只有 5 分钟
+      const token = await ensureValidToken();
+      if (!token) {
+        setError(new Error('未登录'));
+        return;
+      }
+
+      // 构建 SSE URL
+      // 注意：标准 EventSource 不支持自定义 headers，所以使用 URL 参数传递 token
+      // 后端期望的参数名是 access_token（见 auth.guard.ts）
+      const sseUrl = new URL(`${API_BASE_URL}/sse/message/unread`);
+      sseUrl.searchParams.set('access_token', token);
+
+      const eventSource = new EventSource(sseUrl.toString(), {
+        withCredentials: true,
+      });
+
+      eventSource.onopen = () => {
+        setIsConnected(true);
+        setError(null);
+        // 重置重试延迟
+        retryDelayRef.current = initialRetryDelay;
+
+        // 启动 token 过期检查（每 30 秒检查一次）
+        // 如果 token 即将过期（剩余时间少于 1 分钟），主动重连以使用新 token
+        if (tokenCheckIntervalRef.current) {
+          clearInterval(tokenCheckIntervalRef.current);
+        }
+        tokenCheckIntervalRef.current = setInterval(() => {
+          // 检查 token 是否过期或即将过期
+          if (isTokenExpired()) {
+            console.log('Token 已过期，重新连接 SSE...');
+            // connect 是 async 函数，但这里不需要 await
+            connect().catch((err) => {
+              console.error('Token 过期后重连失败:', err);
+            });
+          }
+        }, 30000); // 每 30 秒检查一次
+      };
+
+      eventSource.onmessage = (event) => {
+        try {
+          const message: SSEMessage = JSON.parse(event.data);
+
+          if (message.t === 'm' && message.data) {
+            // 收到消息更新
+            if (typeof message.data.total === 'number') {
+              setUnreadCount(message.data.total);
+              // 同时使 React Query 缓存失效，确保数据一致性
+              queryClient.invalidateQueries({
+                queryKey: notificationKeys.unreadCount(),
+              });
+            }
+          }
+          // 忽略 ping 消息 (t === 'p')
+        } catch (err) {
+          console.error('SSE 消息解析失败:', err);
+        }
+      };
+
+      eventSource.onerror = (event) => {
+        console.log('SSE 连接错误:', event);
+        setIsConnected(false);
+
+        // 关闭当前连接
+        eventSource.close();
+        eventSourceRef.current = null;
+
+        // 如果页面可见且启用了 SSE，尝试重连
+        if (isVisibleRef.current && enabled) {
+          setError(new Error('连接断开，正在重试...'));
+
+          // 指数退避重连
+          retryTimeoutRef.current = setTimeout(() => {
+            retryDelayRef.current = Math.min(
+              retryDelayRef.current * 2,
+              maxRetryDelay,
+            );
+            // connect 是 async 函数，需要处理 Promise
+            connect().catch((err) => {
+              console.error('重连失败:', err);
+            });
+          }, retryDelayRef.current);
+        }
+      };
+
+      eventSourceRef.current = eventSource;
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error('连接失败'));
+      setIsConnected(false);
+    }
+  }, [cleanup, enabled, initialRetryDelay, maxRetryDelay, queryClient]);
+
+  /**
+   * 手动重连
+   */
+  const reconnect = useCallback(() => {
+    retryDelayRef.current = initialRetryDelay;
+    connect();
+  }, [connect, initialRetryDelay]);
+
+  /**
+   * 断开连接
+   */
+  const disconnect = useCallback(() => {
+    cleanup();
+    setUnreadCount(0);
+    setError(null);
+  }, [cleanup]);
+
+  /**
+   * 页面可见性变化处理
+   */
+  useEffect(() => {
+    const handleVisibilityChange = () => {
+      isVisibleRef.current = document.visibilityState === 'visible';
+
+      if (isVisibleRef.current && enabled && !eventSourceRef.current) {
+        // 页面变为可见且没有活跃连接，重新连接
+        connect();
+      } else if (!isVisibleRef.current && eventSourceRef.current) {
+        // 页面变为隐藏，断开连接以节省资源
+        cleanup();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [enabled, connect, cleanup]);
+
+  /**
+   * 初始化连接
+   */
+  useEffect(() => {
+    if (enabled) {
+      connect();
+    } else {
+      cleanup();
+    }
+
+    return cleanup;
+  }, [enabled, connect, cleanup]);
+
+  return {
+    unreadCount,
+    isConnected,
+    error,
+    reconnect,
+    disconnect,
+  };
+}
+
+export default useNotificationSSE;

package/template/apps/web/hooks/useOperationFeedback.ts

@@ -0,0 +1,108 @@
+/**
+ * useOperationFeedback - 统一的操作反馈 Hook
+ * 提供一致的成功/错误/警告提示
+ */
+
+import { useCallback } from 'react';
+import { toast } from 'sonner';
+import { useTranslations } from 'next-intl';
+
+interface ToastOptions {
+  duration?: number;
+  position?:
+    | 'top-left'
+    | 'top-right'
+    | 'top-center'
+    | 'bottom-left'
+    | 'bottom-right'
+    | 'bottom-center';
+}
+
+/**
+ * 统一的操作反馈 Hook
+ *
+ * @example
+ * ```tsx
+ * const { success, error, warning, info } = useOperationFeedback();
+ *
+ * success('操作成功');
+ * error('操作失败');
+ * ```
+ */
+export function useOperationFeedback() {
+  const t = useTranslations('common');
+
+  const defaultOptions: ToastOptions = {
+    duration: 3000,
+    position: 'top-right',
+  };
+
+  const success = useCallback((message: string, options?: ToastOptions) => {
+    toast.success(message, {
+      ...defaultOptions,
+      ...options,
+      duration: options?.duration ?? 2000, // 成功提示稍短
+    });
+  }, []);
+
+  const error = useCallback((message: string, options?: ToastOptions) => {
+    toast.error(message, {
+      ...defaultOptions,
+      ...options,
+      duration: options?.duration ?? 4000, // 错误提示稍长
+    });
+  }, []);
+
+  const warning = useCallback((message: string, options?: ToastOptions) => {
+    toast.warning(message, {
+      ...defaultOptions,
+      ...options,
+      duration: options?.duration ?? 3000,
+    });
+  }, []);
+
+  const info = useCallback((message: string, options?: ToastOptions) => {
+    toast.info(message, {
+      ...defaultOptions,
+      ...options,
+      duration: options?.duration ?? 3000,
+    });
+  }, []);
+
+  const loading = useCallback((message: string, options?: ToastOptions) => {
+    return toast.loading(message, {
+      ...defaultOptions,
+      ...options,
+    });
+  }, []);
+
+  const promise = useCallback(
+    <T>(
+      promise: Promise<T>,
+      messages: {
+        loading: string;
+        success: string | ((data: T) => string);
+        error: string | ((error: unknown) => string);
+      },
+      options?: ToastOptions,
+    ) => {
+      return toast.promise(promise, {
+        loading: messages.loading,
+        success: messages.success,
+        error: messages.error,
+        ...defaultOptions,
+        ...options,
+      });
+    },
+    [],
+  );
+
+  return {
+    success,
+    error,
+    warning,
+    info,
+    loading,
+    promise,
+  };
+}

package/template/apps/web/hooks/usePerformanceMonitor.ts

@@ -0,0 +1,105 @@
+/**
+ * Performance Monitoring Hook
+ *
+ * 性能监控 React Hook
+ * 用于在组件中监控和上报性能指标
+ */
+
+import { useEffect, useRef } from 'react';
+import { initWebVitals, type Metric } from '@/lib/performance/monitor';
+
+export interface UsePerformanceMonitorOptions {
+  /** 是否启用监控（默认：true） */
+  enabled?: boolean;
+  /** 自定义上报函数 */
+  onReport?: (metric: Metric) => void;
+  /** 仅在页面可见时监控（默认：true） */
+  onlyWhenVisible?: boolean;
+}
+
+/**
+ * 性能监控 Hook
+ *
+ * @example
+ * ```tsx
+ * function MyPage() {
+ *   usePerformanceMonitor({
+ *     onReport: (metric) => {
+ *       console.log('Performance metric:', metric);
+ *     },
+ *   });
+ *
+ *   return <div>Page content</div>;
+ * }
+ * ```
+ */
+export function usePerformanceMonitor(
+  options: UsePerformanceMonitorOptions = {},
+) {
+  const { enabled = true, onReport, onlyWhenVisible = true } = options;
+
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const isMonitoringRef = useRef(false);
+
+  useEffect(() => {
+    if (!enabled) return;
+    if (typeof window === 'undefined') return;
+
+    // 如果设置了仅可见时监控，检查页面可见性
+    if (onlyWhenVisible && document.hidden) {
+      // 等待页面可见时再初始化
+      const handleVisibilityChange = () => {
+        if (!document.hidden && !isMonitoringRef.current) {
+          cleanupRef.current = initWebVitals(onReport);
+          isMonitoringRef.current = true;
+        }
+      };
+
+      document.addEventListener('visibilitychange', handleVisibilityChange);
+
+      return () => {
+        document.removeEventListener(
+          'visibilitychange',
+          handleVisibilityChange,
+        );
+        if (cleanupRef.current) {
+          cleanupRef.current();
+        }
+      };
+    }
+
+    // 立即初始化监控
+    if (!isMonitoringRef.current) {
+      cleanupRef.current = initWebVitals(onReport);
+      isMonitoringRef.current = true;
+    }
+
+    return () => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        isMonitoringRef.current = false;
+      }
+    };
+  }, [enabled, onReport, onlyWhenVisible]);
+}
+
+/**
+ * 自定义性能指标测量 Hook
+ */
+export function usePerformanceMeasure(name: string, enabled = true) {
+  const startTimeRef = useRef<number | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+    if (!('performance' in window)) return;
+
+    startTimeRef.current = performance.now();
+
+    return () => {
+      if (startTimeRef.current !== null) {
+        const duration = performance.now() - startTimeRef.current;
+        console.log(`[Performance] ${name}: ${duration.toFixed(2)}ms`);
+      }
+    };
+  }, [name, enabled]);
+}

package/template/apps/web/hooks/usePermissions.ts

@@ -0,0 +1,17 @@
+/**
+ * Permission Hook
+ * 权限检查钩子
+ */
+
+export function usePermissions() {
+  const hasPermission = (
+    _module: string,
+    _resource: string,
+    _action: string,
+  ): boolean => {
+    // TODO: Implement permission check logic
+    return true;
+  };
+
+  return { hasPermission };
+}