create-pardx-scaffold 0.1.10 → 0.1.11

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

@@ -0,0 +1,128 @@
+'use client';
+
+/**
+ * 数据预加载工具
+ * 用于在用户可能需要数据之前预先加载，提升用户体验
+ */
+
+import { useEffect, useRef, useCallback, useMemo } from 'react';
+import { usePathname } from '@/i18n/navigation';
+import { queryClient } from './query-client';
+import { cacheTime } from './cache-config';
+
+// ============================================================================
+// 单项预加载函数（示例）
+// ============================================================================
+
+/**
+ * 预加载用户信息
+ * 在应用初始化或登录后调用
+ */
+export async function prefetchUserInfo() {
+  // Implement based on your API contracts
+  // Example:
+  // return queryClient.prefetchQuery({
+  //   queryKey: ['user', 'info'],
+  //   queryFn: async () => {
+  //     return userClient.getInfo({});
+  //   },
+  //   staleTime: cacheTime.short,
+  // });
+}
+
+/**
+ * 预加载仪表盘数据
+ * 在登录成功后或应用初始化时调用
+ */
+export async function prefetchDashboardData() {
+  await Promise.all([
+    // prefetchUserInfo(),
+    // Add other prefetch functions as needed
+  ]);
+}
+
+// ============================================================================
+// 预加载 Hooks
+// ============================================================================
+
+/**
+ * 获取预加载函数的 Hook
+ * 返回可以在事件（如 hover）中调用的预加载函数
+ */
+export function usePrefetch() {
+  const createHoverHandler = useCallback(
+    (prefetchFn: () => Promise<unknown>) => {
+      let prefetched = false;
+      return () => {
+        if (!prefetched) {
+          prefetched = true;
+          prefetchFn();
+        }
+      };
+    },
+    [],
+  );
+
+  return {
+    createHoverHandler,
+    prefetchUserInfo,
+    prefetchDashboardData,
+  };
+}
+
+/**
+ * 导航项预加载映射
+ * 根据路由路径返回对应的预加载函数
+ */
+export function useNavPrefetch() {
+  const { createHoverHandler } = usePrefetch();
+
+  const navPrefetchMap = useMemo(
+    () => ({
+      '/dashboard': createHoverHandler(prefetchDashboardData),
+      // Add more route prefetch mappings as needed
+    }),
+    [createHoverHandler],
+  );
+
+  return navPrefetchMap;
+}
+
+/**
+ * 路由预加载映射
+ * 根据当前路由路径预加载对应页面数据
+ */
+const routePrefetchMap: Record<string, () => Promise<unknown>> = {
+  '/dashboard': prefetchDashboardData,
+  // Add more route prefetch mappings as needed
+};
+
+/**
+ * 路由变化时自动预加载 Hook
+ * 在组件中使用，当路由变化时自动预加载目标页面数据
+ */
+export function useRoutePrefetch() {
+  const pathname = usePathname();
+  const previousPathname = useRef<string | null>(null);
+
+  useEffect(() => {
+    const currentPath = pathname || '/';
+
+    if (previousPathname.current === currentPath) {
+      return;
+    }
+
+    previousPathname.current = currentPath;
+
+    const prefetchFn = routePrefetchMap[currentPath];
+
+    if (prefetchFn) {
+      prefetchFn().catch((error) => {
+        console.warn(
+          `Failed to prefetch data for route ${currentPath}:`,
+          error,
+        );
+      });
+    }
+  }, [pathname]);
+}

package/template/apps/web/lib/api/query-client.ts

@@ -0,0 +1,37 @@
+'use client';
+
+/**
+ * Query Client 单例
+ * 用于在 hooks 外部访问 queryClient（如预加载）
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+import { cacheTime, gcTime } from './cache-config';
+
+/**
+ * 创建 QueryClient 实例
+ */
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: cacheTime.medium,
+        gcTime: gcTime.medium,
+        retry: 1,
+        refetchOnWindowFocus: false,
+      },
+    },
+  });
+}
+
+// 单例实例
+let queryClientInstance: QueryClient | undefined;
+
+/**
+ * 获取 QueryClient 实例
+ * 在组件外使用（如预加载）
+ */
+export const queryClient =
+  typeof window !== 'undefined'
+    ? (queryClientInstance ??= createQueryClient())
+    : createQueryClient();

