plus-ui/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-Plus is a multi-tenant management system frontend built with Vue 3, TypeScript, Element Plus, and Vite. This is the official UI for the RuoYi-Vue-Plus backend framework (distributed/microservices architecture).

Tech Stack: Vue 3.5+ | TypeScript 5.9+ | Element Plus 2.11+ | Vite 6+ | Pinia 3+ | Vue Router 4.6+

Development Commands

# Install dependencies (using npm mirror for China)
npm install --registry=https://registry.npmmirror.com

# Start development server (runs on http://localhost:80)
npm run dev

# Build for production
npm run build:prod

# Build for development environment
npm run build:dev

# Lint code
npm run lint:eslint

# Fix linting issues automatically
npm run lint:eslint:fix

# Format code with Prettier
npm run prettier

Engine Requirements: Node.js >= 18.18.0 | npm >= 8.9.0

Architecture

Project Structure

src/
├── api/              # API modules organized by domain (system, monitor, workflow, net, demo)
├── assets/           # Static assets (images, styles, icons)
├── components/       # Reusable components (UI + business components)
├── directive/        # Custom Vue directives (v-auth, v-copy, etc.)
├── enums/            # TypeScript enums and constants
├── hooks/            # Vue 3 Composition API hooks
├── lang/             # i18n language files (Chinese/English)
├── layout/           # Layout components (Sidebar, Navbar, TagsView)
├── plugins/          # Global plugins ($tab, $modal, $cache, $auth)
├── router/           # Vue Router configuration
├── store/            # Pinia state management
├── types/            # TypeScript type definitions
├── utils/            # Utility functions (request, crypto, validation)
├── views/            # Page components (mirrors api structure)
├── App.vue           # Root component
├── main.ts           # Application entry point
├── permission.ts     # Route permission control
└── settings.ts       # Global settings

Dynamic Routing & Permissions

The application uses backend-driven routing with permission-based access control:

1. Route Loading Flow (src/permission.ts):

   • User authentication check via getToken()
   • If authenticated but no user info: fetch user info → generate routes → add routes dynamically
   • Routes are fetched from backend via getRouters() API
   • Components are lazy-loaded using import.meta.glob('./../../views/**/*.vue')

2. Route Types:

   • constantRoutes: Always accessible (login, 404, etc.)
   • dynamicRoutes: Permission-based routes added dynamically
   • Special components: Layout, ParentView, InnerLink (handled specially in src/store/modules/permission.ts:76-99)

3. Permission Checking: Uses custom directives and plugins for fine-grained control

State Management (Pinia)

Located in src/store/modules/:

• user.ts: Authentication, user info, logout logic
• permission.ts: Dynamic route generation and management
• app.ts: Application settings (sidebar, language, size) - persisted with @vueuse/core
• settings.ts: Theme and UI preferences
• tagsView.ts: Visited page tabs management
• dict.ts: Dictionary data caching
• notice.ts: Notification state

API Layer

• Base configuration: src/utils/request.ts - Axios instance with interceptors
• Features:
  • JWT token management (Authorization: Bearer <token>)
  • Request/response encryption support (RSA + AES)
  • Duplicate submission prevention (500ms interval)
  • Internationalized error messages
  • Download progress loading
• API modules: Organized by domain in src/api/ mirroring backend structure

Global Plugins

Available in all components via this.$pluginName or composables:

• $tab: Tab/page operations (openPage, closePage, refreshPage)
• $modal: Modal/dialog management (msg, alert, confirm, loading)
• $cache: Session/local storage wrapper
• $auth: Permission checking (hasPermi, hasRole, hasPermiOr)

Code Style & Configuration

• Prettier: 150 char line width, single quotes, 2 spaces, no trailing commas
• ESLint: Vue + TypeScript + Prettier integration
• TypeScript: Path alias @/* → ./src/*, strict mode with some relaxations (noImplicitAny: false, strictNullChecks: false)
• Import: Auto-import for Vue APIs via unplugin-auto-import

Environment Variables

Defined in .env.development and .env.production:

• VITE_APP_TITLE: Application title
• VITE_APP_BASE_API: API base URL (e.g., /dev-api)
• VITE_APP_CONTEXT_PATH: Application context path
• VITE_APP_CLIENT_ID: OAuth client ID
• VITE_APP_ENCRYPT: Enable request/response encryption
• VITE_APP_RSA_PUBLIC_KEY: Request encryption public key
• VITE_APP_RSA_PRIVATE_KEY: Response decryption private key
• VITE_APP_WEBSOCKET: WebSocket toggle (defaults to SSE)
• VITE_APP_SSE: Server-Sent Events toggle

Component Patterns

• Composition API: Use <script setup lang="ts"> syntax
• Props: Use vue-types for runtime type validation
• Auto-import: Vue APIs (ref, reactive, computed, etc.) are auto-imported
• Component naming: Use defineOptions with name property for keep-alive compatibility

Key Features

• Multi-tenancy: Full tenant isolation support
• Workflow Engine: Business process management integration
• Real-time: WebSocket and SSE support for push notifications
• Code Generation: Scaffolding tools for CRUD operations
• File Management: Upload/download with configurable storage
• Monitoring: Cache, logs, server metrics, online users
• i18n: Chinese/English with Element Plus locale integration
• Theme: Light/dark mode with CSS variables

Module Organization

• system: Core system management (users, roles, menus, departments, tenants)
• monitor: System monitoring (logs, cache, online users, server metrics)
• workflow: Workflow process management
• net: Networking/communication features
• demo: Example features and use cases
• tool: Development tools (code generation, form builder)

Backend Integration

This frontend pairs with:

• RuoYi-Vue-Plus: Distributed cluster framework
• RuoYi-Cloud-Plus: Microservices framework

Both available on Gitee/GitHub under dromara organization.

Common Patterns

Adding a New Feature

1. Create API module in src/api/<domain>/
2. Create views in src/views/<domain>/
3. Add types in src/types/ if needed
4. Routes will be loaded dynamically from backend

Permission Checking

// In template
<v-auth="'system:user:add'">Button</v-auth>

// In code
import { useAuth } from '@/hooks/useAuth';
const { hasPermi } = useAuth();
if (hasPermi('system:user:add')) { ... }

API Call Pattern

import { getUserList } from '@/api/system/user';

const { proxy } = getCurrentInstance()!;
const loading = ref(true);

const getList = async () => {
  loading.value = true;
  try {
    const res = await getUserList(queryParams.value);
    // Handle response
  } finally {
    loading.value = false;
  }
};