create-pardx-scaffold 0.1.0

package/template/apps/web/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@repo/web",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint .",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf .next",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:cov": "vitest run --coverage",
+    "test:ui": "vitest --ui",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "test:e2e:headed": "playwright test --headed"
+  },
+  "dependencies": {
+    "@ag-ui/agno": "^0.0.3",
+    "@ag-ui/client": "^0.0.42",
+    "@ag-ui/core": "^0.0.42",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@repo/config": "workspace:*",
+    "@repo/constants": "workspace:*",
+    "@repo/contracts": "workspace:*",
+    "@repo/types": "workspace:*",
+    "@repo/ui": "workspace:*",
+    "@repo/utils": "workspace:*",
+    "@repo/validators": "workspace:*",
+    "@tanstack/react-form": "^1.27.7",
+    "@tanstack/react-query": "^5.0.0",
+    "@tanstack/react-virtual": "^3.13.16",
+    "@ts-rest/core": "^3.51.0",
+    "@ts-rest/react-query": "^3.51.0",
+    "cmdk": "^1.1.1",
+    "crypto-js": "^4.2.0",
+    "d3": "^7.9.0",
+    "date-fns": "^4.1.0",
+    "embla-carousel-react": "^8.6.0",
+    "jszip": "^3.10.1",
+    "lucide-react": "^0.562.0",
+    "next": "^16.1.4",
+    "next-intl": "^4.6.1",
+    "next-themes": "^0.2.0",
+    "nextjs-toploader": "^1.0.0",
+    "openai": "^6.0.0",
+    "react": "19.2.3",
+    "react-day-picker": "^9.13.0",
+    "react-dom": "19.2.3",
+    "react-dropzone": "^14.3.8",
+    "react-hook-form": "^7.69.0",
+    "react-markdown": "^10.1.0",
+    "reactflow": "^11.11.4",
+    "recharts": "^3.6.0",
+    "remark-gfm": "^4.0.1",
+    "shiki": "^3.19.0",
+    "sonner": "^1.0.0",
+    "web-vitals": "^5.1.0",
+    "zustand": "^5.0.9"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.57.0",
+    "@tailwindcss/postcss": "^4",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/crypto-js": "^4.2.2",
+    "@types/d3": "^7.4.3",
+    "@types/jszip": "^3.4.1",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "@typescript-eslint/eslint-plugin": "^8.39.0",
+    "@typescript-eslint/parser": "^8.39.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9",
+    "eslint-config-next": "^16.0.10",
+    "jsdom": "^27.3.0",
+    "minimatch": "^10.1.1",
+    "tailwindcss": "^4",
+    "typescript": "^5",
+    "typescript-eslint": "^8.18.0",
+    "vitest": "^4.0.16"
+  }
+}

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

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * App Provider - Application Context
+ * 应用 Context Provider
+ */
+
+import type { ReactNode } from 'react';
+import { createContext, useContext } from 'react';
+import { BRAND_CONFIG } from '@/lib/config';
+
+interface AppContextType {
+  title: string;
+  version: string;
+  brandName: string;
+  brandLogo: string;
+}
+
+const defaultContext: AppContextType = {
+  title: BRAND_CONFIG.name,
+  version: '0.1.0',
+  brandName: BRAND_CONFIG.name,
+  brandLogo: BRAND_CONFIG.logo,
+};
+
+const AppContext = createContext<AppContextType>(defaultContext);
+
+interface AppProviderProps {
+  children: ReactNode;
+  config?: Partial<AppContextType>;
+}
+
+export function AppProvider({ children, config }: AppProviderProps) {
+  const value = { ...defaultContext, ...config };
+
+  return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
+}
+
+export function useApp() {
+  const context = useContext(AppContext);
+  if (!context) {
+    throw new Error('useApp must be used within AppProvider');
+  }
+  return context;
+}

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