package/template/apps/web/lib/i18n/runtime-translator.ts

@@ -0,0 +1,48 @@
+/**
+ * 运行时翻译注册表：供 fetch 层、非 React 模块在客户端使用 next-intl 文案。
+ * 由 RuntimeI18nBridge 在挂载时注入各 namespace 的 t 函数。
+ */
+
+export type NamespaceTranslate = (
+  key: string,
+  values?: Record<string, string | number>,
+) => string;
+
+const registry = new Map<string, NamespaceTranslate>();
+
+export function registerIntlNamespace(
+  namespace: string,
+  translate: NamespaceTranslate | null,
+): void {
+  if (translate) {
+    registry.set(namespace, translate);
+  } else {
+    registry.delete(namespace);
+  }
+}
+
+export function intlNs(
+  namespace: string,
+  key: string,
+  values?: Record<string, string | number>,
+): string {
+  const t = registry.get(namespace);
+  if (!t) {
+    return key;
+  }
+  try {
+    return values && Object.keys(values).length > 0 ? t(key, values) : t(key);
+  } catch {
+    return key;
+  }
+}
+
+/** 带 locale 前缀的登录路径，供 401 跳转 */
+export function getLocaleLoginPath(): string {
+  if (typeof window === 'undefined') {
+    return '/login';
+  }
+  const pathname = window.location.pathname;
+  const m = pathname.match(/^\/(en|zh-CN)(?=\/|$)/);
+  return m ? `${m[0]}/login` : '/login';
+}

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

