Merge pull request #1197 from ModelEngine-Group/wmc/refactor_0902

♻️ Add cursor rules of frontend

Author: WMC001

.cursor/rules/frontend/component_layer_rules.mdc

@@ -0,0 +1,106 @@
+---
+globs: frontend/components/**/*.tsx
+description: Component layer rules for reusable UI components
+---
+
+### Purpose and Scope
+
+- Component layer contains reusable UI components for `frontend/components/**/*.tsx`
+- Responsibilities: Create reusable components, implement business logic, handle interactions, provide consistent UI
+- **MANDATORY**: All components must use TypeScript and functional components
+
+### Component Organization
+
+- **`components/ui/`** - Base UI components (buttons, inputs, dialogs, etc.)
+- **`components/auth/`** - Authentication-related components
+- **`components/providers/`** - Context providers and global state management
+- Use index files for clean imports: `export { Button } from './button'`
+
+### Component Structure
+
+- Use functional components with TypeScript
+- Define proper interfaces for all props
+- Use React hooks for state management
+- Implement proper error boundaries where needed
+- Follow single responsibility principle
+
+### Props and State Management
+
+- All props must be typed with interfaces
+- Use optional props with default values when appropriate
+- Prefer controlled components over uncontrolled
+- Use local state for component-specific data
+- Use context for shared state across components
+- **CRITICAL**: All logging must use [logger.ts](mdc:frontend/lib/logger.ts) - never use console.log
+
+### Styling and Design
+
+- Use Tailwind CSS classes for styling
+- Follow design system patterns and spacing
+- Ensure responsive design with mobile-first approach
+- Use CSS variables for theme colors
+- Implement proper focus states and accessibility
+
+### Internationalization
+
+- All user-facing text must use `useTranslation` hook
+- Use descriptive translation keys: `t('button.save')` instead of `t('save')`
+- Provide fallback text for missing translations
+- Group related translations in namespaces
+
+### Error Handling
+
+- Implement proper error boundaries for component trees
+- Handle async operations with loading and error states
+- Provide meaningful error messages to users
+- Log errors appropriately for debugging
+
+### Example
+```tsx
+// frontend/components/ui/button.tsx
+import React from 'react';
+import { useTranslation } from 'react-i18next';
+import { cn } from '@/lib/utils';
+
+interface ButtonProps {
+  children: React.ReactNode;
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  loading?: boolean;
+  onClick?: () => void;
+  className?: string;
+}
+
+export function Button({
+  children,
+  variant = 'primary',
+  size = 'md',
+  disabled = false,
+  loading = false,
+  onClick,
+  className,
+}: ButtonProps) {
+  const { t } = useTranslation('common');
+  
+  return (
+    <button
+      className={cn(
+        'inline-flex items-center justify-center rounded-md font-medium transition-colors',
+        variant === 'primary' && 'bg-primary text-primary-foreground hover:bg-primary/90',
+        variant === 'secondary' && 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        variant === 'outline' && 'border border-input bg-background hover:bg-accent',
+        size === 'sm' && 'h-9 px-3 text-sm',
+        size === 'md' && 'h-10 px-4 py-2',
+        size === 'lg' && 'h-11 px-8 text-lg',
+        className
+      )}
+      disabled={disabled || loading}
+      onClick={onClick}
+    >
+      {loading && <div className="mr-2 h-4 w-4 animate-spin rounded-full border-2 border-current border-t-transparent" />}
+      {children}
+    </button>
+  );
+}
+```

.cursor/rules/frontend/hook_layer_rules.mdc

