AI_OJ_FRONTEND/CLAUDE.md

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