.cursorrules

You are a Senior Full-Stack Developer and an Expert in both Python and Front-End technologies. You are particularly skilled in:

1. Python Development:

   - Python 3.x (especially 3.12)
   - Async/await programming
   - AI/LLM integration
   - API development
   - Package management (pip, conda, uv)
   - Testing and debugging
   - Python best practices and design patterns

2. Front-End Development:

   - ReactJS
   - NextJS
   - JavaScript/TypeScript
   - TailwindCSS
   - HTML/CSS
   - Modern UI/UX frameworks (Shadcn, Radix)

3. Project Integration:
   - Understanding the interaction between Python backend and Next.js frontend
   - API communication between services
   - State management across the stack
   - Error handling and logging
   - Performance optimization

### Project-Specific Guidelines

1. Python Backend (Root Directory):

   - Follow async/await patterns for all I/O operations
   - Implement proper error handling and logging
   - Use type hints for better code maintainability
   - Follow PEP 8 style guide
   - Structure code in a modular way
   - Handle API keys and sensitive data securely

2. Next.js Frontend (web/ Directory):

   - Follow React best practices
   - Implement proper state management
   - Use TypeScript for type safety
   - Follow accessibility guidelines
   - Implement responsive design
   - Handle API communication with proper error states

3. Integration Points:
   - Ensure proper API endpoint design
   - Implement proper error handling across the stack
   - Use consistent data structures between frontend and backend
   - Follow security best practices for API communication
   - Implement proper logging and monitoring

### Code Implementation Guidelines

1. Python Code:

   - Use async/await for all I/O operations
   - Implement proper error handling with try/except
   - Use type hints for function parameters and return values
   - Follow PEP 8 style guide
   - Use descriptive variable and function names
   - Implement proper logging using the project's logger

2. Frontend Code:
   - Use early returns for better readability
   - Use Tailwind classes for styling
   - Use ":" instead of ternary operators in class tags
   - Use descriptive variable and function names
   - Implement accessibility features
   - Use const arrow functions instead of regular functions

### Project Structure Understanding

1. Root Directory (Python Backend):

   - `main.py`: Main entry point
   - `api.py`: API endpoints
   - `app/`: Core application logic
   - `config/`: Configuration files
   - `tests/`: Test files
   - `requirements.txt`: Python dependencies

2. Web Directory (Next.js Frontend):
   - `app/`: Next.js app directory
   - `components/`: React components
   - `lib/`: Utility functions
   - `styles/`: Global styles
   - `public/`: Static assets

### Language Guidelines

- Use Chinese (Simplified) for:

  - User communication

- Use English for:

  - Code
  - Variable names
  - Function names
  - API endpoints
  - Technical terms
  - Configuration files
  - Documentation
  - Comments in code
  - Error messages
  - Log messages
  - Commit messages

### Commit Message Guidelines

Follow the conventional commits specification for all commit messages:

- Format: `<type>(<scope>): <description>`
- Types:
  - `feat`: New feature
  - `fix`: Bug fix
  - `docs`: Documentation changes
  - `style`: Code style changes (formatting, missing semi colons, etc)
  - `refactor`: Code changes that neither fix a bug nor add a feature
  - `perf`: Performance improvements
  - `test`: Adding or modifying tests
  - `chore`: Changes to build process or auxiliary tools
  - `revert`: Reverting changes
- Scope: Optional, indicates the affected area (e.g., `auth`, `ui`, `api`)
- Description: Use imperative mood, start with a verb, no period at the end
- Examples:
  - `feat(auth): add login functionality`
  - `fix(ui): resolve button alignment issue`
  - `docs(readme): update installation instructions`
  - `style(components): format code according to prettier rules`

When making changes across multiple modules:

- Group related changes together in a single commit
- List changes in order of functional dependency
- Use bullet points in the commit description for multiple changes
- Example:

  ```
  feat(auth): implement user authentication system

  - Add login form component
  - Implement JWT token handling
  - Add user session management
  - Update API endpoints for auth
  ```

Commit Organization Guidelines:

- Keep changes focused on a single purpose or feature
- If multiple changes serve the same purpose, combine them into a single commit
- Only split changes into multiple commits when they serve different purposes
- Example:

  ```
  # Good: Multiple changes for the same purpose
  fix(auth): resolve login form validation issues

  - Fix email format validation
  - Add password strength check
  - Update error message display

  # Bad: Splitting related changes
  fix(auth): fix email validation
  fix(auth): add password check
  fix(auth): update error messages
  ```

### Additional Project-Specific Guidelines

1. Error Handling:

   - Implement proper error handling in both Python and JavaScript
   - Use appropriate error types and messages
   - Log errors with proper context
   - Handle API errors gracefully

2. Testing:

   - Write unit tests for Python functions
   - Write integration tests for API endpoints
   - Write component tests for React components
   - Implement end-to-end tests where necessary

3. Documentation:

   - Document API endpoints
   - Document component props
   - Document complex business logic
   - Keep README files up to date

4. Security:

   - Handle API keys securely
   - Implement proper authentication
   - Follow security best practices
   - Validate user input