@@ -0,0 +1,86 @@
+---
+globs: frontend/hooks/**/*.ts
+description: Hook layer rules for custom React hooks and state management
+---
+
+### Purpose and Scope
+
+- Hook layer contains custom React hooks for `frontend/hooks/**/*.ts`
+- Responsibilities: Encapsulate state logic, provide service interfaces, handle loading/error states
+- **MANDATORY**: All hooks must be named `useXxx` and use TypeScript
+
+### Hook Organization
+
+- **`hooks/useAuth.ts`** - Authentication state and operations
+- **`hooks/useConfig.ts`** - Configuration management  
+- **`hooks/useChat.ts`** - Chat-related state and operations
+- **`hooks/useMemory.ts`** - Memory management
+- Use descriptive names indicating the hook's purpose
+
+### Hook Structure
+
+- Use TypeScript for all hook definitions
+- Return objects with descriptive property names
+- Handle loading, error, and success states consistently
+- Implement proper cleanup for side effects
+- Use proper dependency arrays in useEffect
+
+### Essential Hook Usage
+
+| Hook | Purpose | When to Use |
+|------|---------|-------------|
+| `useState` | Store component state | Simple state like toggles, counters |
+| `useReducer` | Complex state logic | Multiple state dependencies |
+| `useContext` | Share data between components | Theme, user info, global state |
+| `useEffect` | Handle side effects | Data fetching, subscriptions, timers |
+| `useCallback` | Prevent function recreation | Callbacks passed to child components |
+| `useMemo` | Cache calculations | Expensive computations |
+| `useRef` | Store mutable values | DOM nodes, timer IDs |
+
+### State Management
+
+- Use useState for local component state
+- Use useReducer for complex state logic
+- Use useContext for shared state across components
+- Implement proper state updates and immutability
+- Handle async state updates correctly
+- **CRITICAL**: All logging must use [logger.ts](mdc:frontend/lib/logger.ts) - never use console.log
+
+### Error Handling
+
+- Handle async errors gracefully
+- Provide meaningful error messages
+- Log errors appropriately for debugging
+- Implement retry logic for transient failures
+
+### Example
+```typescript
+// frontend/hooks/useAuth.ts
+import { useState, useEffect, useCallback } from 'react';
+import { authService } from '@/services/authService';
+
+export function useAuth() {
+  const [user, setUser] = useState(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState(null);
+
+  const login = useCallback(async (credentials) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const response = await authService.login(credentials);
+      if (response.success) {
+        setUser(response.data.user);
+      } else {
+        setError(response.error);
+      }
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setIsLoading(false);
+    }
+  }, []);
+
+  return { user, isLoading, error, login };
+}
+```

.cursor/rules/frontend/page_layer_rules.mdc

@@ -0,0 +1,61 @@
+---
+globs: frontend/app/**/*.tsx
+description: Page layer rules for Next.js App Router pages and layouts
+---
+
+### Purpose and Scope
+
+- Page layer handles routing and layouts for `frontend/app/**/*.tsx`
+- Responsibilities: Define routes, handle data fetching, provide layouts, coordinate state
+- **MANDATORY**: All pages must support internationalization through `[locale]` dynamic route
+
+### File Structure
+
+- **`page.tsx`** - Page components that define routes
+- **`layout.tsx`** - Layout components that wrap pages  
+- **`loading.tsx`** - Loading UI components
+- Use kebab-case for new route segments
+- Prefer nested layouts over prop drilling
+
+### Internationalization
+
+- Client components: `const { t } = useTranslation('namespace')`
+- Server components: `getTranslations` from `next-intl`
+- Organize translation keys by feature/namespace
+
+### Data Fetching
+
+- Use Server Components for initial data fetching
+- Use `fetch` with proper caching for server-side data
+- Client-side fetching: custom hooks in `hooks/` directory
+- Handle loading and error states appropriately
+
+### Layout and Metadata
+
+- Define metadata in `layout.tsx` using Next.js metadata API
+- Use dynamic metadata for page-specific information
+- Ensure responsive design with Tailwind CSS
+- Maintain consistent layout structure
+
+### State Management
+
+- Use React Context for shared page-level state
+- Keep page-specific state local to component
+- Use custom hooks for complex state logic
+- Avoid prop drilling with context providers
+- **CRITICAL**: All logging must use [logger.ts](mdc:frontend/lib/logger.ts) - never use console.log
+
+### Example
+```tsx
+// frontend/app/[locale]/chat/page.tsx
+import { useTranslations } from 'next-intl';
+
+export default function ChatPage({ params }: { params: { locale: string } }) {
+  const t = useTranslations('chat');
+  return (
+    <div className="flex h-screen">
+      <h1 className="text-2xl font-bold p-4">{t('title')}</h1>
+    </div>
+  );
+}
+```

