# 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)

```bash
# 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)

```bash
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`