create-pardx-scaffold 0.1.10 → 0.1.11

package/template/apps/web/components/state-components.tsx

@@ -0,0 +1,214 @@
+'use client';
+
+/**
+ * 公共状态组件
+ * 用于统一页面加载、错误、空状态的展示
+ */
+
+import { Loader2 } from 'lucide-react';
+import { Button } from '@repo/ui';
+import type { ReactNode } from 'react';
+import { useTranslations } from 'next-intl';
+
+// ============================================================================
+// Loading Spinner
+// ============================================================================
+
+interface LoadingSpinnerProps {
+  /** 自定义类名 */
+  className?: string;
+  /** 图标大小 */
+  size?: 'sm' | 'md' | 'lg';
+  /** 最小高度 */
+  minHeight?: string | number;
+}
+
+const sizeMap = {
+  sm: 'size-4',
+  md: 'size-8',
+  lg: 'size-12',
+};
+
+/**
+ * 统一的加载状态组件
+ */
+export function LoadingSpinner({
+  className,
+  size = 'md',
+  minHeight = 400,
+}: LoadingSpinnerProps) {
+  const minHeightStyle =
+    typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={`flex items-center justify-center ${className ?? ''}`}
+      style={{ minHeight: minHeightStyle }}
+    >
+      <Loader2
+        className={`${sizeMap[size]} animate-spin text-primary`}
+      />
+    </div>
+  );
+}
+
+// ============================================================================
+// Error State
+// ============================================================================
+
+interface ErrorStateProps {
+  /** 错误消息 */
+  message?: string;
+  /** 重试回调 */
+  onRetry?: () => void;
+  /** 重试按钮文字 */
+  retryText?: string;
+  /** 自定义类名 */
+  className?: string;
+  /** 最小高度 */
+  minHeight?: string | number;
+}
+
+/**
+ * 统一的错误状态组件
+ */
+export function ErrorState({
+  message,
+  onRetry,
+  retryText,
+  className,
+  minHeight = 400,
+}: ErrorStateProps) {
+  const t = useTranslations('common');
+  const displayMessage = message ?? t('messages.loadFailed');
+  const displayRetry = retryText ?? t('actions.retry');
+  const minHeightStyle =
+    typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={`flex flex-col items-center justify-center gap-4 ${className ?? ''}`}
+      style={{ minHeight: minHeightStyle }}
+    >
+      <p className="text-destructive">{displayMessage}</p>
+      {onRetry && (
+        <Button
+          variant="outline"
+          onClick={onRetry}
+          className="rounded-lg"
+        >
+          {displayRetry}
+        </Button>
+      )}
+    </div>
+  );
+}
+
+// ============================================================================
+// Empty State
+// ============================================================================
+
+interface EmptyStateProps {
+  /** 标题 */
+  title?: string;
+  /** 描述 */
+  description?: string;
+  /** 图标 */
+  icon?: ReactNode;
+  /** 操作按钮 */
+  action?: ReactNode;
+  /** 自定义类名 */
+  className?: string;
+  /** 最小高度 */
+  minHeight?: string | number;
+}
+
+/**
+ * 统一的空状态组件
+ */
+export function EmptyState({
+  title,
+  description,
+  icon,
+  action,
+  className,
+  minHeight = 200,
+}: EmptyStateProps) {
+  const t = useTranslations('common');
+  const displayTitle = title ?? t('messages.noData');
+  const minHeightStyle =
+    typeof minHeight === 'number' ? `${minHeight}px` : minHeight;
+
+  return (
+    <div
+      className={`flex flex-col items-center justify-center gap-4 ${className ?? ''}`}
+      style={{ minHeight: minHeightStyle }}
+    >
+      {icon}
+      <div className="text-center">
+        <p className="text-muted-foreground">{displayTitle}</p>
+        {description && (
+          <p className="text-sm text-muted-foreground/60 mt-1">{description}</p>
+        )}
+      </div>
+      {action}
+    </div>
+  );
+}
+
+// ============================================================================
+// Page Loading (Full Page)
+// ============================================================================
+
+interface PageLoadingProps {
+  /** 自定义类名 */
+  className?: string;
+}
+
+/**
+ * 全页面加载状态
+ */
+export function PageLoading({ className }: PageLoadingProps) {
+  return (
+    <div
+      className={`p-6 flex items-center justify-center min-h-[400px] ${className ?? ''}`}
+    >
+      <Loader2 className="size-8 animate-spin text-primary" />
+    </div>
+  );
+}
+
+// ============================================================================
+// Page Error (Full Page with Shell)
+// ============================================================================
+
+interface PageErrorProps {
+  /** 错误消息 */
+  message?: string;
+  /** 重试回调 */
+  onRetry?: () => void;
+}
+
+/**
+ * 全页面错误状态
+ */
+export function PageError({ message, onRetry }: PageErrorProps) {
+  const t = useTranslations('common');
+  const displayMessage = message ?? t('messages.loadFailed');
+  const retryLabel = t('actions.retry');
+
+  return (
+    <div className="p-6 flex flex-col items-center justify-center min-h-[400px] gap-4">
+      <p className="text-destructive">{displayMessage}</p>
+      {onRetry && (
+        <Button
+          variant="outline"
+          onClick={onRetry}
+          className="rounded-lg"
+        >
+          {retryLabel}
+        </Button>
+      )}
+    </div>
+  );
+}

