create-pardx-scaffold 0.1.0

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

@@ -0,0 +1,329 @@
+'use client';
+
+/**
+ * Version Check Hook
+ *
+ * 检测前后端版本一致性，自动提示用户刷新页面。
+ *
+ * 工作原理:
+ * 1. 从 API 响应头获取版本信息
+ * 2. 定期轮询 /api/version/hash 检测更新
+ * 3. 版本不一致时提示用户刷新
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *     useVersionCheck({
+ *         onVersionMismatch: () => {
+ *             toast.info('检测到新版本，请刷新页面');
+ *         },
+ *     });
+ *
+ *     return <div>...</div>;
+ * }
+ * ```
+ */
+
+import { useEffect, useRef, useCallback, useState } from 'react';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface VersionInfo {
+  appVersion: string;
+  apiVersion: string;
+  buildVersion: string;
+  buildTime: string;
+  environment: string;
+}
+
+export interface VersionCheckResult {
+  needsRefresh: boolean;
+  reason?: 'outdated' | 'incompatible' | 'major_update';
+  serverVersion: string;
+  clientVersion: string;
+  action?: 'refresh' | 'update' | 'none';
+  message?: string;
+}
+
+export interface UseVersionCheckOptions {
+  /**
+   * 检查间隔 (毫秒)
+   * 默认: 60000 (1分钟)
+   */
+  checkInterval?: number;
+
+  /**
+   * 是否自动刷新
+   * 默认: false
+   */
+  autoRefresh?: boolean;
+
+  /**
+   * 版本不一致时的回调
+   */
+  onVersionMismatch?: (result: VersionCheckResult) => void;
+
+  /**
+   * 自定义 API 基础 URL
+   */
+  apiBaseUrl?: string;
+
+  /**
+   * 是否启用检查
+   * 默认: true
+   */
+  enabled?: boolean;
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const VERSION_STORAGE_KEY = 'pardx:app:version';
+const BUILD_STORAGE_KEY = 'pardx:app:build';
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+export function useVersionCheck(options: UseVersionCheckOptions = {}) {
+  const {
+    checkInterval = 60000,
+    autoRefresh = false,
+    onVersionMismatch,
+    apiBaseUrl = process.env.NEXT_PUBLIC_API_BASE_URL || '/api',
+    enabled = true,
+  } = options;
+
+  const [versionInfo, setVersionInfo] = useState<VersionInfo | null>(null);
+  const [needsRefresh, setNeedsRefresh] = useState(false);
+  const [checkResult, setCheckResult] = useState<VersionCheckResult | null>(
+    null,
+  );
+  const intervalRef = useRef<NodeJS.Timeout | null>(null);
+  const initialBuildRef = useRef<string | null>(null);
+
+  /**
+   * 获取服务端版本信息
+   */
+  const fetchVersionInfo =
+    useCallback(async (): Promise<VersionInfo | null> => {
+      try {
+        const response = await fetch(`${apiBaseUrl}/version`, {
+          method: 'GET',
+          headers: {
+            'Cache-Control': 'no-cache',
+          },
+        });
+
+        if (!response.ok) {
+          return null;
+        }
+
+        const data = await response.json();
+        return data.data || data;
+      } catch (error) {
+        console.warn('Failed to fetch version info:', error);
+        return null;
+      }
+    }, [apiBaseUrl]);
+
+  /**
+   * 获取构建哈希 (轻量级)
+   */
+  const fetchBuildHash = useCallback(async (): Promise<{
+    hash: string;
+    time: string;
+  } | null> => {
+    try {
+      const response = await fetch(`${apiBaseUrl}/version/hash`, {
+        method: 'GET',
+        headers: {
+          'Cache-Control': 'no-cache, no-store, must-revalidate',
+        },
+      });
+
+      if (!response.ok) {
+        return null;
+      }
+
+      const data = await response.json();
+      return data.data || data;
+    } catch (error) {
+      console.warn('Failed to fetch build hash:', error);
+      return null;
+    }
+  }, [apiBaseUrl]);
+
+  /**
+   * 检查版本
+   */
+  const checkVersion = useCallback(async () => {
+    const buildInfo = await fetchBuildHash();
+    if (!buildInfo) {
+      return;
+    }
+
+    // 首次加载，保存构建版本
+    if (!initialBuildRef.current) {
+      initialBuildRef.current = buildInfo.hash;
+      localStorage.setItem(BUILD_STORAGE_KEY, buildInfo.hash);
+      return;
+    }
+
+    // 比较构建版本
+    if (buildInfo.hash !== initialBuildRef.current) {
+      const result: VersionCheckResult = {
+        needsRefresh: true,
+        reason: 'outdated',
+        serverVersion: buildInfo.hash,
+        clientVersion: initialBuildRef.current,
+        action: 'refresh',
+        message: '检测到新版本，请刷新页面',
+      };
+
+      setCheckResult(result);
+      setNeedsRefresh(true);
+
+      if (onVersionMismatch) {
+        onVersionMismatch(result);
+      }
+
+      if (autoRefresh) {
+        window.location.reload();
+      }
+    }
+  }, [fetchBuildHash, onVersionMismatch, autoRefresh]);
+
+  /**
+   * 手动刷新
+   */
+  const refresh = useCallback(() => {
+    window.location.reload();
+  }, []);
+
+  /**
+   * 跳过刷新 (用户选择稍后刷新)
+   */
+  const skipRefresh = useCallback(() => {
+    setNeedsRefresh(false);
+    // 更新本地存储的版本，避免重复提示
+    if (checkResult?.serverVersion) {
+      initialBuildRef.current = checkResult.serverVersion;
+      localStorage.setItem(BUILD_STORAGE_KEY, checkResult.serverVersion);
+    }
+  }, [checkResult]);
+
+  // 初始化
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    // 从存储恢复构建版本
+    const storedBuild = localStorage.getItem(BUILD_STORAGE_KEY);
+    if (storedBuild) {
+      initialBuildRef.current = storedBuild;
+    }
+
+    // 获取版本信息
+    fetchVersionInfo().then((info) => {
+      if (info) {
+        setVersionInfo(info);
+        localStorage.setItem(VERSION_STORAGE_KEY, JSON.stringify(info));
+      }
+    });
+
+    // 首次检查
+    checkVersion();
+
+    // 设置定时检查
+    intervalRef.current = setInterval(checkVersion, checkInterval);
+
+    return () => {
+      if (intervalRef.current) {
+        clearInterval(intervalRef.current);
+      }
+    };
+  }, [enabled, checkInterval, fetchVersionInfo, checkVersion]);
+
+  // 监听页面可见性变化
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const handleVisibilityChange = () => {
+      if (document.visibilityState === 'visible') {
+        checkVersion();
+      }
+    };
+
+    document.addEventListener('visibilitychange', handleVisibilityChange);
+
+    return () => {
+      document.removeEventListener('visibilitychange', handleVisibilityChange);
+    };
+  }, [enabled, checkVersion]);
+
+  return {
+    /** 服务端版本信息 */
+    versionInfo,
+    /** 是否需要刷新 */
+    needsRefresh,
+    /** 版本检查结果 */
+    checkResult,
+    /** 手动刷新 */
+    refresh,
+    /** 跳过刷新 */
+    skipRefresh,
+    /** 手动检查版本 */
+    checkVersion,
+  };
+}
+
+// ============================================================================
+// Utility: 从响应头获取版本
+// ============================================================================
+
+/**
+ * 从 fetch 响应头获取版本信息
+ */
+export function getVersionFromHeaders(
+  response: Response,
+): Partial<VersionInfo> {
+  return {
+    appVersion: response.headers.get('x-app-version') || undefined,
+    apiVersion: response.headers.get('x-api-version') || undefined,
+    buildVersion: response.headers.get('x-build-version') || undefined,
+    buildTime: response.headers.get('x-build-time') || undefined,
+  };
+}
+
+/**
+ * 创建带版本检查的 fetch 包装器
+ */
+export function createVersionAwareFetch(
+  onVersionMismatch?: (currentBuild: string, serverBuild: string) => void,
+) {
+  let currentBuild: string | null = null;
+
+  return async (
+    input: RequestInfo | URL,
+    init?: RequestInit,
+  ): Promise<Response> => {
+    const response = await fetch(input, init);
+
+    const serverBuild = response.headers.get('x-build-version');
+    if (serverBuild) {
+      if (currentBuild && currentBuild !== serverBuild) {
+        onVersionMismatch?.(currentBuild, serverBuild);
+      }
+      currentBuild = serverBuild;
+    }
+
+    return response;
+  };
+}

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

