create-pardx-scaffold 0.1.0 → 0.1.2

package/template/apps/web/config.ts

@@ -0,0 +1,115 @@
+// API 配置
+// API 基础地址从环境变量读取
+// 在 .env.local 文件中设置以下环境变量：
+// - NEXT_PUBLIC_API_BASE_URL: 登录、上传文件、测评等接口的基础地址
+
+/**
+ * 获取 API 基础地址（用于登录、上传文件、测评等）
+ */
+const getApiBaseUrl = (): string => {
+  const baseUrl = process.env.NEXT_PUBLIC_API_BASE_URL;
+
+  if (!baseUrl) {
+    // Use default value during build time or development
+    const defaultUrl = 'http://localhost:3100/api';
+    if (
+      process.env.NODE_ENV === 'development' ||
+      process.env.NEXT_PHASE === 'phase-production-build'
+    ) {
+      return defaultUrl;
+    }
+    // At runtime in production, use default if not set
+    console.warn('NEXT_PUBLIC_API_BASE_URL 未设置，使用默认值', defaultUrl);
+    return defaultUrl;
+  }
+
+  return baseUrl;
+};
+
+/**
+ * 获取品牌名称
+ */
+const getBrandName = (): string => {
+  const brandName = process.env.NEXT_PUBLIC_BRAND_NAME;
+  return brandName || 'Pardx.AI';
+};
+
+/**
+ * 获取品牌 Logo 路径
+ */
+const getBrandLogo = (): string => {
+  const brandLogo = process.env.NEXT_PUBLIC_BRAND_LOGO;
+  return brandLogo || '/logo.svg';
+};
+
+/**
+ * 获取品牌完整标题（用于页面标题）
+ *
+ * 产品定位：多智能体驱动的内容创作与运营平台
+ * 核心能力：
+ * - AI 内容创作（智能写作、创意生成）
+ * - 知识库管理（进化型知识库、智能提取、质量评估）
+ * - 智能推荐（向量检索、协同过滤）
+ * - 招聘面试（AI 招聘 Agent、简历解析、智能匹配）
+ * - 会议管理（实时转写、知识提取、纪要生成）
+ * - 多智能体协作（AG-UI/Agno）
+ */
+const getBrandTitle = (): string => {
+  const brandTitle = process.env.NEXT_PUBLIC_BRAND_TITLE;
+  return brandTitle || 'PardxAI - Multi-Agent Content Creation ';
+};
+
+/**
+ * 获取品牌描述（用于页面描述）
+ *
+ * 描述应包含：
+ * - 产品定位（多智能体平台）
+ * - 核心功能（内容创作、知识管理、智能推荐、招聘面试）
+ * - 技术优势（AI 驱动、多智能体协作）
+ * - 目标用户（企业团队、内容创作者、HR 团队）
+ */
+const getBrandDescription = (): string => {
+  const brandDescription = process.env.NEXT_PUBLIC_BRAND_DESCRIPTION;
+  return (
+    brandDescription ||
+    'PardxAI is an AI-powered multi-agent platform for content creation.'
+  );
+};
+
+export const API_CONFIG = {
+  // API 基础地址（用于登录、上传文件、测评等）
+  baseUrl: getApiBaseUrl(),
+
+  // API 端点路径 这些断点是不适用ts-rest-api的，用于登录和校验权限的断点，如果未来需要使用ts-rest-api，则将这些断点迁移到ts-rest-api中
+  endpoints: {
+    // 登录端点
+    login: '/sign/in/mobile/password',
+
+    // Token 刷新端点
+    refreshToken: '/sign/refresh/token',
+  },
+};
+
+/**
+ * 品牌配置
+ * 可通过环境变量覆盖：
+ * - NEXT_PUBLIC_BRAND_NAME: 品牌名称（默认: "Pardx.AI"）
+ * - NEXT_PUBLIC_BRAND_LOGO: Logo 路径（默认: "/logo.svg"）
+ * - NEXT_PUBLIC_BRAND_TITLE: 页面标题（默认: "PardxAI - Multi-Agent Content Creation"）
+ * - NEXT_PUBLIC_BRAND_DESCRIPTION: 页面描述（默认: "PardxAI is an AI-powered multi-agent platform for content creation."）
+ *
+ * 产品定位说明：
+ * PardxAI 是一个多智能体驱动的内容创作与运营平台，提供以下核心能力：
+ * 1. AI 内容创作：智能写作、创意生成、多模态内容创作
+ * 2. 知识库管理：进化型知识库系统、智能知识提取、质量评估、版本控制、相似度检测与合并
+ * 3. 智能推荐：基于向量检索和协同过滤的知识推荐系统
+ * 4. 招聘面试：AI 招聘 Agent、简历解析、JD 分析、人才匹配、智能面试
+ * 5. 会议管理：实时转写、知识提取、智能纪要生成
+ * 6. 多智能体协作：AG-UI/Agno 集成，支持多智能体协同工作
+ */
+export const BRAND_CONFIG = {
+  name: getBrandName(),
+  logo: getBrandLogo(),
+  title: getBrandTitle(),
+  description: getBrandDescription(),
+};

package/template/apps/web/eslint.config.mjs

@@ -0,0 +1,4 @@
+import { nextJsConfig } from '@repo/config/eslint/next-js';
+
+/** @type {import("eslint").Linter.Config} */
+export default nextJsConfig;

package/template/apps/web/lib/api/avatar-upload.ts

@@ -32,6 +32,7 @@ export async function uploadAvatar(
     body: {
       signature,
       filename,
+      fsize: file.size,
       bucket: 'pardx-image',
       vendor: 'oss',
     },

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,
+};