package/template/apps/web/config.ts

@@ -3,6 +3,24 @@
 // 在 .env.local 文件中设置以下环境变量：
 // - NEXT_PUBLIC_SERVER_BASE_URL: 登录、上传文件、测评等接口的基础地址
 
+/**
+ * 获取 Agno API 基础地址（用于智能体相关接口）
+ */
+const getAgnoApiBaseUrl = (): string => {
+  const baseUrl = process.env.NEXT_AGNO_API_BASE_URL;
+  if (!baseUrl) {
+    const defaultUrl = 'http://127.0.0.1:8000/api';
+    if (
+      process.env.NODE_ENV === 'development' ||
+      process.env.NEXT_PHASE === 'phase-production-build'
+    ) {
+      return defaultUrl;
+    }
+    return defaultUrl;
+  }
+  return baseUrl;
+};
+
 /**
  * 获取 Server 基础地址（用于登录、上传文件、测评等）
  */
@@ -80,8 +98,10 @@ export const API_CONFIG = {
   // API 基础地址（用于登录、上传文件、测评等）
   baseUrl: getServerBaseUrl() + '/api',
   apiHealthUrl: getServerBaseUrl() + '/health',
+  // Agno API 基础地址（用于智能体相关接口）
+  agnoApiBaseUrl: getAgnoApiBaseUrl(),
 
-  // API 端点路径 这些断点是不适用ts-rest-api的，用于登录和校验权限的断点，如果未来需要使用ts-rest-api，则将这些断点迁移到ts-rest-api中
+  // API 端点路径 这些断点是不适用ts-rest-api的，用于登录和校验权限的断点，如果未来需要使用ts-rest-api，则将这些端点迁移到ts-rest-api中
   endpoints: {
     // 登录端点
     login: '/sign/in/mobile/password',
@@ -113,4 +133,4 @@ export const BRAND_CONFIG = {
   logo: getBrandLogo(),
   title: getBrandTitle(),
   description: getBrandDescription(),
-};
+};

package/template/apps/web/lib/api/cache-config.ts

@@ -234,3 +234,35 @@ export function getSearchQueryOptions() {
     refetchOnWindowFocus: false,
   };
 }
