# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

RuoYi-Vue-Plus frontend — a multi-tenant admin management system. Built with **Vue 3 + TypeScript + Vite + Element Plus + Pinia + UnoCSS**. The backend is a Java/Spring Boot service (separate repo).

## Project Directory Structure

High-level map of the repository (excluding `node_modules/`, `dist/`, and `.git/`). The app boots from **`index.html`** → **`src/main.ts`** → **`src/App.vue`**.

### Repository root

| Path | Purpose |
|------|---------|
| `src/` | All Vue application source |
| `public/` | Static assets served as-is by Vite (favicon, etc.) |
| `vite/` | Vite config fragments; **`vite/plugins/`** holds custom plugins (auto-import, icons, compression, etc.) |
| `bin/` | Optional shell/helper scripts |
| `html/` | Extra static HTML assets used by the project |
| `.claude/` | Local Claude Code agents, rules, skills (optional; may be gitignored in some clones) |
| `CLAUDE.md` | AI / contributor guidance for this repo |
| `vite.config.ts` | Vite entry config |
| `tsconfig.json` | TypeScript compiler options |
| `uno.config.ts` | UnoCSS utility config |
| `eslint.config.ts` | ESLint flat config |
| `.env.development` / `.env.production` | `VITE_*` environment variables |
| `package.json` / `pnpm-lock.yaml` | Dependencies and scripts (pnpm) |
| `README.md` | Human-oriented project readme |
| `LICENSE` | License file |
| `.editorconfig` / `.prettierrc` / `.prettierignore` | Editor & Prettier defaults |
| `.eslintrc-auto-import.json` | ESLint metadata for auto-imported globals |

### `.claude/` (local only, gitignored)

Not committed to the repo; present on some dev machines for Claude Code:

- `agents/` — agent prompt files (e.g. `jarvis.md`)
- `commands/` — custom slash commands
- `rules/` — extra coding rules
- `skills/` — reusable skill docs (e.g. `mock-data`, `vue3-admin`)

### `src/` — top-level files

| File | Purpose |
|------|---------|
| `main.ts` | App bootstrap, global styles, plugin registration |
| `App.vue` | Root component |
| `permission.ts` | Router navigation guard (token, dynamic routes, progress bar) |
| `settings.ts` | Default layout / UI settings |
| `animate.ts` | Transition / animation helpers (if used by layout) |

### `src/api/` — HTTP clients (mirrors backend modules)

Organized by business area; each folder usually has `index.ts` and sometimes `types.ts`.

| Area | Folders |
|------|---------|
| **System** | `system/` — user, role, menu, dept, post, dict, config, notice, oss, ossConfig, tenant, tenantPackage, client, social, … |
| **Monitor** | `monitor/` — online, operlog, loginInfo, cache |
| **Tool** | `tool/gen/` — code generation |
| **Workflow** | `workflow/` — category, definition, instance, task, leave, spel, workflowCommon |
| **Demo** | `demo/demo`, `demo/tree` |
| **Project extensions** | `WarningList/`, `equipmentList/`, `fileList/`, `systemList/` — domain-specific APIs alongside RuoYi modules |
| **Other** | `menu.ts` — menu-related calls at API root |

### `src/views/` — routed pages

Lazy-loaded via `import.meta.glob` in the permission store. Mirrors `src/api/` layout:

- **`system/`** — CRUD pages for users, roles, menus, tenants, dict, OSS, etc.
- **`monitor/`** — online users, operlog, logininfor, cache, admin, snailjob
- **`tool/gen/`** — generator UI
- **`workflow/`** — process definition/instance, tasks, leave, spel, category
- **`demo/`** — sample pages
- **`error/`** — 404 and error views
- **`redirect/`** — redirect helper route
- **Extensions** — `WarningList/`, `equipmentList/`, `fileList/`, `systemList/` (e.g. `systemList/user`, `base`, `password`, `role`)
- **Root views** — `login.vue`, `register.vue`, `index.vue` (home/dashboard)

### `src/components/` — shared Vue components

