create-pardx-scaffold 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pardx-scaffold",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold a new project from PardxAI monorepo (git-tracked files)",
   "license": "MIT",
   "bin": "./cli.js",

package/template/.cursor/worktrees.json

@@ -0,0 +1,37 @@
+{
+  "setup-worktree": [
+    "npm install",
+    "npx prisma generate",
+    "npx prisma migrate dev",
+    "npx prisma migrate deploy",
+    "npx prisma migrate push",
+    "npx prisma migrate reset",
+    "npx prisma migrate resolve",
+    "npx prisma migrate status",
+    "npx prisma migrate up",
+    "npx prisma migrate down",
+    "pnpm dev",
+    "pnpm build",
+    "pnpm start",
+    "pnpm test",
+    "pnpm lint",
+    "pnpm format",
+    "pnpm type-check",
+    "pnpm clean",
+    "pnpm db:generate",
+    "pnpm db:migrate:dev",
+    "pnpm db:migrate:deploy",
+    "pnpm db:push",
+    "pnpm db:format",
+    "pnpm db:migrate:reset",
+    "pnpm db:migrate:resolve",
+    "pnpm db:migrate:status",
+    "pnpm db:migrate:up",
+    "pnpm db:migrate:down",
+    "pnpm db:migrate:latest",
+    "pnpm db:migrate:rollback",
+    "pnpm db:migrate:status",
+    "pnpm db:migrate:up",
+    "pnpm db:migrate:down"
+  ]
+}

package/template/.dockerignore

@@ -0,0 +1,49 @@
+# 依赖目录
+node_modules
+**/node_modules
+
+# 构建输出
+dist
+**/dist
+.next
+**/.next
+build
+**/build
+
+# 日志
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# 测试
+coverage
+**/.coverage
+
+# 环境变量
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+*~
+
+# Git
+.git
+.gitignore
+
+# 其他
+.DS_Store
+*.pem
+**/.env.production
+
+
+
+
+
+
+

package/template/.mcp.json

@@ -0,0 +1,26 @@
+{
+  "mcpServers": {
+    "CopilotKit MCP": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "https://mcp.copilotkit.ai"
+      ]
+    },
+    "fs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "/Users/techwu/Documents/codes/xica.ai/full.xica.ai"
+      ]
+    },
+    "next-devtools": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "next-devtools-mcp@latest"
+      ]
+    }
+  }
+}

package/template/.nvmrc

@@ -0,0 +1 @@
+22

package/template/CLAUDE.md

@@ -133,6 +133,7 @@ pardx-ai/
 - **State Management**: React Query (@tanstack/react-query)
 - **Styling**: Tailwind CSS 4 + class-variance-authority
 - **API Client**: ts-rest + React Query
+- **Validation**: Zod 4 (see Zod 4 Usage Guidelines below)
 
 **Backend:**
 - **Framework**: NestJS 11 with Fastify
@@ -141,6 +142,11 @@ pardx-ai/
 - **Queue**: RabbitMQ + BullMQ
 - **Auth**: Passport (JWT, OAuth2)
 - **API Contract**: ts-rest
+- **Validation**: Zod 4 (see Zod 4 Usage Guidelines below)
+
+**Shared:**
+- **Validation Library**: Zod 4.x (NOT Zod 3.x)
+- **API Contract**: ts-rest 3.53.x (supports Zod 4)
 
 ### Build Configuration
 
@@ -507,6 +513,85 @@ Code shared between frontend and backend goes in `packages/`:
 
 Next.js 16 App Router is used. Client components must include `'use client'` directive.
 