+
+// ============================================================================
+// 安全查询辅助函数
+// ============================================================================
+
+/**
+ * 获取详情查询的安全配置
+ * 防止在 ID 为空时发起请求
+ */
+export function getSafeDetailQueryOptions(id: string | undefined) {
+  return {
+    staleTime: cacheTime.medium,
+    gcTime: gcTime.medium,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+    enabled: Boolean(id), // 关键：ID 不存在时不发起请求
+  };
+}
+
+/**
+ * 获取条件查询的安全配置
+ * 当条件不满足时不发起请求
+ */
+export function getConditionalQueryOptions(condition: boolean) {
+  return {
+    staleTime: cacheTime.medium,
+    gcTime: gcTime.medium,
+    refetchOnWindowFocus: false,
+    refetchOnMount: false,
+    enabled: condition, // 条件不满足时不发起请求
+  };
+}

package/template/apps/web/lib/api/contracts/client.ts

@@ -10,12 +10,14 @@ import {
   settingContract,
   signContract,
   smsContract,
+  systemContract,
+  taskContract,
   uploaderContract,
   userContract,
 } from '@repo/contracts';
 import { getHeaders } from '@repo/utils/headers';
 import { API_VERSION_HEADER, APP_BUILD_HEADER } from '@repo/constants';