Reusable UI (each subfolder is typically a small component package): `Breadcrumb`, `DictTag`, `Editor`, `FileUpload`, `ImageUpload`, `ImagePreview`, `Pagination`, `SvgIcon`, `IconSelect`, `Process` (workflow), `UserSelect`, `RoleSelect`, `LangSelect`, `SizeSelect`, `Screenfull`, `Hamburger`, `iFrame`, `TopNav`, `RightToolbar`, `ParentView`, `RuoYiDoc`, `RuoYiGit`, etc.

### `src/layout/` — application shell

- **`index.vue`** — main layout wrapper
- **`components/`** — `AppMain`, `Navbar`, `Sidebar/` (menu, logo, items), `TagsView`, `Settings`, `TopBar`, `notice`, `IframeToggle`, `InnerLink`, `SocialCallback`

### `src/store/modules/` — Pinia stores

`user`, `permission`, `settings`, `tagsView`, `dict`, `notice`, `app`, etc. (see Architecture table below).

### Other `src/` directories

| Path | Purpose |
|------|---------|
| `router/` | Static route table; dynamic routes appended at runtime |
| `plugins/` | `index.ts` registers global properties (`$tab`, `$modal`, `$download`, …) |
| `directive/` | `permission/` (v-hasPermi, v-hasRoles), `common/` |
| `utils/` | `request.ts`, crypto, theme, ruoyi helpers, websocket, SSE, … |
| `lang/` | i18n messages (`zh_CN`, `en_US`) and `index.ts` |
| `hooks/` | Composables (e.g. `useDialog`) |
| `enums/` | Shared enums (HTTP codes, etc.) |
| `types/` | Global `.d.ts` and TS augmentations |
| `assets/` | `logo/`, `images/`, `icons/svg/`, `styles/` (global SCSS) |

### Directory tree (compact)

```
Visualize/
├── bin/
├── html/
├── public/
├── vite/
│   └── plugins/          # auto-import, icons, compression, …
├── src/
│   ├── api/              # REST modules by domain (+ WarningList, equipmentList, …)
│   ├── assets/           # images, svg icons, logo, scss
│   ├── components/       # shared UI (see list above)
│   ├── directive/
│   ├── enums/
│   ├── hooks/
│   ├── lang/
│   ├── layout/           # shell + layout/components/*
│   ├── plugins/
│   ├── router/
│   ├── store/modules/
│   ├── types/
│   ├── utils/
│   ├── views/            # pages: system, monitor, workflow, tool, demo, …
│   ├── App.vue
│   ├── main.ts
│   ├── permission.ts
│   └── settings.ts
├── CLAUDE.md
├── index.html
├── package.json
├── uno.config.ts
├── vite.config.ts
└── tsconfig.json
```

## Commands

```bash
# Install dependencies (pnpm is used, despite docs mentioning npm)
pnpm install --registry=https://registry.npmmirror.com

# Dev server on port 80, proxies /dev-api to localhost:8080
pnpm dev

# Production build
pnpm build:prod

# Linting
pnpm lint:eslint          # check only
pnpm lint:eslint:fix      # auto-fix
pnpm prettier             # format all files

# Preview production build
pnpm preview
```

There are no tests configured in this project.

## Architecture

### Permission & Routing

The routing system is permission-driven:

1. [src/permission.ts](src/permission.ts) is the navigation guard. On first visit with a valid token, it calls `useUserStore().getInfo()` to fetch roles/permissions, then `usePermissionStore().generateRoutes()` to build dynamic routes from the backend menu API.
2. [src/router/index.ts](src/router/index.ts) defines `constantRoutes` (login, 404, redirect, home) and an empty `dynamicRoutes` array. Dynamic routes returned from the backend are added via `router.addRoute()`.
3. The backend returns route metadata as JSON; [src/store/modules/permission.ts](src/store/modules/permission.ts) maps component strings like `'Layout'`, `'ParentView'` to actual Vue components, and lazy-loads view components via `import.meta.glob('./../../views/**/*.vue')`.
4. Route guards check `roles` and `permissions` arrays on each user. Button-level permission uses the `v-hasPermi` / `v-hasRoles` directives defined in [src/directive/permission/](src/directive/permission/).