+## 🔷 Zod 4 Usage Guidelines
+
+**IMPORTANT: This project uses Zod 4.x (NOT Zod 3.x). All code MUST follow Zod 4 patterns.**
+
+### Import Statement
+
+```typescript
+// ✅ Correct: Import from 'zod' (uses Zod 4 classic mode)
+import { z } from 'zod';
+
+// ❌ Wrong: Do NOT use zod/v3 compatibility layer
+import { z } from 'zod/v3';
+```
+
+### Key Differences from Zod 3
+
+1. **Object Schema Definition**
+   ```typescript
+   // Zod 4 uses $strip instead of strip() for object mode
+   const schema = z.object({
+     name: z.string(),
+     age: z.number(),
+   }); // Default is $strip mode
+   ```
+
+2. **Error Handling**
+   ```typescript
+   // Zod 4 error structure
+   const result = schema.safeParse(data);
+   if (!result.success) {
+     // Use result.error.issues for error details
+     console.log(result.error.issues);
+   }
+   ```
+
+3. **Type Inference**
+   ```typescript
+   // Both work in Zod 4
+   type User = z.infer<typeof UserSchema>;
+   type User = z.output<typeof UserSchema>;
+   ```
+
+### ts-rest Compatibility
+
+This project uses **ts-rest 3.53.x** which supports Zod 4. The contract definitions work the same way:
+
+```typescript
+import { initContract } from '@ts-rest/core';
+import { z } from 'zod';
+
+const c = initContract();
+
+export const userContract = c.router({
+  getUser: {
+    method: 'GET',
+    path: '/user/:id',
+    pathParams: z.object({
+      id: z.string().uuid(),
+    }),
+    responses: {
+      200: z.object({
+        id: z.string(),
+        name: z.string(),
+      }),
+    },
+  },
+});
+```
+
+### Migration Notes
+
+If you encounter code using Zod 3 patterns, update to Zod 4:
+
+| Zod 3 | Zod 4 |
+|-------|-------|
+| `z.object({}).strip()` | `z.object({})` (default is strip) |
+| `z.object({}).passthrough()` | `z.looseObject({})` or `z.object({}).passthrough()` |
+| `z.object({}).strict()` | `z.strictObject({})` or `z.object({}).strict()` |
+
 ## 📋 Code Quality Standards
 
 All code MUST follow these quality standards:

package/template/apps/api/libs/domain/services/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Domain Services
+ *
+ * 业务服务层 - 包含依赖 domain 层的业务服务
+ * 这些服务依赖 domain/db 或其他 domain 模块，因此不能放在 infra 层
+ */
+export * from './ip-info';

package/template/apps/api/libs/{infra/shared-services → domain/services}/ip-info/ip-info.module.ts

@@ -2,6 +2,8 @@
  * IP Info Service Module
  *
  * 职责：提供 IP 信息查询服务
+ *
+ * 注意：此模块依赖 CountryCodeModule (domain 层)，因此放置在 domain/services 下
  */
 import { Module } from '@nestjs/common';
 import { HttpModule } from '@nestjs/axios';

package/template/apps/api/libs/{infra/shared-services → domain/services}/ip-info/ip-info.service.ts

@@ -6,6 +6,8 @@
  * - 国家/地区查询
  * - 大洲查询 (依赖 CountryCodeService)
  * - 时区查询
+ *
+ * 注意：此服务依赖 CountryCodeService (domain 层)，因此放置在 domain/services 下
  */
 import { Injectable, Inject } from '@nestjs/common';
 import { HttpService } from '@nestjs/axios';

package/template/apps/api/libs/infra/clients/internal/file-storage/dto/file.dto.ts

