tkNewAdmin/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 yudao-ui-admin-vue3, a Vue 3 admin dashboard built with Vite, TypeScript, and Element Plus. It's part of the 芋道 (Yudao) open-source admin system that supports multi-tenant SaaS scenarios and integrates with Spring Boot/Spring Cloud backends.

Development Commands

Setup

pnpm install          # Install dependencies (pnpm is required, version >=8.6.0)

Development

pnpm dev              # Start dev server with env.local environment
pnpm dev-server       # Start dev server with dev environment
pnpm ts:check         # Run TypeScript type checking

Build

pnpm build:local      # Build for local environment
pnpm build:dev        # Build for dev environment
pnpm build:test       # Build for test environment
pnpm build:stage      # Build for staging environment
pnpm build:prod       # Build for production environment

Preview

pnpm serve:dev        # Preview dev build
pnpm serve:prod       # Preview production build
pnpm preview          # Build local and preview

Linting & Formatting

pnpm lint:eslint      # Fix ESLint issues in .js, .ts, .vue files
pnpm lint:format      # Format code with Prettier
pnpm lint:style       # Fix Stylelint issues in styles

Cleanup

pnpm clean            # Remove node_modules
pnpm clean:cache      # Clear node_modules cache

Architecture

Technology Stack

• Framework: Vue 3.5.12 (Composition API)
• Build Tool: Vite 5.1.4
• UI Library: Element Plus 2.9.1
• Language: TypeScript 5.3.3
• State Management: Pinia 2.1.7 with persistence (pinia-plugin-persistedstate)
• Router: Vue Router 4.4.5
• I18n: Vue I18n 9.10.2
• HTTP Client: Axios 1.9.0
• CSS Framework: UnoCSS 0.58.5
• Icons: Iconify 3.1.1

Directory Structure

src/
├── api/              # API service layer organized by business modules
│   ├── login/        # Authentication APIs
│   ├── system/       # System management (users, roles, menus, etc.)
│   ├── bpm/          # Business Process Management (workflow)
│   ├── infra/        # Infrastructure (code gen, files, jobs, etc.)
│   ├── pay/          # Payment system
│   ├── mall/         # E-commerce/Mall system
│   ├── crm/          # Customer Relationship Management
│   ├── erp/          # Enterprise Resource Planning
│   ├── ai/           # AI/LLM features
│   └── mp/           # WeChat Official Account
├── assets/           # Static assets (images, svgs)
├── components/       # Global reusable components
├── config/           # Configuration files
├── directives/       # Custom Vue directives
├── hooks/            # Composable functions
├── layout/           # Layout components
├── locales/          # I18n translation files
├── plugins/          # Plugin setup (Element Plus, UnoCSS, etc.)
├── router/           # Vue Router configuration
├── store/            # Pinia stores
│   └── modules/      # Store modules (user, permission, dict, etc.)
├── styles/           # Global styles (SCSS)
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
├── views/            # Page components organized by features
├── App.vue           # Root component
├── main.ts           # Application entry point
└── permission.ts     # Route permission guard

Application Bootstrap (src/main.ts)

The application initializes in this order:

1. I18n setup (async - loads translations)
2. Pinia store setup
3. Global components registration
4. Element Plus setup
5. Form Create (form builder) setup
6. Router setup
7. Directives (auth, mounted-focus)
8. VueDOMPurifyHTML (XSS protection for v-html)

Permission & Route System (src/permission.ts)

• Dynamic Route Loading: Routes are fetched from backend based on user permissions
• Route Guards:
  • Checks authentication token before each route
  • Loads user info and permissions on first access
  • Loads dictionary data for the entire app
  • Dynamically adds authorized routes using router.addRoute()
• White List: /login, /social-login, /auth-redirect, /bind, /register, /oauthLogin/gitee

State Management Pattern

Stores are located in src/store/modules/ and use Pinia:

• user.ts - User information and authentication
• permission.ts - User permissions and dynamic routes
• dict.ts - System dictionaries (cached)
• Store modules use the "WithOut" pattern for access outside setup: useUserStoreWithOut()

API Layer Pattern

• APIs are organized by business domain in src/api/
• Each module has an index.ts (API functions) and types.ts (TypeScript interfaces)
• Axios is configured in src/config/axios/ with interceptors for auth and error handling
• API calls should use the centralized request service, not raw axios

Auto-Import System

The project uses unplugin-auto-import and unplugin-vue-components:

• Vue APIs (ref, computed, etc.) are auto-imported
• Element Plus components are auto-imported
• Custom composables from hooks are auto-imported
• Generated types are in src/types/auto-imports.d.ts and src/types/auto-components.d.ts

Form Builder Integration

• Uses @form-create/element-ui and @form-create/designer for dynamic form building
• BPMN workflow designer uses bpmn-js and bpmn-js-properties-panel

Environment Configuration

• Environment files: .env, .env.local, .env.dev, .env.test, .env.stage, .env.prod
• Key variables:
  • VITE_BASE_PATH - Base URL path
  • VITE_BASE_URL - API base URL
  • VITE_PORT - Dev server port
  • VITE_OUT_DIR - Build output directory
  • VITE_DROP_CONSOLE - Remove console.log in production

Build Configuration

• Code Splitting:
  • echarts is split into separate chunk
  • @form-create/element-ui is split separately
  • @form-create/designer is split separately
• Minification: Uses Terser
• Memory: Build uses --max_old_space_size=4096 for large builds

Multi-Tenant (SaaS) Support

This system has built-in multi-tenant functionality:

• Tenant management in system modules
• Tenant packages with customizable menu/permission configurations
• APIs should be tenant-aware

Development Guidelines

Path Aliases

Use @/ for imports, which resolves to src/:

import { useUserStore } from '@/store/modules/user'

TypeScript

• noImplicitAny is disabled - type annotations are not strictly required
• Use interfaces from src/api/*/types.ts for API request/response types

I18n

• Translation files are in src/locales/
• Use the useI18n() composable (auto-imported)
• Support for Chinese and English

Component Development

• Global components in src/components/ are auto-registered
• Use Element Plus components (auto-imported, no manual import needed)
• DiyEditor mobile components are excluded from auto-import

Icons

• SVG icons are in src/assets/svgs/
• Use Iconify for icon sets
• SVG icons are registered with icon-[dir]-[name] pattern

Styling

• SCSS is the preprocessor
• Global variables are in src/styles/variables.scss (auto-injected)
• UnoCSS is used for atomic/utility CSS

Security

• XSS protection via vue-dompurify-html for v-html directives
• Auth tokens managed in src/utils/auth
• Permission directives for button-level access control

Important Notes

• Node.js: Requires >= 16.0.0
• pnpm: Must use pnpm >= 8.6.0 (not npm or yarn)
• Backend: Designed to work with Spring Boot (single) or Spring Cloud (microservices) backend
• Route Debugging: If routes aren't appearing, check the permission store and backend API responses
• Dictionary Loading: System dictionaries are loaded once on login and cached in the dict store

Related Documentation

• Backend API docs (Swagger): Available at /admin-api/swagger-ui.html on backend server
• Official docs: https://doc.iocoder.cn
• Demo: http://dashboard-vue3.yudao.iocoder.cn