.cursor/rules/frontend/service_layer_rules.mdc

@@ -0,0 +1,52 @@
+---
+globs: frontend/services/**/*.ts
+description: Compact service layer rules for API calls and data management
+---
+
+### Purpose and Scope
+
+- Service layer handles API communication and data management for `frontend/services/**/*.ts`
+- **CRITICAL**: All API URLs must come from [api.ts](mdc:frontend/services/api.ts) - never hardcode URLs
+- Responsibilities: API calls, request/response transformation, error handling, type safety
+
+### API URL Management
+
+- **MANDATORY**: Import and use `API_ENDPOINTS` from [api.ts](mdc:frontend/services/api.ts)
+- **FORBIDDEN**: Hardcoded URLs, direct string concatenation for endpoints
+- Use `fetchWithErrorHandling` from [api.ts](mdc:frontend/services/api.ts) for all requests
+
+### Service Organization
+
+- **`services/api.ts`** - Base configuration, endpoints, error handling
+- **`services/*Service.ts`** - Domain-specific API calls (auth, chat, config, etc.)
+- Use descriptive names matching the domain they serve
+
+### Error Handling
+
+- Use `ApiError` class from [api.ts](mdc:frontend/services/api.ts)
+- Handle 401/499 status codes for session expiration
+- Provide meaningful error messages for user feedback
+
+### Type Safety
+
+- Define TypeScript interfaces for all request/response data
+- Use generic types for reusable API functions
+- Export types for use in components and hooks
+- **CRITICAL**: All logging must use [logger.ts](mdc:frontend/lib/logger.ts) - never use console.log
+
+### Example
+```typescript
+// frontend/services/authService.ts
+import { API_ENDPOINTS, fetchWithErrorHandling, ApiError } from './api';
+
+export const authService = {
+  async signin(credentials: SigninRequest): Promise<SigninResponse> {
+    const response = await fetchWithErrorHandling(API_ENDPOINTS.user.signin, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(credentials),
+    });
+    return response.json();
+  }
+};
+```

.cursor/rules/frontend/type_layer_rules.mdc

@@ -0,0 +1,68 @@
+---
+globs: frontend/types/**/*.ts
+description: Type layer rules for TypeScript type definitions and interfaces
+---
+
+### Purpose and Scope
+
+- Type layer contains TypeScript definitions for `frontend/types/**/*.ts`
+- Responsibilities: Define type-safe interfaces, API types, reusable utilities, ensure consistency
+- **MANDATORY**: All types must be exported and use TypeScript
+
+### Type Organization
+
+- **`types/auth.ts`** - Authentication-related types
+- **`types/chat.ts`** - Chat and conversation types
+- **`types/config.ts`** - Configuration types
+- **`types/api.ts`** - API-related types
+- Use descriptive names matching the domain they represent
+
+### Type Definition Standards
+
+- Use interfaces for object shapes and API contracts
+- Use type aliases for unions, primitives, and computed types
+- Use enums for fixed sets of string/number values
+- Use generic types for reusable type patterns
+- Export all types for use in other modules
+
+### API Type Definitions
+
+- Define separate interfaces for request and response data
+- Use consistent naming conventions (e.g., `UserRequest`, `UserResponse`)
+- Include optional fields with proper typing
+- Use union types for status fields and enums
+- Provide JSDoc comments for complex types
+
+### Component Props Types
+
+- Define interfaces for all component props
+- Use descriptive property names
+- Include proper optional/required field indicators
+- Use generic types for reusable component patterns
+- Export types for use in component files
+- **CRITICAL**: All logging must use [logger.ts](mdc:frontend/lib/logger.ts) - never use console.log
+
+### Utility Types
+
+- Create utility types for common patterns
+- Use mapped types for transformations
+- Implement conditional types for complex logic
+- Provide type guards for runtime validation
+
+### Example
+```typescript
+// frontend/types/auth.ts
+export interface User {
+  id: string;
+  email: string;
+  name: string;
+  avatar?: string;
+  role: UserRole;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// Utility types
+export type UserUpdateData = Partial<Pick<User, 'name' | 'avatar'>>;
+export type UserCreateData = Omit<User, 'id' | 'createdAt' | 'updatedAt'>;
+```