@@ -1,4 +1,4 @@
-import { API_CONFIG } from './config';
+import { API_CONFIG } from '@/config';
 
 function urlEncode(params: Record<string, unknown>) {
   if (params && typeof params === 'object' && !Array.isArray(params)) {

package/template/apps/web/providers/app-provider.tsx

@@ -7,7 +7,7 @@
 
 import type { ReactNode } from 'react';
 import { createContext, useContext } from 'react';
-import { BRAND_CONFIG } from '@/lib/config';
+import { BRAND_CONFIG } from '@/config';
 
 interface AppContextType {
   title: string;

package/template/apps/web/providers/auth-provider.tsx

@@ -0,0 +1,228 @@
+'use client';
+
+/**
+ * Auth Context Provider
+ *
+ * Provides authentication state and methods throughout the application.
+ * Manages user info, tokens, login/logout functionality.
+ */
+import {
+  createContext,
+  useContext,
+  useState,
+  useEffect,
+  useCallback,
+  type ReactNode,
+} from 'react';
+import { useRouter } from '@/i18n/navigation';
+import type { UserInfo, LoginSuccess } from '@repo/contracts';
+import {
+  getUser,
+  setUser,
+  getTokens,
+  setTokens,
+  clearAll,
+  isTokenExpired,
+} from '@/lib/storage';
+import { signClient } from '@/lib/api/contracts/client';
+import { prefetchDashboardData } from '@/lib/api/prefetch';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+export interface AuthContextType {
+  // State
+  user: UserInfo | null;
+  isLoading: boolean;
+  isAuthenticated: boolean;
+  isAdmin: boolean;
+
+  // Actions
+  login: (data: LoginSuccess) => void;
+  logout: () => Promise<void>;
+  refreshUser: () => Promise<void>;
+}
+
+// ============================================================================
+// Context Creation
+// ============================================================================
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+// ============================================================================
+// Provider Component
+// ============================================================================
+
+interface AuthProviderProps {
+  children: ReactNode;
+}
+
+export function AuthProvider({ children }: AuthProviderProps) {
+  const [user, setUserState] = useState<UserInfo | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const router = useRouter();
+
+  // Initialize user from localStorage on mount and prefetch dashboard data
+  useEffect(() => {
+    const storedUser = getUser();
+    if (storedUser) {
+      setUserState(storedUser);
+      // Prefetch dashboard data for returning authenticated users
+      prefetchDashboardData().catch((error) => {
+        console.warn('Failed to prefetch dashboard data on init:', error);
+      });
+    }
+    setIsLoading(false);
+
+    // Listen for user info updates from other components
+    const handleUserUpdate = () => {
+      const updatedUser = getUser();
+      setUserState(updatedUser);
+    };
+
+    window.addEventListener('userInfoUpdated', handleUserUpdate);
+    return () => {
+      window.removeEventListener('userInfoUpdated', handleUserUpdate);
+    };
+  }, []);
+
+  // Login: store user and tokens, then prefetch dashboard data
+  const login = useCallback((data: LoginSuccess) => {
+    // Store user (merges with existing data if any)
+    setUser(data.user);
+    setTokens({
+      access: data.access,
+      refresh: data.refresh,
+      accessExpire: data.accessExpire,
+      expire: data.expire,
+    });
+    // Get the merged user from storage for state
+    const mergedUser = getUser();
+    setUserState(mergedUser);
+    // Prefetch dashboard data after successful login
+    prefetchDashboardData().catch((error) => {
+      console.warn('Failed to prefetch dashboard data:', error);
+    });
+  }, []);
+
+  // Logout: clear storage and redirect
+  const logout = useCallback(async () => {
+    try {
+      // Call sign out endpoint
+      await signClient.signOut({
+        body: {},
+      });
+    } catch (error) {
+      // Ignore errors during logout
+      console.warn('Sign out API call failed:', error);
+    } finally {
+      // Clear local storage
+      clearAll();
+      setUserState(null);
+      // Redirect to login page
+      router.push('/login');
+    }
+  }, [router]);
+
+  // Refresh user info from server
+  const refreshUser = useCallback(async () => {
+    const tokens = getTokens();
+    if (!tokens?.refresh) {
+      return;
+    }
+
+    try {
+      const response = await signClient.refreshToken({
+        query: { refresh: tokens.refresh },
+      });
+
+      if (response.status === 200 && response.body.data) {
+        const data = response.body.data;
+        // Store user (merges with existing data)
+        setUser(data.user);
+        setTokens({
+          access: data.access,
+          refresh: data.refresh,
+          accessExpire: data.accessExpire,
+          expire: data.expire,
+        });
+        // Get the merged user from storage for state
+        const mergedUser = getUser();
+        setUserState(mergedUser);
+      }
+    } catch (error) {
+      console.error('Failed to refresh user:', error);
+    }
+  }, []);
+
+  // Auto-refresh token before expiry
+  useEffect(() => {
+    if (!user) return;
+
+    const checkAndRefresh = () => {
+      if (isTokenExpired()) {
+        refreshUser();
+      }
+    };
+
+    const interval = setInterval(checkAndRefresh, 60000);
+    return () => clearInterval(interval);
+  }, [user, refreshUser]);
+
+  const value: AuthContextType = {
+    user,
+    isLoading,
+    isAuthenticated: !!user && !isTokenExpired(),
+    isAdmin: user?.isAdmin ?? false,
+    login,
+    logout,
+    refreshUser,
+  };
+
+  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
+}
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Hook to access auth context
+ * @throws Error if used outside AuthProvider
+ */
+export function useAuth(): AuthContextType {
+  const context = useContext(AuthContext);
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return context;
+}
+
+// ============================================================================
+// Utility Hooks
+// ============================================================================
+
+/**
+ * Hook to check if user is authenticated
+ */
+export function useIsAuthenticated(): boolean {
+  const { isAuthenticated } = useAuth();
+  return isAuthenticated;
+}
+
+/**
+ * Hook to get current user ID
+ */
+export function useUserId(): string | null {
+  const { user } = useAuth();
+  return user?.id ?? null;
+}
+
+/**
+ * Hook to check if current user is admin
+ */
+export function useIsAdmin(): boolean {
+  const { isAdmin } = useAuth();
+  return isAdmin;
+}

package/template/apps/web/providers/index.tsx

@@ -11,35 +11,54 @@ import NextTopLoader from 'nextjs-toploader';
 import { QueryProvider } from './query-provider';
 import { ThemeProvider } from './theme-provider';
 import { AppProvider } from './app-provider';
+import { AuthProvider } from './auth-provider';
+import { RuntimeI18nBridge } from '@/components/runtime-i18n-bridge';
 
 export { QueryProvider } from './query-provider';
 export { ThemeProvider } from './theme-provider';
 export { AppProvider, useApp } from './app-provider';
+export {
+  AuthProvider,
+  useAuth,
+  useIsAuthenticated,
+  useUserId,
+  useIsAdmin,
+} from './auth-provider';
+export { IntlClientProvider } from './intl-client-provider';
 
 interface ProvidersProps {
   children: ReactNode;
 }
 
 /**
- * Root Providers Component
+ * Root providers Component
  * 根 Providers 组件
  *
  * Combines all providers in the correct order:
- * 1. AppProvider - Application context
- * 2. ThemeProvider - Theme management
- * 3. QueryProvider - React Query
- * 4. UI components (Toaster, TopLoader)
+ * 1. AppProvider - Application context (brand, version)
+ * 2. ThemeProvider - Theme management (dark/light mode)
+ * 3. AuthProvider - Authentication state and methods
+ * 4. QueryProvider - React Query
+ * 5. UI components (Toaster, TopLoader)
  */
 export function Providers({ children }: ProvidersProps) {
   return (
     <AppProvider>
       <ThemeProvider>
-        <NextTopLoader color="transparent" />
-        <Toaster position="top-center" richColors />
-        <QueryProvider>{children}</QueryProvider>
+        <AuthProvider>
+          <NextTopLoader color="#000" showSpinner={false} height={2} />
+          <Toaster
+            position="top-center"
+            richColors
+            closeButton
+            duration={4000}
+          />
+          <RuntimeI18nBridge />
+          <QueryProvider>{children}</QueryProvider>
+        </AuthProvider>
       </ThemeProvider>
     </AppProvider>
   );
 }
 
-export default Providers;
+export default Providers;

package/template/apps/web/providers/intl-client-provider.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import type { AbstractIntlMessages } from 'next-intl';
+import { NextIntlClientProvider, IntlErrorCode } from 'next-intl';
+import type { Locale } from '@/i18n/config';
+
+interface IntlClientProviderProps {
+  locale: Locale;
+  messages: AbstractIntlMessages;
+  /** Set from server layout using NODE_ENV so the client bundle avoids env reads. */
+  enableMissingMessageLogging?: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Wraps next-intl client provider. When enableMissingMessageLogging is true,
+ * logs missing message keys to the console to catch JSON drift early.
+ */
+export function IntlClientProvider({
+  locale,
+  messages,
+  enableMissingMessageLogging = false,
+  children,
+}: IntlClientProviderProps) {
+  return (
+    <NextIntlClientProvider
+      locale={locale}
+      messages={messages}
+      onError={
+        enableMissingMessageLogging
+          ? (error) => {
+              if (error.code === IntlErrorCode.MISSING_MESSAGE) {
+                console.warn('[next-intl] Missing message:', error.message);
+              }
+            }
+          : undefined
+      }
+    >
+      {children}
+    </NextIntlClientProvider>
+  );
+}

package/template/apps/web/vitest.config.ts

@@ -2,12 +2,16 @@
  * Vitest Configuration for Next.js Web Application
  *
  * @see https://vitest.dev/config/
+ *
+ * Note: Vitest 4.x uses Vite 7 internally while @vitejs/plugin-react expects
+ * Vite 6 types. This type mismatch is known and doesn't affect functionality.
  */
 import { defineConfig } from 'vitest/config';
 import react from '@vitejs/plugin-react';
 import path from 'path';
 
 export default defineConfig({
+  // @ts-expect-error Vitest 4.x/Vite 7 type mismatch with @vitejs/plugin-react
   plugins: [react()],
   test: {
     // Test environment