Visualize-electronic-fences/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 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

# 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 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 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 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/.

API Layer & Encryption

• 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/utils/crypto.ts: AES key generation, encrypt/decrypt utilities.
• src/utils/jsencrypt.ts: RSA encrypt/decrypt for the AES key exchange header.
• API modules are organized under 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 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.

Layout

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 for utility-first CSS (see 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

i18n

Vue I18n with zh_CN (default) and en_US in 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 and is not committed; CLAUDE.md at repo root is tracked and documents this project for AI / contributors.