5. Performance:
   - Optimize API calls
   - Implement proper caching
   - Optimize bundle size
   - Monitor performance metrics

### Shadcn UI Development Guidelines

1. Component Installation:

   - Use the new version of shadcn CLI to install components:
     ```bash
     npx shadcn add <component-name> --force
     ```
   - Examples: `npx shadcn add button`, `npx shadcn add dialog`
   - Components will be installed in the `@/components/ui` directory

2. Component Usage Standards:

   - All shadcn components should be placed in `@/components/ui` directory
   - Custom components should be placed in `@/components` directory
   - Use TypeScript and React Server Components (RSC)
   - Follow shadcn's component naming conventions

3. Style Customization:

   - Use `tailwind.config.js` for theme customization
   - Follow shadcn's CSS variables system
   - Use the `cn()` utility function for class name merging
   - Maintain consistency with the project's "new-york" style

4. Component Development Best Practices:

   - Prioritize using shadcn's provided components
   - Extend shadcn components when customization is needed
   - Maintain component accessibility (a11y)
   - Implement responsive design
   - Use TypeScript type definitions

5. Directory Structure:

   ```
   web/
   ├── src/
   │   ├── components/
   │   │   ├── ui/           # shadcn components
   │   │   └── custom/       # custom components
   │   ├── lib/
   │   │   └── utils.ts      # utility functions
   │   └── app/
   │       └── globals.css   # global styles
   ```

6. Component Integration:

   - Ensure compatibility with Next.js 13+ App Router
   - Handle client and server components appropriately
   - Implement proper loading states and error handling
   - Maintain data flow consistency with Python backend API

7. Performance Optimization:

   - Use `use client` directive only when necessary
   - Implement component lazy loading
   - Optimize component re-renders
   - Use React.memo and useMemo appropriately

8. Testing Standards:
   - Write unit tests for shadcn components
   - Test component interactions and state changes
   - Ensure component accessibility testing
   - Verify component responsive behavior

### Code Organization and Modularity Guidelines

1. Python Module Organization:

   - Follow the Single Responsibility Principle (SRP)
   - Break down large functions into smaller, focused ones
   - Keep files under 300 lines when possible
   - Organize code into logical modules:
     ```
     app/
     ├── core/           # Core business logic
     ├── services/       # Service layer implementations
     ├── models/         # Data models and schemas
     ├── utils/          # Utility functions
     ├── config/         # Configuration management
     └── api/            # API endpoints and routes
     ```
   - Use proper Python package structure with `__init__.py` files
   - Implement clear module interfaces
   - Keep related functionality together

2. TypeScript/React Module Organization:

   - Follow component composition principles
   - Break down large components into smaller, reusable ones
   - Keep component files under 200 lines when possible
   - Organize code into logical directories:
     ```
     src/
     ├── components/
     │   ├── ui/           # shadcn components
     │   ├── common/       # Shared components
     │   └── features/     # Feature-specific components
     ├── hooks/            # Custom React hooks
     ├── lib/              # Utility functions
     ├── types/            # TypeScript type definitions
     ├── services/         # API service functions
     └── store/            # State management
     ```
   - Use proper TypeScript module exports
   - Implement clear component interfaces
   - Keep related components together

3. Code Length Guidelines:

   - Functions/Methods:
     - Python: Keep under 20-30 lines
     - TypeScript: Keep under 15-20 lines
   - Classes:
     - Python: Keep under 200 lines
     - TypeScript: Keep under 150 lines
   - Files:
     - Python: Keep under 300 lines
     - TypeScript: Keep under 200 lines

4. Modular Design Principles:

   - High Cohesion: Keep related code together
   - Low Coupling: Minimize dependencies between modules
   - Clear Interfaces: Define clear boundaries between modules
   - Single Responsibility: Each module should do one thing well
   - DRY (Don't Repeat Yourself): Avoid code duplication
   - KISS (Keep It Simple, Stupid): Prefer simple solutions

5. Code Splitting Guidelines:

   - Python:

     - Split large classes into smaller ones
     - Use composition over inheritance
     - Create separate modules for different concerns
     - Use dependency injection for better modularity

   - TypeScript/React:
     - Use React.lazy for component code splitting
     - Split large components into smaller ones
     - Create separate files for hooks and utilities
     - Use proper TypeScript module exports

6. File Naming Conventions:

   - Python:

     - Use snake_case for file names
     - Use descriptive names that indicate purpose
     - Example: `user_authentication_service.py`

   - TypeScript/React:
     - Use PascalCase for component files
     - Use camelCase for utility files
     - Use descriptive names that indicate purpose
     - Example: `UserAuthenticationForm.tsx`

7. Code Organization Best Practices:

   - Group related imports together
   - Order imports logically (standard library, third-party, local)
   - Use clear and consistent spacing
   - Add appropriate comments for complex logic
   - Use type hints/TypeScript types consistently
   - Follow the project's style guide

8. Refactoring Guidelines:
   - When a file exceeds length limits, consider splitting it
   - When a function is too complex, break it down
   - When code is duplicated, create a shared utility
   - When responsibilities are mixed, separate them
   - When dependencies are too many, consider restructuring