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
```bash
pnpm install          # Install dependencies (pnpm is required, version >=8.6.0)
```

### Development
```bash
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
```bash
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
```bash
pnpm serve:dev        # Preview dev build
pnpm serve:prod       # Preview production build
pnpm preview          # Build local and preview
```

### Linting & Formatting
```bash
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
```bash
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/`:
```typescript
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