@@ -0,0 +1,45 @@
+'use client';
+
+/**
+ * Providers Index - Combined Providers
+ * 统一的 Providers 组合
+ */
+
+import type { ReactNode } from 'react';
+import { Toaster } from 'sonner';
+import NextTopLoader from 'nextjs-toploader';
+import { QueryProvider } from './query-provider';
+import { ThemeProvider } from './theme-provider';
+import { AppProvider } from './app-provider';
+
+export { QueryProvider } from './query-provider';
+export { ThemeProvider } from './theme-provider';
+export { AppProvider, useApp } from './app-provider';
+
+interface ProvidersProps {
+  children: ReactNode;
+}
+
+/**
+ * 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)
+ */
+export function Providers({ children }: ProvidersProps) {
+  return (
+    <AppProvider>
+      <ThemeProvider>
+        <NextTopLoader color="transparent" />
+        <Toaster position="top-center" richColors />
+        <QueryProvider>{children}</QueryProvider>
+      </ThemeProvider>
+    </AppProvider>
+  );
+}
+
+export default Providers;

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

@@ -0,0 +1,181 @@
+'use client';
+
+/**
+ * Query Provider - Enhanced React Query Configuration
+ * 增强的 React Query 配置
+ *
+ * 缓存策略说明：
+ * - 默认：5分钟 staleTime，30分钟 gcTime
+ * - 权限数据：2分钟（需要较快响应权限变更）
+ * - 静态数据：30分钟（角色、部门、模板等）
+ * - 知识库数据：1小时（公司信息、品牌、产品等）
+ * - 实时数据：30秒（未读消息数等）
+ *
+ * 知识单元缓存策略：
+ * - 知识单元列表/详情：5分钟（频繁访问，可能被编辑）
+ * - 知识树结构：15分钟（结构变化较少）
+ * - 知识版本历史：15分钟（历史记录稳定）
+ * - 合并建议：15分钟（需要定期更新）
+ * - 相似知识检测：30分钟（AI分析结果相对稳定）
+ * - 智能标签推荐：30分钟（AI分析结果相对稳定）
+ * - 贡献者统计：30分钟（统计数据变化较慢）
+ * - 质量评估：1小时（评估结果非常稳定）
+ * - 过期知识检测：1分钟（需要快速响应）
+ */
+
+import type { Query } from '@tanstack/react-query';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+import { toast } from 'sonner';
+import { handleApiErrorResponse } from '@/lib/errors';
+import { cacheTime, gcTime } from '@/lib/api/cache-config';
+
+// ============================================================================
+// 缓存策略配置
+// ============================================================================
+
+/**
+ * 根据 queryKey 获取差异化的 staleTime
+ * 不同类型的数据使用不同的缓存时间
+ */
+function getStaleTimeByQueryKey(queryKey: readonly unknown[]): number {
+  if (!queryKey || queryKey.length === 0) {
+    return cacheTime.medium; // 默认 5 分钟
+  }
+
+  const firstKey = queryKey[0];
+
+  if (typeof firstKey !== 'string') {
+    return cacheTime.medium;
+  }
+
+  // 消息相关数据
+  if (firstKey === 'messages') {
+    const secondKey = queryKey[1];
+    if (secondKey === 'unread-count') {
+      return cacheTime.realtime; // 30 秒
+    }
+    return cacheTime.medium; // 5 分钟
+  }
+
+  // 默认缓存时间
+  return cacheTime.medium;
+}
+
+/**
+ * 根据 queryKey 获取差异化的 gcTime
+ */
+function getGcTimeByQueryKey(queryKey: readonly unknown[]): number {
+  if (!queryKey || queryKey.length === 0) {
+    return gcTime.medium;
+  }
+
+  const firstKey = queryKey[0];
+
+  if (typeof firstKey !== 'string') {
+    return gcTime.medium;
+  }
+
+  // 实时数据使用较短的 gcTime
+  if (firstKey === 'messages') {
+    const secondKey = queryKey[1];
+    if (secondKey === 'unread-count') {
+      return gcTime.short; // 5 分钟
+    }
+  }
+
+  return gcTime.medium;
+}
+
+// ============================================================================
+// QueryClient 创建
+// ============================================================================
+
+/**
+ * Create QueryClient with optimized configuration
+ * 创建优化配置的 QueryClient
+ *
+ * React Query v5 支持 staleTime 作为函数动态计算缓存时间，
+ * gcTime 使用默认值（需要差异化时在各个 query 中单独设置）
+ */
+function createQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        // Retry configuration with exponential backoff
+        retry: (failureCount, error) => {
+          // Don't retry on 4xx errors (client errors)
+          if (error && typeof error === 'object' && 'status' in error) {
+            const status = (error as { status: number }).status;
+            if (status >= 400 && status < 500) {
+              return false;
+            }
+          }
+          // Retry up to 3 times for server errors
+          return failureCount < 3;
+        },
+        retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+
+        // 动态缓存策略 - staleTime 支持函数，根据 queryKey 计算
+        // gcTime 使用默认值（需要差异化时在各个 query 中单独设置）
+        staleTime: (query: Query) => getStaleTimeByQueryKey(query.queryKey),
+        gcTime: gcTime.medium, // 默认 30 分钟垃圾回收时间
+
+        // Refetch behavior
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: true,
+
+        // Don't throw errors by default, handle them in the UI
+        throwOnError: false,
+      },
+      mutations: {
+        retry: false,
+        onError: (error) => {
+          // Handle API errors with domain-specific messages
+          if (error && typeof error === 'object' && 'body' in error) {
+            const result = handleApiErrorResponse(
+              (error as { body: unknown }).body,
+            );
+            toast.error(result.message || 'Operation failed');
+            result.action?.();
+          } else if (error instanceof Error) {
+            toast.error(error.message);
+          } else {
+            toast.error('An unexpected error occurred');
+          }
+        },
+      },
+    },
+  });
+}
+
+// Singleton for SSR/SSG to prevent creating multiple clients
+let browserQueryClient: QueryClient | undefined = undefined;
+
+function getQueryClient() {
+  if (typeof window === 'undefined') {
+    // Server: always create a new QueryClient
+    return createQueryClient();
+  }
+  // Browser: reuse the same QueryClient
+  if (!browserQueryClient) {
+    browserQueryClient = createQueryClient();
+  }
+  return browserQueryClient;
+}
+
+interface QueryProviderProps {
+  children: ReactNode;
+}
+
+export function QueryProvider({ children }: QueryProviderProps) {
+  const [queryClient] = useState(() => getQueryClient());
+
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}
+
+// 导出缓存策略函数，供外部使用（如 prefetch）
+export { getStaleTimeByQueryKey, getGcTimeByQueryKey };

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