@@ -0,0 +1,50 @@
+/**
+ * i18n 配置文件
+ * 定义支持的语言、默认语言和命名空间
+ */
+
+// 支持的语言列表
+export const locales = ['zh-CN', 'en'] as const;
+
+// 默认语言
+export const defaultLocale = 'zh-CN' as const;
+
+// 语言类型
+export type Locale = (typeof locales)[number];
+
+// 语言显示名称
+export const localeNames: Record<Locale, string> = {
+  'zh-CN': '简体中文',
+  en: 'English',
+};
+
+// 语言图标（可选，用于 UI 显示）
+export const localeFlags: Record<Locale, string> = {
+  'zh-CN': '🇨🇳',
+  en: '🇺🇸',
+};
+
+// 命名空间列表（与 locales/ 目录下的 JSON 文件对应）
+export const namespaces = [
+  'assessment',
+  'chat',
+  'common',
+  'creative',
+  'daily-challenge',
+  'errors',
+  'forms',
+  'memory',
+  'navigation',
+  'recommendation',
+  'recruitment',
+  'settings',
+  'subscription',
+  'validation',
+] as const;
+
+export type Namespace = (typeof namespaces)[number];
+
+// 检查是否是有效的 locale
+export function isValidLocale(locale: string): locale is Locale {
+  return locales.includes(locale as Locale);
+}

