# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Vue 3 + TypeScript frontend application for an AI Online Judge (OJ) platform called "AI OJ By MeowRain". The application uses modern Vue 3 patterns with Composition API and includes a comprehensive authentication and permission system.

## Development Commands

### Environment Setup

- **Package Manager**: Uses `bun` (evidenced by bun.lock file)
- **Development Server**: `npm run dev` (runs on port 3000, opens browser automatically)
- **Production Development**: `npm run dev:prod` (development mode with production environment config)

### Building

- **Development Build**: `npm run build` (builds with development environment)
- **Production Build**: `npm run build:prod` (builds with production environment)
- **Preview**: `npm run preview` (preview built application)

### Code Quality

- **Type Checking**: `npm run type-check` (Vue TypeScript compiler check without emit)
- **Linting**: `npm run lint` (ESLint for .ts and .vue files)
- **Type Generation**: `npm run build:types` (generates TypeScript declaration files)

### Environment Configuration

The application uses environment-specific configuration files:

- `.env.dev` - Development environment (API: <http://localhost:8080>)
- `.env.prod` - Production environment (API: <http://localhost:8080>)
- `.env.test` - Test environment

## Architecture Overview

### Technology Stack

- **Frontend**: Vue 3 with Composition API (`<script setup>`)
- **Language**: TypeScript with strict type checking
- **Build Tool**: Vite (using rolldown-vite@7.2.2)
- **UI Framework**: Arco Design Vue
- **State Management**: Pinia stores
- **Routing**: Vue Router 4 with hash-based routing
- **HTTP Client**: Axios with interceptors
- **CSS**: SCSS support

### Project Structure

你可以使用 命令 tree src /F  在项目根目录下生成项目结构图，以下是主要目录说明：

```
src/
├── access/              # Permission system core
├── api/                # API service layer (currently empty)
├── components/         # Reusable Vue components
├── config/             # Environment configuration
├── layouts/            # Application layout components
├── plugins/            # Vue plugins (Axios configuration)
├── router/             # Route definitions and configuration
├── store/              # Pinia state management
├── types/              # Global TypeScript type definitions
├── utils/              # Utility functions
└── views/              # Page components
```

### Authentication & Permission System

**Access Levels**: Role-based access control with three levels:

- `NOT_LOGIN`: Public access (default)
- `USER`: Logged-in users
- `ADMIN`: Administrators

**Permission Implementation**:

- Routes include `meta.access` property defining required permission level
- `checkAccess.ts` handles permission validation logic
- Navigation menu filters routes based on user permissions
- Axios interceptors automatically attach Bearer tokens to API requests

**User Store** (`src/store/user.ts`):

- Manages authentication state using Pinia
- Stores user login information and tokens
- Currently uses mock data with placeholder `getLoginUser()` method

### Routing Architecture

- **Hash-based routing**: Uses `createWebHashHistory()` for compatibility
- **Route metadata**: Each route includes `hideInMenu` and `access` properties
- **Permission-based navigation**: Menu items filtered by user access level
- **Route guards**: Permission checks before route access

### HTTP Client Configuration

- **Base URL**: Configured via environment variables (`VITE_API_URL`)
- **Interceptors**: Automatic token attachment and response handling
- **Error Handling**: Centralized error handling in `src/plugins/axios.ts`

## Key Patterns and Conventions

### Vue 3 Patterns

- Uses `<script setup>` syntax for all components
- Composition API with reactive refs and computed properties
- TypeScript integration with proper type definitions

### State Management

- Pinia stores for centralized state management
- Type-safe store definitions with TypeScript interfaces
- Reactive state updates with proper reactivity

### Styling

- Arco Design Vue component library for consistent UI
- SCSS support for custom styling
- Global CSS in `src/style.css`

### Path Aliases

- `@` alias points to `src/` directory for clean imports
- Configured in both Vite config and TypeScript config

## Development Notes

### Current Implementation Status

- ✅ Basic Vue 3 + TypeScript setup
- ✅ Arco Design UI integration
- ✅ Permission-based routing system
- ✅ Authentication state management
- ✅ Environment configuration
- ✅ HTTP client with interceptors
- ⚠️ API service layer is empty
- ⚠️ User authentication uses mock data
- ❌ No backend integration yet
- ❌ No testing framework configured

### Known Issues

- Bug in `src/access/checkAccess.ts:24` - should return `true` for USER access
- `getLoginUser()` method in user store is not implemented
- No actual API endpoints implemented in `src/api/`

### Development Workflow

1. Use `npm run dev` for development server
2. Environment variables are loaded automatically based on mode
3. TypeScript strict mode is enabled
4. ESLint configuration for code quality

### Backend Integration

- Configured to connect to `localhost:8080` for API calls
- Uses Bearer token authentication
- Expected to work with a separate backend service
- OpenAPI codegen dependency available for API client generation