@@ -0,0 +1,26 @@
+'use client';
+
+/**
+ * Theme Provider - Next.js Theme Configuration
+ * 主题 Provider
+ */
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+import type { ReactNode } from 'react';
+
+interface ThemeProviderProps {
+  children: ReactNode;
+}
+
+export function ThemeProvider({ children }: ThemeProviderProps) {
+  return (
+    <NextThemesProvider
+      attribute="class"
+      defaultTheme="system"
+      enableSystem
+      disableTransitionOnChange
+    >
+      {children}
+    </NextThemesProvider>
+  );
+}

package/template/apps/web/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "@repo/config/typescript/nextjs.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "paths": {
+      "@/*": ["./*"],
+      "@repo/ui/*": ["../../packages/ui/src/*"],
+      "@repo/utils": ["../../packages/utils"],
+      "@repo/types": ["../../packages/types"],
+      "@repo/config": ["../../packages/config"],
+      "@repo/constants": ["../../packages/constants/src"],
+      "@repo/contracts": ["../../packages/contracts/src"],
+      "@repo/validators": ["../../packages/validators/src"]
+    },
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ]
+  },
+  "include": [
+    "next-env.d.ts",
+    "next.config.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

package/template/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "pardx-ai",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "turbo run dev",
+    "dev:web": "turbo run dev --filter=@repo/web",
+    "dev:api": "turbo run dev --filter=@repo/api",
+    "build": "turbo run build",
+    "build:web": "turbo run build --filter=@repo/web",
+    "build:api": "turbo run build --filter=@repo/api",
+    "lint": "turbo run lint",
+    "lint:web": "turbo run lint --filter=@repo/web",
+    "lint:api": "turbo run lint --filter=@repo/api",
+    "type-check": "turbo run type-check",
+    "test": "turbo run test",
+    "test:web": "turbo run test --filter=@repo/web",
+    "test:api": "turbo run test --filter=@repo/api",
+    "test:packages": "turbo run test --filter=@repo/validators --filter=@repo/utils --filter=@repo/contracts",
+    "test:cov": "turbo run test:cov",
+    "test:e2e": "turbo run test:e2e --filter=@repo/web",
+    "db:format": "turbo run db:format --filter=@repo/api",
+    "db:generate": "turbo run db:generate --filter=@repo/api",
+    "db:migrate:dev": "turbo run db:migrate:dev --filter=@repo/api",
+    "db:migrate:deploy": "turbo run db:migrate:deploy --filter=@repo/api",
+    "db:push": "turbo run db:push --filter=@repo/api",
+    "clean": "turbo run clean && rm -rf node_modules",
+    "generate:enums": "node scripts/generate-prisma-enums.js",
+    "generate:i18n-errors": "ts-node scripts/generate-i18n-errors.ts",
+    "export-scaffold": "node scripts/export-scaffold-for-create.js",
+    "create-scaffold": "node packages/create-pardx-scaffold/bin.js",
+    "prebuild": "pnpm generate:enums"
+  },
+  "devDependencies": {
+    "prettier": "^3.7.4",
+    "turbo": "^2.7.2",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "pnpm": ">=9.0.0"
+  },
+  "packageManager": "pnpm@10.27.0",
+  "pnpm": {
+    "overrides": {
+      "openai": "^6.0.0",
+      "glob": "^11.0.1",
+      "rimraf": "^6.0.1",
+      "rxjs": "7.8.1",
+      "punycode": "^2.3.1"
+    },
+    "peerDependencyRules": {
+      "allowedVersions": {
+        "openai": "6",
+        "rxjs": "7.8.1"
+      },
+      "ignoreMissing": [
+        "openai",
+        "@swc/core",
+        "@swc/wasm",
+        "@swc-node/register",
+        "node-notifier",
+        "ts-node",
+        "encoding",
+        "webpack-cli"
+      ]
+    },
+    "onlyBuiltDependencies": [
+      "@alicloud/openapi-core",
+      "@nestjs/core",
+      "@parcel/watcher",
+      "@prisma/engines",
+      "@scarf/scarf",
+      "@swc/core",
+      "bcrypt",
+      "core-js-pure",
+      "esbuild",
+      "msgpackr-extract",
+      "prisma",
+      "protobufjs",
+      "sharp",
+      "tos-crc64-js",
+      "unrs-resolver"
+    ]
+  },
+  "dependencies": {
+    "framer-motion": "^12.29.0",
+    "web-vitals": "^5.1.0",
+    "zod": "^3.25.76"
+  }
+}