-import { API_CONFIG } from '../../config';
+import { API_CONFIG } from '@/config';
 import { getToken, ensureValidToken, clearToken } from '../../api';
 import { APP_VERSION } from '@/lib/version';
 import {
@@ -311,6 +313,21 @@ export const uploaderClient = initClient(uploaderContract, clientOptions);
  */
 export const analyticsClient = initClient(analyticsContract, clientOptions);
 
+/**
+ * Message API - Direct client
+ */
+export const messageClient = initClient(messageContract, clientOptions);
+
+/**
+ * Task API - Direct client
+ */
+export const taskClient = initClient(taskContract, clientOptions);
+
+/**
+ * System API - Direct client
+ */
+export const systemClient = initClient(systemContract, clientOptions);
+
 // ============================================================================
 // React Query Clients (for hooks)
 // ============================================================================
@@ -335,6 +352,21 @@ export const settingApi = initQueryClient(settingContract, clientOptions);
  */
 export const analyticsApi = initQueryClient(analyticsContract, clientOptions);
 
+/**
+ * User API - React Query hooks
+ */
+export const userApi = initQueryClient(userContract, clientOptions);
+
+/**
+ * Task API - React Query hooks
+ */
+export const taskApi = initQueryClient(taskContract, clientOptions);
+
+/**
+ * System API - React Query hooks
+ */
+export const systemApi = initQueryClient(systemContract, clientOptions);
+
 // ============================================================================
 // Generic ts-rest Client (for custom contracts)
 // ============================================================================
@@ -347,6 +379,9 @@ export const analyticsApi = initQueryClient(analyticsContract, clientOptions);
  * Note: For imperative calls (non-hook usage), use the direct clients:
  * - analyticsClient (for Analytics)
  * - messageClient (for Message)
+ * - userClient (for User)
+ * - taskClient (for Task)
+ * - systemClient (for System)
  * - etc.
  */
 export const tsRestClient = {
@@ -356,6 +391,13 @@ export const tsRestClient = {
   message: messageApi,
   setting: settingApi,
   download: downloadApi,
+  user: userApi,
+  task: taskApi,
+  system: systemApi,
   // Direct clients (for imperative calls)
   analyticsClient,
+  messageClient,
+  userClient,
+  taskClient,
+  systemClient,
 };

package/template/apps/web/lib/api/contracts/hooks/analytics.ts

@@ -0,0 +1,32 @@
+'use client';
+
+import { tsRestClient, analyticsClient } from '../client';
+
+/**
+ * Analytics Query Keys
+ * Used for React Query cache management
+ */
+export const analyticsKeys = {
+  all: ['analytics'] as const,
+  track: () => [...analyticsKeys.all, 'track'] as const,
+  trackBatch: () => [...analyticsKeys.all, 'trackBatch'] as const,
+};
+
+// ============================================================================
+// Analytics Mutation Hooks
+// Analytics events are typically sent via mutations, not queries
+// ============================================================================
+
+/**
+ * Track a single analytics event
+ */
+export function useTrackEvent() {
+  return tsRestClient.analytics.track.useMutation();
+}
+
+/**
+ * Track multiple analytics events in batch
+ */
+export function useTrackEventBatch() {
+  return tsRestClient.analytics.trackBatch.useMutation();
+}

package/template/apps/web/lib/api/contracts/hooks/index.ts

@@ -1,6 +1,45 @@
 'use client';
 
-// Notification hooks
+// User hooks
+export {
+  userKeys,
+  useUserInfo,
+  useUserCheck,
+  useUserContact,
+} from './user';
+
+// Message hooks
+export {
+  messageKeys,
+  useMessages,
+  useUnreadMessageCount,
+  useSetMessagesRead,
+} from './message';
+
+// Analytics hooks
+export {
+  analyticsKeys,
+  useTrackEvent,
+  useTrackEventBatch,
+} from './analytics';
+
+// Task hooks
+export {
+  taskKeys,
+  useCheckTask,
+  useTaskList,
+  useCheckTasks,
+} from './task';
+
+// System hooks
+export {
+  systemKeys,
+  usePermissionConfig,
+  useServiceReady,
+  useServiceHealth,
+} from './system';
+
+// Notification hooks (placeholder)
 export {
   notificationKeys,
   useNotifications,
@@ -19,4 +58,4 @@ export {
   useSetPassword,
   useBindEmail,
   useBindPhone,
-} from './setting';
+} from './setting';

package/template/apps/web/lib/api/contracts/hooks/message.ts

@@ -0,0 +1,60 @@
+'use client';
+
+import { useQueryClient } from '@tanstack/react-query';
+import { tsRestClient, messageClient } from '../client';
+import type { z } from 'zod';
+import type { MessageListQuerySchema } from '@repo/contracts';
+
+type MessageListQuery = z.input<typeof MessageListQuerySchema>;
+
+/**
+ * Message Query Keys
+ * Used for React Query cache management
+ */
+export const messageKeys = {
+  all: ['messages'] as const,
+  list: (query?: MessageListQuery) => [...messageKeys.all, 'list', query] as const,
+  unreadCount: () => [...messageKeys.all, 'unreadCount'] as const,
+};
+
+// ============================================================================
+// Message Query Hooks
+// ============================================================================
+
+/**
+ * Get list of messages
+ * @param query - Query parameters (page, limit, type, isRead)
+ */
+export function useMessages(query?: MessageListQuery) {
+  const queryKey = messageKeys.list(query);
+  const { page = 1, limit = 20, ...rest } = query ?? {};
+  return tsRestClient.message.list.useQuery(
+    queryKey,
+    { query: { page, limit, ...rest } },
+    { queryKey },
+  );
+}
+
+/**
+ * Get unread message count
+ */
+export function useUnreadMessageCount() {
+  const queryKey = messageKeys.unreadCount();
+  return tsRestClient.message.getUnreadCount.useQuery(queryKey, {});
+}
+
+// ============================================================================
+// Message Mutation Hooks
+// ============================================================================
+
+/**
+ * Set messages as read
+ */
+export function useSetMessagesRead() {
+  const queryClient = useQueryClient();
+  return tsRestClient.message.setRead.useMutation({
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: messageKeys.all });
+    },
+  });
+}

