WCS_UI/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 the **RuoYi-Vue-Plus** frontend — a multi-tenant enterprise management system (Vue 3 + TypeScript + Element Plus + Vite). It is the UI for a Java Spring Boot backend and follows a standard admin panel architecture with RBAC, dynamic routing, and multi-tenant support.

## Commands

```bash
# Development (uses pnpm)
pnpm dev                    # Start dev server (port from VITE_APP_PORT, default 80)
pnpm build:prod             # Production build
pnpm build:dev              # Development build
pnpm preview                # Preview production build locally

# Code quality
pnpm lint:eslint            # Run ESLint
pnpm lint:eslint:fix        # Auto-fix ESLint issues
pnpm prettier               # Format all files with Prettier

# No test runner configured yet (vitest is installed but no vitest.config.ts exists)
```

## Architecture

### Entry & Bootstrap (`src/main.ts`)
- Creates Vue app → mounts Pinia → Vue Router → vue-i18n → plugins → custom directives → VXE Table
- Loads UnoCSS, Element Plus styles, Highlight.js, SVG icons
- Imports `src/permission.ts` for route guards

### Routing (`src/router/index.ts`)
Two-tier route system:

1. **`constantRoutes`** — always loaded (login, register, 401, 404, index, redirect, profile)
2. **`dynamicRoutes`** — initially empty array; populated by frontend-defined routes checked against user permissions

Actual menus come from the **backend API** (`/getRouters`). `permission.ts` store fetches these, converts backend route configs to Vue Router routes via `filterAsyncRouter()`, and dynamically adds them. Component strings from backend (e.g., `"system/user/index"`) are resolved against `import.meta.glob('./../../views/**/*.vue')`.

### Permission Guard (`src/permission.ts`)
Router `beforeEach`:
- No token → redirect to `/login` (unless whitelisted)
- Has token + no roles loaded → fetch user info (`useUserStore().getInfo()`) then generate routes (`usePermissionStore().generateRoutes()`) → dynamically add routes → redirect to target
- Has token + roles loaded → allow navigation

### State Management (Pinia)

| Store | File | Purpose |
|-------|------|---------|
| `user` | `src/store/modules/user.ts` | Auth token, user info, roles, permissions |
| `permission` | `src/store/modules/permission.ts` | Dynamic routes generation, sidebar/topbar route trees |
| `app` | `src/store/modules/app.ts` | Sidebar state, device type, language, size |
| `settings` | `src/store/modules/settings.ts` | Layout config (theme, navType, tagsView, etc.) persisted to localStorage |
| `dict` | `src/store/modules/dict.ts` | Dictionary data cache |
| `tagsView` | `src/store/modules/tagsView.ts` | Multi-tab page management |
| `notice` | `src/store/modules/notice.ts` | Notification/announcement state |

### HTTP Layer (`src/utils/request.ts`)
Axios instance with:
- **Request interceptor**: injects Bearer token + `Content-Language` header, GET params serialization, duplicate submit detection (500ms window via sessionStorage), optional AES body encryption (ECB mode, key encrypted with RSA public key)
- **Response interceptor**: AES decryption, 401 → re-login prompt, 500 → error message, 601 → warning
- **`download()`** helper for file downloads with loading state

Encryption is toggleable via `VITE_APP_ENCRYPT` env var — must match backend config.

### Permission System (`src/plugins/auth.ts`)
- `hasPermi(permission)` — exact permission match (admin `*:*:*` wildcard supported)
- `hasPermiOr(permissions)` — any match
- `hasPermiAnd(permissions)` — all match
- `hasRole(role)` / `hasRoleOr(roles)` / `hasRoleAnd(roles)` — role-based equivalents
- Used in route filtering and button-level UI control via custom directives

### Layout (`src/layout/index.vue`)
Classic admin layout: Sidebar + Navbar + TagsView + AppMain + Settings drawer. Supports:
- `NavTypeEnum.LEFT` — left sidebar
- `NavTypeEnum.TOP` — top navigation
- `NavTypeEnum.MIX` — mixed mode
- Responsive: mobile detection at 992px breakpoint

### API Layer (`src/api/`)
Organized by backend module:
- `src/api/login.ts` — auth (login, logout, register, tenant list)
- `src/api/menu.ts` — menu/routing
- `src/api/system/` — user, role, menu, dept, post, dict, config, notice, tenant, oss, client, social
- `src/api/monitor/` — online users, operlog, loginInfo, cache
- `src/api/tool/gen/` — code generation
- `src/api/workflow/` — workflow (category, definition, instance, task, leave)
- `src/api/demo/` — demo/demo, demo/tree

### Directory Quick Reference

| Directory | Purpose |
|-----------|---------|
| `src/views/` | Page components, mirrors `src/api/` module structure |
| `src/components/` | Shared components (Breadcrumb, DictTag, FileUpload, ImageUpload, Editor, Pagination, etc.) |
| `src/plugins/` | Global Vue plugins installed via `app.use()` — auth, cache, modal, tab, download, svgicon |
| `src/directive/` | Custom directives (permission checks, common utilities) |
| `src/utils/` | Utilities — request, auth (token storage), crypto (AES+RSA), validate, websocket, sse, ruoyi (helper fns), dict, theme, scroll-to |
| `src/lang/` | vue-i18n language packs (zh_CN, en_US) |
| `src/enums/` | TypeScript enums (HttpStatus, NavTypeEnum, LanguageEnum, SideThemeEnum, MenuTypeEnum) |
| `src/types/` | Global type declarations (env.d.ts, router.d.ts, global.d.ts, etc.) |
| `vite/plugins/` | Vite plugin configs — auto-import, auto-components, UnoCSS, SVG icons, compression, setup-extend |

### Key Conventions
- Auto-imported: `vue`, `vue-router`, `@vueuse/core`, `pinia` (via `unplugin-auto-import`)
- Auto-registered: Element Plus components + `icon-park` icons (via `unplugin-vue-components`)
- Path alias: `@/` → `src/`
- Uses UnoCSS with `presetAttributify` (attribute-based utilities) and `presetIcons`
- SCSS variables in `src/assets/styles/variables.module.scss`
- Backend API prefix: `/dev-api` (dev), configurable via `VITE_APP_BASE_API`
- Token stored in localStorage under key `Admin-Token`, managed via `@vueuse/core`'s `useStorage`
- SSR/SSE: `src/utils/sse.ts` for Server-Sent Events, `src/utils/websocket.ts` for WebSocket

### Important: Backend-Driven Nature
Many UI aspects are controlled by backend API responses:
- **Menus/routes** come from backend (not frontend route definitions)
- **Dictionaries** (`dict` store) provide dynamic dropdown options throughout the app
- **Tenant info** is fetched on auth and drives data isolation
- Always check the backend API contract when modifying UI modules