@@ -45,7 +45,7 @@ export const GetObjectOptionsSchema = z.object({
 // Presigned Put URL Object Schema
 export const PresignedPutUrlObjectSchema = z.object({
   url: z.string(),
-  headers: z.record(z.string()),
+  headers: z.record(z.string(), z.string()),
 });
 
 // Listed Object Entry Schema

package/template/apps/api/libs/infra/shared-services/email/email.module.ts

@@ -9,7 +9,6 @@ import { HttpModule } from '@nestjs/axios';
 import { RedisModule } from '@app/redis';
 import { RabbitmqModule } from '@app/rabbitmq';
 import { VerifyModule } from '@app/clients/internal/verify';
-import { SystemTaskQueueModule } from '@app/db';
 import { EmailService } from './email.service';
 
 @Module({
@@ -19,7 +18,6 @@ import { EmailService } from './email.service';
     RedisModule,
     RabbitmqModule,
     VerifyModule,
-    SystemTaskQueueModule,
   ],
   providers: [EmailService],
   exports: [EmailService],

package/template/apps/api/libs/infra/shared-services/file-storage/bucket-resolver.ts

@@ -16,7 +16,7 @@ import { Logger } from 'winston';
 import { FileBucketVendor } from '@prisma/client';
 
 import { PardxUploader } from '@app/clients/internal/file-storage';
-import { IpInfoService } from '@app/shared-services/ip-info';
+import { IpInfoService } from '@app/services/ip-info';
 import { AppConfig } from '@/config/validation';
 import arrayUtil from '@/utils/array.util';
 import enviromentUtil from '@/utils/enviroment.util';

package/template/apps/api/libs/infra/shared-services/file-storage/file-storage.module.ts

@@ -12,7 +12,7 @@
 import { Module } from '@nestjs/common';
 import { ConfigModule } from '@nestjs/config';
 import { HttpModule } from '@nestjs/axios';
-import { IpInfoServiceModule } from '@app/shared-services/ip-info';
+import { IpInfoServiceModule } from '@app/services/ip-info';
 import { RedisModule } from '@app/redis';
 import { FileStorageService } from './file-storage.service';
 import { FileStorageClientFactory } from './file-storage.factory';

package/template/apps/api/libs/infra/shared-services/sms/sms.module.ts

@@ -9,7 +9,6 @@ import { HttpModule } from '@nestjs/axios';
 import { RedisModule } from '@app/redis';
 import { RabbitmqModule } from '@app/rabbitmq';
 import { VerifyModule } from '@app/clients/internal/verify';
-import { SystemTaskQueueModule } from '@app/db';
 import { SmsService } from './sms.service';
 
 @Module({
@@ -19,7 +18,6 @@ import { SmsService } from './sms.service';
     RedisModule,
     RabbitmqModule,
     VerifyModule,
-    SystemTaskQueueModule,
   ],
   providers: [SmsService],
   exports: [SmsService],

package/template/apps/api/package.json

@@ -61,7 +61,7 @@
         "glob": "^11.0.1",
         "jest": "^29.7.0",
         "prettier": "^3.3.3",
-        "prisma": "7.2.0",
+        "prisma": "7.3.0",
         "rimraf": "^6.0.1",
         "source-map-support": "^0.5.21",
         "supertest": "^7.1.1",
@@ -70,7 +70,7 @@
         "ts-node": "^10.9.2",
         "tsconfig-paths": "^4.2.0",
         "tsconfig-paths-webpack-plugin": "^4.2.0",
-        "turbo": "^2.7.1",
+        "turbo": "^2.8.0",
         "typescript": "^5.4.5",
         "webpack": "^5.98.0",
         "webpack-cli": "^6.0.1",
@@ -82,8 +82,8 @@
         "@alicloud/nls-filetrans-2018-08-17": "^1.0.0",
         "@alicloud/openapi-client": "^0.4.15",
         "@alicloud/pop-core": "^1.8.0",
-        "@aws-sdk/client-s3": "^3.826.0",
-        "@aws-sdk/s3-request-presigner": "^3.826.0",
+        "@aws-sdk/client-s3": "^3.978.0",
+        "@aws-sdk/s3-request-presigner": "^3.978.0",
         "@fastify/compress": "^8.0.1",
         "@fastify/cookie": "^11.0.2",
         "@fastify/helmet": "^13.0.1",
@@ -107,15 +107,15 @@
         "@nestjs/schedule": "^6.1.0",
         "@nestjs/swagger": "^11.2.3",
         "@nestjs/websockets": "^11.1.10",
-        "@prisma/adapter-pg": "^7.2.0",
-        "@prisma/client": "7.2.0",
-        "@prisma/extension-accelerate": "^2.0.1",
+        "@prisma/adapter-pg": "^7.3.0",
+        "@prisma/client": "7.3.0",
+        "@prisma/extension-accelerate": "^3.0.1",
         "@repo/constants": "workspace:*",
         "@repo/contracts": "workspace:*",
         "@repo/utils": "workspace:*",
         "@repo/validators": "workspace:*",
-        "@ts-rest/core": "^3.51.0",
-        "@ts-rest/nest": "^3.51.0",
+        "@ts-rest/core": "^3.53.0-rc.1",
+        "@ts-rest/nest": "^3.53.0-rc.1",
         "@volcengine/openapi": "^1.32.0",
         "@volcengine/tos-sdk": "^2.7.6",
         "@willsoto/nestjs-prometheus": "^6.0.2",
@@ -126,7 +126,7 @@
         "axios": "^1.7.2",
         "bcrypt": "^6.0.0",
         "bull": "^4.16.5",
-        "bullmq": "^5.56.9",
+        "bullmq": "^5.67.2",
         "class-transformer": "^0.5.1",
         "class-validator": "^0.14.1",
         "cls-hooked": "^4.2.2",
@@ -134,8 +134,8 @@
         "dotenv-expand": "^12.0.3",
         "fastify": "^5.2.0",
         "fastify-sse-v2": "^4.2.1",
-        "google-auth-library": "^9.11.0",
-        "ioredis": "5.6.1",
+        "google-auth-library": "^10.5.0",
+        "ioredis": "5.9.2",
         "js-yaml": "^4.1.0",
         "lodash": "^4.17.21",
         "moment-timezone": "^0.6.0",
@@ -147,7 +147,7 @@
         "nestjs-i18n": "^10.4.5",
         "nodemailer": "^7.0.3",
         "nodemailer-sendcloud-transport": "^0.0.2",
-        "openai": "^6.15.0",
+        "openai": "^6.17.0",
         "passport": "^0.7.0",
         "passport-google-oauth20": "^2.0.0",
         "passport-jwt": "^4.0.1",
@@ -164,11 +164,11 @@
         "socket.io": "^4.8.1",
         "tencentcloud-sdk-nodejs-sms": "^4.0.859",
         "uniqid": "^5.4.0",
-        "unleash-client": "^6.9.0",
+        "unleash-client": "^6.9.5",
         "uuid": "^11.1.0",
         "winston": "^3.13.0",
         "winston-daily-rotate-file": "^5.0.0",
         "ws": "^8.18.3",
-        "zod": "^3.23.0"
+        "zod": "^4.3.6"
     }
 }

package/template/apps/api/prisma/migrations/migration_lock.toml

@@ -0,0 +1,3 @@
+# Please do not edit this file manually
+# It should be added in your version-control system (e.g., Git)
+provider = "postgresql"

package/template/apps/api/src/app.module.ts

@@ -32,7 +32,7 @@ import type { AppConfig, ZoneConfig } from '@/config/validation';
 
 /** request middleware */
 import RequestMiddleware from '@/common/middleware/request.middleware';
-import { IpInfoServiceModule } from '@app/shared-services/ip-info';
+import { IpInfoServiceModule } from '@app/services/ip-info';
 import { ScheduleModule } from '@nestjs/schedule';
 import { RedisModule } from '@app/redis';
 import { CacheDecoratorModule } from '@/common/decorators/cache/cache.module';

package/template/apps/web/.env.example

@@ -1,5 +1,7 @@
-# API Configuration
-NEXT_PUBLIC_API_BASE_URL=http://localhost:3100/api
+# API 配置
+NEXT_PUBLIC_API_BASE_URL=http://localhost:13100/api
 
-# Feature Flags
-NEXT_PUBLIC_ENABLE_ANALYTICS=false
+NEXT_PUBLIC_BRAND_NAME='Pardx.ai'
+NEXT_PUBLIC_BRAND_LOGO='/logo.svg'
+NEXT_PUBLIC_BRAND_TITLE=PardxAI - Multi-Agent Content Creation & Knowledge Management Platform
+NEXT_PUBLIC_BRAND_DESCRIPTION=PardxAI is an AI-powered multi-agent platform for content creation, knowledge management, and intelligent operations. Features include AI writing, evolutionary knowledge base, smart recommendations, AI recruitment agents, and meeting intelligence.

package/template/apps/web/components/error-boundary.tsx

@@ -0,0 +1,166 @@
+'use client';
+
+import { Component, type ReactNode, type ErrorInfo } from 'react';
+
+/**
+ * Error Boundary Props
+ */
+interface ErrorBoundaryProps {
+  children: ReactNode;
+  /** 自定义错误回退 UI */
+  fallback?: ReactNode;
+  /** 错误回调函数 */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+  /** 是否显示重试按钮 */
+  showRetry?: boolean;
+}
+
+/**
+ * Error Boundary State
+ */
+interface ErrorBoundaryState {
+  hasError: boolean;
+  error?: Error;
+  errorInfo?: ErrorInfo;
+}
+
+/**
+ * 默认错误回退 UI
+ */
+function DefaultErrorFallback({
+  error,
+  onRetry,
+  showRetry = true,
+}: {
+  error?: Error;
+  onRetry?: () => void;
+  showRetry?: boolean;
+}) {
+  return (
+    <div className="flex min-h-[200px] flex-col items-center justify-center p-8 text-center">
+      <div className="mb-4 text-6xl">😵</div>
+      <h2 className="mb-2 text-xl font-semibold text-gray-900 dark:text-gray-100">
+        出错了
+      </h2>
+      <p className="mb-4 text-gray-600 dark:text-gray-400">
+        {error?.message || '页面发生了意外错误'}
+      </p>
+      {showRetry && onRetry && (
+        <button
+          onClick={onRetry}
+          className="rounded-md bg-blue-600 px-4 py-2 text-white transition-colors hover:bg-blue-700"
+        >
+          重试
+        </button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * React Error Boundary 组件
+ *
+ * 用于捕获子组件树中的 JavaScript 错误，记录错误并显示回退 UI
+ *
+ * @example
+ * ```tsx
+ * <ErrorBoundary fallback={<CustomError />}>
+ *   <MyComponent />
+ * </ErrorBoundary>
+ * ```
+ */
+export class ErrorBoundary extends Component<
+  ErrorBoundaryProps,
+  ErrorBoundaryState
+> {
+  constructor(props: ErrorBoundaryProps) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError(error: Error): ErrorBoundaryState {
+    return { hasError: true, error };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // 记录错误信息
+    console.error('ErrorBoundary caught an error:', error, errorInfo);
+
+    // 更新状态以包含错误信息
+    this.setState({ errorInfo });
+
+    // 调用错误回调
+    this.props.onError?.(error, errorInfo);
+
+    // 在生产环境中，可以发送到错误追踪服务
+    if (process.env.NODE_ENV === 'production') {
+      // TODO: 发送到错误追踪服务 (如 Sentry)
+    }
+  }
+
+  handleRetry = () => {
+    this.setState({ hasError: false, error: undefined, errorInfo: undefined });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      // 如果提供了自定义 fallback，使用它
+      if (this.props.fallback) {
+        return this.props.fallback;
+      }
+
+      // 否则使用默认错误 UI
+      return (
+        <DefaultErrorFallback
+          error={this.state.error}
+          onRetry={this.handleRetry}
+          showRetry={this.props.showRetry}
+        />
+      );
+    }
+
+    return this.props.children;
+  }
+}
+
+/**
+ * 页面级 Error Boundary
+ * 用于包裹整个页面，提供更友好的错误提示
+ */
+export function PageErrorBoundary({ children }: { children: ReactNode }) {
+  return (
+    <ErrorBoundary
+      showRetry
+      onError={(error, errorInfo) => {
+        // 页面级错误可以记录更多上下文
+        console.error('Page error:', {
+          error: error.message,
+          stack: error.stack,
+          componentStack: errorInfo.componentStack,
+        });
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+/**
+ * 组件级 Error Boundary
+ * 用于包裹单个组件，错误不会影响其他组件
+ */
+export function ComponentErrorBoundary({
+  children,
+  fallback,
+}: {
+  children: ReactNode;
+  fallback?: ReactNode;
+}) {
+  return (
+    <ErrorBoundary fallback={fallback} showRetry={false}>
+      {children}
+    </ErrorBoundary>
+  );
+}
+
+export default ErrorBoundary;

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

@@ -0,0 +1,10 @@
+/**
+ * Shared Components
+ *
+ * 通用组件导出
+ */
+export {
+  ErrorBoundary,
+  PageErrorBoundary,
+  ComponentErrorBoundary,
+} from './error-boundary';

package/template/apps/web/components.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "../../packages/ui/src/styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "hooks": "@/hooks",
+    "lib": "@/lib",
+    "utils": "@repo/ui/lib/utils",
+    "ui": "@repo/ui/components"
+  }
+}