package/template/apps/web/lib/api/contracts/hooks/system.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { tsRestClient, systemClient } from '../client';
+
+/**
+ * System Query Keys
+ * Used for React Query cache management
+ */
+export const systemKeys = {
+  all: ['system'] as const,
+  permissionConfig: () => [...systemKeys.all, 'permissionConfig'] as const,
+  ready: () => [...systemKeys.all, 'ready'] as const,
+  health: () => [...systemKeys.all, 'health'] as const,
+};
+
+// ============================================================================
+// System Query Hooks
+// ============================================================================
+
+/**
+ * Get permission configuration
+ */
+export function usePermissionConfig() {
+  return tsRestClient.system.getPermissionConfig.useQuery(
+    systemKeys.permissionConfig(),
+    {},
+  );
+}
+
+/**
+ * Check if service is ready
+ */
+export function useServiceReady() {
+  return tsRestClient.system.checkServiceReady.useQuery(systemKeys.ready(), {});
+}
+
+/**
+ * Check service health status
+ */
+export function useServiceHealth() {
+  return tsRestClient.system.checkHealth.useQuery(systemKeys.health(), {});
+}

package/template/apps/web/lib/api/contracts/hooks/task.ts

@@ -0,0 +1,54 @@
+'use client';
+
+import { useQueryClient } from '@tanstack/react-query';
+import { tsRestClient, taskClient } from '../client';
+
+/**
+ * Task Query Keys
+ * Used for React Query cache management
+ */
+export const taskKeys = {
+  all: ['tasks'] as const,
+  check: (taskId: string) => [...taskKeys.all, 'check', taskId] as const,
+  list: () => [...taskKeys.all, 'list'] as const,
+};
+
+// ============================================================================
+// Task Query Hooks
+// ============================================================================
+
+/**
+ * Check if a task is completed
+ * @param taskId - Task UUID
+ */
+export function useCheckTask(taskId: string) {
+  const queryKey = taskKeys.check(taskId);
+  return tsRestClient.task.checkTask.useQuery(
+    queryKey,
+    { params: { taskId } },
+    { queryKey, enabled: Boolean(taskId) },
+  );
+}
+
+/**
+ * Get user's task list
+ */
+export function useTaskList() {
+  return tsRestClient.task.getTaskList.useQuery(taskKeys.list(), {});
+}
+
+// ============================================================================
+// Task Mutation Hooks
+// ============================================================================
+
+/**
+ * Check multiple tasks completion status
+ */
+export function useCheckTasks() {
+  const queryClient = useQueryClient();
+  return tsRestClient.task.checkTasks.useMutation({
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: taskKeys.all });
+    },
+  });
+}

package/template/apps/web/lib/api/contracts/hooks/user.ts

@@ -0,0 +1,45 @@
+'use client';
+
+import { tsRestClient, userClient } from '../client';
+
+/**
+ * User Query Keys
+ * Used for React Query cache management
+ */
+export const userKeys = {
+  all: ['user'] as const,
+  info: () => [...userKeys.all, 'info'] as const,
+  check: () => [...userKeys.all, 'check'] as const,
+  contact: (userId: string) => [...userKeys.all, 'contact', userId] as const,
+};
+
+// ============================================================================
+// User Info Hooks
+// ============================================================================
+
+/**
+ * Get current user's account info
+ */
+export function useUserInfo() {
+  return tsRestClient.user.getInfo.useQuery(userKeys.info(), {});
+}
+
+/**
+ * Check user info (returns userId)
+ */
+export function useUserCheck() {
+  return tsRestClient.user.check.useQuery(userKeys.check(), {});
+}
+
+/**
+ * Get user contact info by userId
+ * @param userId - User UUID
+ */
+export function useUserContact(userId: string) {
+  const queryKey = userKeys.contact(userId);
+  return tsRestClient.user.getContact.useQuery(
+    queryKey,
+    { params: { userId } },
+    { queryKey, enabled: Boolean(userId) },
+  );
+}

package/template/apps/web/lib/api/contracts/server-client.ts

@@ -16,7 +16,7 @@ import {
   DEVICE_ID_HEADER,
   MPTRAIL_HEADER,
 } from '@repo/constants';
-import { API_CONFIG } from '../../config';
+import { API_CONFIG } from '@/config';
 import { APP_VERSION } from '../../version';
 
 const API_BASE_URL = API_CONFIG.baseUrl;