### API Layer & Encryption

- [src/utils/request.ts](src/utils/request.ts): Axios instance with interceptors for token injection, repeat-submit prevention (session-based, 500ms window), and optional RSA+AES body encryption (`VITE_APP_ENCRYPT=true`). Response interceptor handles 401 → re-login prompt, error code mapping from [src/enums/RespEnum.ts](src/enums/RespEnum.ts).
- [src/utils/crypto.ts](src/utils/crypto.ts): AES key generation, encrypt/decrypt utilities.
- [src/utils/jsencrypt.ts](src/utils/jsencrypt.ts): RSA encrypt/decrypt for the AES key exchange header.
- API modules are organized under [src/api/](src/api/) mirroring backend controllers: `system/`, `monitor/`, `tool/`, `workflow/`, `demo/`, plus project-specific folders (e.g. `WarningList/`, `equipmentList/`) — see **Project Directory Structure**.

### State Management (Pinia)

| Store module | Purpose |
|---|---|
| `app` | Sidebar toggle, device type, language locale, element size |
| `user` | Token, roles, permissions, login/logout/getInfo |
| `permission` | Dynamic route generation from backend menu data |
| `settings` | Layout config (theme, nav layout, tagsView, etc.), persisted to localStorage |
| `tagsView` | Open page tabs state |
| `dict` | Data dictionary cache |
| `notice` | Notification/websocket state |

### Global Plugins & Directives

[src/plugins/index.ts](src/plugins/index.ts) installs these on `app.config.globalProperties`:
- `$tab` — page tab operations
- `$modal` — modal dialogs
- `$cache` — session/local storage helpers
- `$download` — file download with loading indicator
- `$auth` — permission check methods (`hasPermi`, `hasRole`, etc.)
- Utility functions: `useDict`, `parseTime`, `addDateRange`, `handleTree`, `selectDictLabel`

Custom directives (v-hasPermi, v-hasRoles, v-copyText) registered in [src/directive/index.ts](src/directive/index.ts).

### Layout

[src/layout/index.vue](src/layout/index.vue) is the main layout shell. Key sub-components:
- `Sidebar/` — left sidebar menu (renders from `permissionStore.sidebarRouters`)
- `Navbar.vue` — top bar with breadcrumb, user menu, fullscreen toggle
- `TagsView/` — tabbed page navigation
- `Settings/` — layout configuration drawer
- `TopBar/` — alternative top-navigation bar layout

### Views & API Organization

`src/views/` and `src/api/` are organized by business domain:

- `system/` — Users, roles, menus, departments, tenants, dictionary, config, notices, OSS
- `monitor/` — Online users, operation logs, login logs, cache monitoring, admin/snail-job dashboards
- `workflow/` — Process definitions, instances, tasks, categories
- `tool/` — Code generation
- `demo/` — Demo/example pages
- **This repo also adds** `WarningList/`, `equipmentList/`, `fileList/`, `systemList/` under both `views/` and `api/` (see **Project Directory Structure** above).

### Styling

- [UnoCSS](https://unocss.dev) for utility-first CSS (see [uno.config.ts](uno.config.ts))
- Element Plus with SCSS preprocessing
- Dark mode via Element Plus CSS vars (`element-plus/theme-chalk/dark/css-vars.css`)
- Theme color configurable in settings, applied in [src/utils/theme.ts](src/utils/theme.ts)

### i18n

Vue I18n with `zh_CN` (default) and `en_US` in [src/lang/](src/lang/). Language preference persisted to localStorage.

## Key Conventions

- Path alias `@/` maps to `src/`
- `@/` is used for all internal imports
- Environment variables prefixed with `VITE_APP_` are available via `import.meta.env`
- Vite dev server proxies `VITE_APP_BASE_API` (default `/dev-api`) to `http://localhost:8080`
- `.claude/` is listed in [`.gitignore`](.gitignore) and is not committed; **`CLAUDE.md` at repo root is tracked** and documents this project for AI / contributors.