package/template/packages/config/eslint/base.js

@@ -0,0 +1,32 @@
+import js from "@eslint/js"
+import eslintConfigPrettier from "eslint-config-prettier"
+import onlyWarn from "eslint-plugin-only-warn"
+import turboPlugin from "eslint-plugin-turbo"
+import tseslint from "typescript-eslint"
+
+/**
+ * A shared ESLint configuration for the repository.
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const config = [
+  js.configs.recommended,
+  eslintConfigPrettier,
+  ...tseslint.configs.recommended,
+  {
+    plugins: {
+      turbo: turboPlugin,
+    },
+    rules: {
+      "turbo/no-undeclared-env-vars": "warn",
+    },
+  },
+  {
+    plugins: {
+      onlyWarn,
+    },
+  },
+  {
+    ignores: ["dist/**", ".next/**", "out/**", "build/**", "node_modules/**"],
+  },
+]

package/template/packages/config/eslint/next.js

@@ -0,0 +1,134 @@
+import js from '@eslint/js';
+import pluginNext from '@next/eslint-plugin-next';
+import eslintConfigPrettier from 'eslint-config-prettier';
+import pluginPrettier from 'eslint-plugin-prettier/recommended';
+import pluginReact from 'eslint-plugin-react';
+import pluginReactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+import { config as baseConfig } from './base.js';
+
+/**
+ * A custom ESLint configuration for libraries that use Next.js.
+ *
+ * This configuration:
+ * - Enforces Prettier formatting rules (reads from .prettierrc)
+ * - Enforces TypeScript code quality rules based on code quality standards
+ * - Integrates Next.js and React best practices
+ *
+ * @type {import("eslint").Linter.Config}
+ * */
+export const nextJsConfig = [
+  ...baseConfig,
+  js.configs.recommended,
+  eslintConfigPrettier, // Disables conflicting ESLint rules
+  pluginPrettier, // Enforces Prettier formatting (reads from .prettierrc)
+  ...tseslint.configs.recommended,
+  {
+    ...pluginReact.configs.flat.recommended,
+    languageOptions: {
+      ...pluginReact.configs.flat.recommended.languageOptions,
+      globals: {
+        ...globals.serviceworker,
+      },
+    },
+  },
+  {
+    plugins: {
+      '@next/next': pluginNext,
+    },
+    rules: {
+      ...pluginNext.configs.recommended.rules,
+      ...pluginNext.configs['core-web-vitals'].rules,
+    },
+  },
+  {
+    plugins: {
+      'react-hooks': pluginReactHooks,
+    },
+    settings: { react: { version: 'detect' } },
+    rules: {
+      ...pluginReactHooks.configs.recommended.rules,
+      // React scope no longer necessary with new JSX transform.
+      'react/react-in-jsx-scope': 'off',
+      'react/prop-types': 'off',
+      'react/no-children-prop': 'off',
+    },
+  },
+  {
+    rules: {
+      // ============================================
+      // TypeScript 代码质量规范 (基于代码质量与类型定义规范.md)
+      // ============================================
+
+      // 1. 类型安全规则
+      // 禁止使用 any 类型（必要时使用 unknown）
+      '@typescript-eslint/no-explicit-any': [
+        'error',
+        {
+          fixToUnknown: true, // 自动修复为 unknown
+          ignoreRestArgs: false, // REST 参数也需要类型
+        },
+      ],
+
+      // 要求使用 type-only imports（import type）
+      '@typescript-eslint/consistent-type-imports': [
+        'error',
+        {
+          prefer: 'type-imports', // 优先使用 type-only imports
+          fixStyle: 'separate-type-imports', // 类型和值分开导入
+          disallowTypeAnnotations: false,
+        },
+      ],
+
+      // 禁止未使用的变量
+      '@typescript-eslint/no-unused-vars': [
+        'warn',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+
+      // 要求函数返回类型（可选，但推荐）
+      '@typescript-eslint/explicit-function-return-type': 'off', // 关闭，因为 TypeScript 可以推断
+
+      // 要求模块边界类型（可选，但推荐）
+      '@typescript-eslint/explicit-module-boundary-types': 'off', // 关闭，因为 TypeScript 可以推断
+
+      // 2. 类型定义规则
+      // 优先使用 interface 而不是 type（用于对象类型）
+      '@typescript-eslint/consistent-type-definitions': [
+        'warn',
+        'interface', // 优先使用 interface
+      ],
+
+      // 3. 命名规范
+      // 类型名称使用 PascalCase（由 TypeScript 编译器自动检查）
+      // Props 类型以 Props 结尾（由命名约定保证，无法自动检查）
+
+      // 4. 其他类型安全规则
+      // 禁止非空断言（使用类型守卫代替）
+      '@typescript-eslint/no-non-null-assertion': 'warn',
+
+      // 注意：以下规则需要类型信息（parserOptions.project），会显著降低性能
+      // 对于 Next.js 项目，不建议启用这些规则
+      // 如果确实需要，可以在 tsconfig.json 中配置 parserOptions.project
+      // '@typescript-eslint/prefer-nullish-coalescing': 'warn', // 需要类型信息
+      // '@typescript-eslint/prefer-optional-chain': 'warn', // 需要类型信息
+
+      // 禁止使用 @ts-ignore
+      '@typescript-eslint/ban-ts-comment': [
+        'error',
+        {
+          'ts-expect-error': 'allow-with-description',
+          'ts-ignore': true, // 禁止 ts-ignore
+          'ts-nocheck': true, // 禁止 ts-nocheck
+          'ts-check': false,
+        },
+      ],
+    },
+  },
+];