package/template/apps/web/i18n/index.ts

@@ -0,0 +1,30 @@
+/**
+ * i18n 模块统一导出
+ */
+
+// 配置
+export {
+  locales,
+  defaultLocale,
+  localeNames,
+  localeFlags,
+  namespaces,
+  isValidLocale,
+  type Locale,
+  type Namespace,
+} from './config';
+
+// 路由
+export { routing } from './routing';
+
+// 导航工具
+export {
+  Link,
+  redirect,
+  usePathname,
+  useRouter,
+  getPathname,
+} from './navigation';
+
+// 类型定义
+export type { AppMessages } from './types';

package/template/apps/web/i18n/navigation.ts

@@ -0,0 +1,26 @@
+/**
+ * 国际化导航工具
+ * 提供支持多语言的导航组件和 hooks
+ */
+
+import { createNavigation } from 'next-intl/navigation';
+import { routing } from './routing';
+
+// 创建国际化导航工具
+// 这些导出的工具会自动处理语言前缀
+export const {
+  // 国际化的 Link 组件，自动添加语言前缀
+  Link,
+
+  // 国际化的 redirect 函数
+  redirect,
+
+  // 获取当前路径（不含语言前缀）
+  usePathname,
+
+  // 国际化的 router
+  useRouter,
+
+  // 获取完整路径（含语言前缀）
+  getPathname,
+} = createNavigation(routing);

package/template/apps/web/i18n/request.ts

@@ -0,0 +1,50 @@
+/**
+ * 服务端翻译请求配置
+ * 用于 Next.js 服务端组件加载翻译
+ *
+ * 优化说明：
+ * - 动态导入所有命名空间，无需手动维护导入列表
+ * - 自动同步 config.ts 中定义的命名空间
+ * - 添加新翻译文件时无需修改此文件
+ */
+
+import { getRequestConfig } from 'next-intl/server';
+import { routing } from './routing';
+import { namespaces } from './config';
+
+export default getRequestConfig(async ({ requestLocale }) => {
+  // 获取请求的语言
+  let locale = await requestLocale;
+
+  // 验证语言是否在支持的列表中
+  if (
+    !locale ||
+    !routing.locales.includes(locale as (typeof routing.locales)[number])
+  ) {
+    locale = routing.defaultLocale;
+  }
+
+  // 动态导入所有命名空间
+  const messageImports = await Promise.all(
+    namespaces.map((namespace) =>
+      import(`../locales/${locale}/${namespace}.json`).then((module) => ({
+        namespace,
+        messages: module.default,
+      })),
+    ),
+  );
+
+  // 构建消息对象
+  const messages = messageImports.reduce(
+    (acc, { namespace, messages }) => {
+      acc[namespace] = messages;
+      return acc;
+    },
+    {} as Record<string, any>,
+  );
+
+  return {
+    locale,
+    messages,
+  };
+});

package/template/apps/web/i18n/routing.ts

@@ -0,0 +1,21 @@
+/**
+ * i18n 路由配置
+ * 定义多语言路由规则
+ */
+
+import { defineRouting } from 'next-intl/routing';
+import { locales, defaultLocale } from './config';
+
+export const routing = defineRouting({
+  // 支持的语言列表
+  locales,
+
+  // 默认语言
+  defaultLocale,
+
+  // 语言前缀策略
+  // 'as-needed': 默认语言不显示前缀，其他语言显示
+  // 'always': 所有语言都显示前缀
+  // 'never': 不显示前缀（不推荐）
+  localePrefix: 'as-needed',
+});

package/template/apps/web/i18n/types.ts

