RuoYi-Vue/CLAUDE.md

CLAUDE.md

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

Project Overview

RuoYi-Vue v3.9.1 is a rapid development platform with Spring Boot + Vue.js separated architecture. It provides a complete admin dashboard system with JWT authentication, role-based access control, code generation, and 18 built-in functional modules.

Technology Stack:

• Backend: Spring Boot 2.5.15, Spring Security 5.7.14, MyBatis, Redis, JWT
• Frontend: Vue 2.6.12, Element UI 2.15.14, Vuex 3.6.0, Vue Router 3.4.9
• Database: MySQL with Druid connection pool
• Build: Maven (backend), Vue CLI 4.4.6 (frontend)

Project Structure

RuoYi-Vue/
├── pom.xml                          # Root Maven configuration
├── ruoyi-admin/                     # Web service entry point (Controllers, Config)
├── ruoyi-framework/                 # Core framework (Security, AOP, Interceptors)
├── ruoyi-system/                    # System business logic (Services, Mappers)
├── ruoyi-common/                    # Common utilities, constants, exceptions
├── ruoyi-quartz/                    # Scheduled tasks module
├── ruoyi-generator/                 # Code generation module
└── ruoyi-ui/                        # Frontend Vue.js application
    ├── package.json
    ├── vue.config.js                # Webpack config with proxy to backend
    ├── .env.development             # Dev environment (VUE_APP_BASE_API=/dev-api)
    ├── .env.production              # Prod environment (VUE_APP_BASE_API=/prod-api)
    └── src/
        ├── api/                     # API service layer
        ├── components/              # Reusable components
        ├── directive/               # Custom directives (permission, etc.)
        ├── layout/                  # Layout components
        ├── plugins/                 # Plugins (cache, modal, download)
        ├── router/                  # Vue Router configuration
        ├── store/                   # Vuex store modules
        ├── utils/                   # Utility functions
        └── views/                   # Page views (login, system, monitor, tool)

Development Commands

Backend (Maven)

# Package application (skips tests)
mvn clean package -Dmaven.test.skip=true

# Run application from JAR
cd ruoyi-admin/target
java -jar ruoyi-admin.jar

# Or use provided scripts from project root
./ry.sh start|stop|restart|status    # Unix
ry.bat                               # Windows

Frontend (npm)

cd ruoyi-ui

# Install dependencies
npm install

# Development server (runs on port 80, proxies /dev-api to localhost:8080)
npm run dev

# Production build
npm run build:prod

# Staging build
npm run build:stage

# Preview production build
npm run preview

Architecture Patterns

Backend Architecture

Module Dependencies:

• ruoyi-admin → ruoyi-framework → ruoyi-system → ruoyi-common
• ruoyi-generator and ruoyi-quartz are independent modules

Key Patterns:

1. Layered Architecture: Controller → Service → Mapper → Domain
2. Security: JWT + Spring Security with role-based access control
3. Dynamic Datasource: Primary/secondary database support via Druid
4. AOP: Aspect-oriented logging (@Log annotation) and data scope filtering
5. Global Exception Handling: GlobalExceptionHandler with AjaxResult wrapper
6. XSS Prevention: Built-in XSS filtering via XssFilter
7. Repeat Submit Prevention: @RepeatSubmit annotation with interceptor

Key Files:

• ruoyi-admin/src/main/java/com/ruoyi/RuoYiApplication.java - Entry point
• ruoyi-admin/src/main/resources/application.yml - Main configuration
• ruoyi-admin/src/main/resources/application-druid.yml - Database configuration
• ruoyi-framework/src/main/java/com/ruoyi/framework/config/SecurityConfig.java - Security config
• ruoyi-framework/src/main/java/com/ruoyi/framework/aspectj/LogAspect.java - Logging aspect

Frontend Architecture

Key Patterns:

1. Route Guards: permission.js handles JWT token validation and dynamic route generation
2. Axios Interceptors: Request/response handling in utils/request.js
3. Global Methods: Mounted on Vue prototype (e.g., this.getDicts(), this.parseTime())
4. Global Components: DictTag, Pagination, RightToolbar, Editor, FileUpload, ImageUpload
5. Store Modules: user, app, tagsView, permission, settings
6. Directives: v-hasPermi, v-hasRole, v-debounce, v-copy, v-ellipsis

API Proxy Configuration:

• Development: /dev-api → http://localhost:8080
• Production: /prod-api → configured via nginx or context

Key Files:

• ruoyi-ui/src/main.js - Entry point with global registrations
• ruoyi-ui/src/permission.js - Route permission control
• ruoyi-ui/src/utils/request.js - Axios configuration
• ruoyi-ui/src/utils/ruoyi.js - Common utility functions
• ruoyi-ui/src/store/modules/permission.js - Dynamic route generation

Code Generation

The code generator creates CRUD operations from database tables:

1. Access the generator UI at System → Code Generator
2. Import a table from the database
3. Configure field types, validation, and UI options
4. Generate code (creates backend + frontend files)
5. Copy generated files to appropriate directories

Templates are in ruoyi-generator/src/main/resources/vm/

Database

• Main schema: sql/ry_20250522.sql
• Quartz tables: sql/quartz.sql
• Default login: admin/admin123

Common Development Notes

• Backend runs on port 8080 by default
• Frontend dev server runs on port 80 with proxy to backend
• Swagger API docs available at /swagger-ui/index.html when enabled
• Redis required for caching and session storage
• File upload path configured in application.yml under ruoyi.profile