@@ -0,0 +1,57 @@
+/**
+ * i18n 类型定义
+ * 为翻译键提供类型安全
+ *
+ * 使用方式：
+ * import type { TranslationKeys } from '@/i18n/types';
+ * const key: TranslationKeys = 'common.actions.save';
+ */
+
+import type zhCN from '../locales/zh-CN/common.json';
+import type zhCNNavigation from '../locales/zh-CN/navigation.json';
+import type zhCNForms from '../locales/zh-CN/forms.json';
+import type zhCNErrors from '../locales/zh-CN/errors.json';
+import type zhCNValidation from '../locales/zh-CN/validation.json';
+import type zhCNChat from '../locales/zh-CN/chat.json';
+import type zhCNRecruitment from '../locales/zh-CN/recruitment.json';
+import type zhCNAssessment from '../locales/zh-CN/assessment.json';
+import type zhCNCreative from '../locales/zh-CN/creative.json';
+import type zhCNSettings from '../locales/zh-CN/settings.json';
+import type zhCNSubscription from '../locales/zh-CN/subscription.json';
+import type zhCNRecommendation from '../locales/zh-CN/recommendation.json';
+import type zhCNMemory from '../locales/zh-CN/memory.json';
+import type zhCNDailyChallenge from '../locales/zh-CN/daily-challenge.json';
+
+/**
+ * 所有翻译消息的类型定义
+ */
+export interface AppMessages {
+  common: typeof zhCN;
+  navigation: typeof zhCNNavigation;
+  forms: typeof zhCNForms;
+  errors: typeof zhCNErrors;
+  validation: typeof zhCNValidation;
+  chat: typeof zhCNChat;
+  recruitment: typeof zhCNRecruitment;
+  assessment: typeof zhCNAssessment;
+  creative: typeof zhCNCreative;
+  settings: typeof zhCNSettings;
+  subscription: typeof zhCNSubscription;
+  recommendation: typeof zhCNRecommendation;
+  memory: typeof zhCNMemory;
+  'daily-challenge': typeof zhCNDailyChallenge;
+}
+
+/**
+ * 声明 next-intl 的类型
+ * 这样 useTranslations() 就能获得类型提示
+ */
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace IntlMessages {
+    // eslint-disable-next-line @typescript-eslint/no-empty-interface
+    interface Messages extends AppMessages {}
+  }
+}
+
+export {};

package/template/apps/web/lib/actions/auth.ts

@@ -0,0 +1,81 @@
+'use server';
+import request from '@/lib/requests';
+import type { TikTokAccessToken } from '@repo/types/auth';
+
+export async function getOAuthUrl(provider: string) {
+  const now = new Date().getTime();
+  switch (provider) {
+    case 'tiktok':
+      return `${process.env.TIKTOK_ENDPOINT_OAUTH}?client_key=${process.env.TIKTOK_CLIENT_KEY}&response_type=code&scope=${process.env.TIKTOK_AUTH_SCOPES}&redirect_uri=${process.env.TIKTOK_REDIRECT_URI}&state=${now}`;
+    case 'instagram':
+    default:
+      return;
+  }
+}
+
+// Fetch an access token using an authorization code
+export async function getTiktokAccessToken(code: string) {
+  const resp = await request.post<TikTokAccessToken>(
+    `${process.env.TIKTOK_API_ENDPOINT}/v2/oauth/token/`,
+    {
+      params: {
+        client_key: process.env.TIKTOK_CLIENT_KEY,
+        client_secret: process.env.TIKTOK_CLIENT_SECRET,
+        code: code,
+        grant_type: 'authorization_code',
+        redirect_uri: process.env.TIKTOK_REDIRECT_URI,
+      },
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+    },
+  );
+  return resp;
+}
+
+// Refresh an access token using a refresh token
+export async function refreshTiktokAccessToken(refreshToken: string) {
+  const fields = '';
+  const resp = await request.post<TikTokAccessToken>(
+    `${process.env.TIKTOK_API_ENDPOINT}/v2/oauth/token/?fields=${fields}`,
+    {
+      params: {
+        client_key: process.env.TIKTOK_CLIENT_KEY,
+        client_secret: process.env.TIKTOK_CLIENT_SECRET,
+        refresh_token: refreshToken,
+        grant_type: 'refresh_token',
+      },
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+    },
+  );
+  return resp;
+}
+
+// Get User Info
+export async function getTiktokUserProfile(accessToken: string) {
+  const resp = await request.get(
+    `${process.env.TIKTOK_API_ENDPOINT}/v2/user/info/`,
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    },
+  );
+  return resp;
+}
+
+/**
+ * 
+ {
+    "access_token": "act.8dsjbPDiBVQzq34dd1X2U47e6r6BsvP7eTBrwYa3O91XMFPpIeTq1pYYt2Ik!5096.va",
+    "expires_in": 86400,
+    "open_id": "-000u1leqP_Rg0TBecSi3DSYFpc5qQFO0aOV",
+    "refresh_expires_in": 31536000,
+    "refresh_token": "rft.z4K63WtDO7SFLl4jaI3yn4sUYSlTNTAS4NiYnLRt3iwLBOIH37UUZmamqgNM!5132.va",
+    "scope": "user.info.basic,video.publish,video.upload",
+    "token_type": "Bearer"
+}
+ * 
+ */