CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7JeecgBoot Vue3 frontend — an enterprise low-code platform built with Vue 3 + Vite 6 + Ant Design Vue 4 + TypeScript. Uses pnpm as package manager. Node 18 or 20+ required (`engines: "^18 || >=20"`).
8 
9## Common Commands
10 
11```bash
12pnpm dev              # Start dev server (port 3100, mock enabled)
13pnpm build            # Production build (output: dist/)
14pnpm build:docker     # Docker production build
15pnpm build:dockercloud # Docker cloud production build
16pnpm build:report     # Build with bundle visualizer
17pnpm preview          # Build + preview
18 
19# Linting (no unified "lint" script — run individually)
20npx eslint src/path/to/file.vue          # Lint specific file
21npx stylelint "src/**/*.{vue,less,css}"  # Stylelint
22pnpm batch:prettier                       # Format all src files
23 
24# Testing (Jest configured but not integrated into npm scripts)
25# Tests exist in tests/ directory but no test script in package.json
26# Run manually if needed: npx jest
27
28pnpm clean:cache      # Clear Vite cache
29pnpm gen:icon         # Regenerate icon data
30pnpm reinstall        # Clean reinstall all dependencies
31```
32 
33## Path Aliases
34 
35- `/@/` and `@/` → `src/`
36- `/#/` and `#/` → `types/`
37- `~icons/{collection}/{name}` → unplugin-icons (compile-time icon imports)
38 
39The `/@/` prefix (with leading slash) is the project's conventional alias — prefer it for consistency.
40 
41## Architecture
42 
43### Bootstrap Sequence (src/main.ts)
44 
45`createApp` → createRouter → setupStore (pinia) → setupProps → i18n → initAppConfigStore → registerPackages (@jeecg/online) → registerGlobComp (core Ant Design components) → SSO login → registerSuper (dynamic module discovery) → setupRouter → guards → directives → error handler → registerThirdComp (vxe-table, emoji, dayjs) → setupElectron → router.isReady() → mount
46 
47### Routing & Permissions
48 
49- **Permission mode: BACK** — routes and menus are fetched from the backend API via `getBackMenuAndPerms()`
50- Dynamic routes added at runtime in `src/store/modules/permission.ts`
51- Static routes: login, oauth2-login, token-login, error pages, AI dashboard
52- Router mode: HTML5 history (hash mode when running in Electron)
53- Super modules discovered dynamically via `import.meta.glob('./**/register.ts')` in `src/views/super/registerSuper.ts`
54 
55### State Management (Pinia)
56 
57Key stores in `src/store/modules/`:
58- `user.ts` (app-user) — auth token, user info, roles, tenant, dict items
59- `permission.ts` (app-permission) — dynamic routes, permission codes, backend menus
60- `app.ts` (app) — project config, theme, layout settings
61- `locale.ts` (app-locale) — i18n locale
62- `multipleTab.ts` (app-multiple-tab) — tab state
63 
64Auth persisted in localStorage via `src/utils/auth/index.ts`.
65 
66### API Layer
67 
68- Custom Axios wrapper: `src/utils/http/axios/` — configured instance exported as `defHttp`
69- All requests signed with MD5 via `signMd5Utils`
70- Tenant ID injected as header when `VITE_GLOB_TENANT_MODE` is enabled
71- Response format: `{ code, result, message, success }` where `code === 200` is success
72 
73### Component Registration
74 
75- **Auto-import**: `unplugin-vue-components` with `AntDesignVueResolver` auto-imports all Ant Design Vue components (no manual import needed in templates)
76- **Global manual**: `registerGlobComp.ts` registers Icon, AIcon, JUploadButton, Button, TinyMCE Editor
77- **Third-party**: `registerThirdComp.ts` registers vxe-table (full import), custom vxe cell components, emoji picker, dayjs plugins
78- **Async loading**: Heavy components use `src/utils/factory/createAsyncComponent.tsx`
79 
80### Icon System
81 
82Three icon approaches:
831. **Iconify runtime** — `<Icon icon="mdi:home" />` via `@iconify/iconify` CDN lazy-load
842. **SVG sprites** — `<Icon icon="icon-name|svg" />` via `vite-plugin-svg-icons`
853. **unplugin-icons** — `import IconName from '~icons/collection/name'` for compile-time tree-shaken icons
86 
87### Theme System
88 
89- Less variables generated by `build/generate/generateModifyVars.ts`
90- Dark mode via Ant Design Vue `theme.darkAlgorithm`
91- CSS variable `--j-global-primary-color` set dynamically from theme color
92- CSS class prefix: `jeecg` (defined in `src/settings/designSetting.ts`)
93 
94### External Packages
95 
96- `@jeecg/online` and `@jeecg/aiflow` are external monorepo packages excluded from Vite optimizeDeps (CJS compatibility issues)
97- Registered via `registerPackages(app)` in main.ts
98 
99### Performance Optimization Patterns
100 
101**Critical: Use dynamic imports for non-critical modules**
102- Static `import` at top of file causes the entire dependency chain to load on initial page
103- Use `await import('module')` or `import('path/to/module').then()` for lazy loading
104- Key files using dynamic imports:
105  - `src/settings/registerThirdComp.ts` — vxe-table, emoji picker (loaded after mount)
106  - `src/views/super/registerSuper.ts` — dynamic module discovery
107  - Non-critical Ant Design Vue components loaded asynchronously
108 
109**Vite optimizeDeps**
110- Pre-bundled dependencies in `vite.config.ts` include: dayjs, axios, pinia, nprogress, qs, crypto-js, md5, sortablejs, xe-utils, vue-i18n, lodash-es, xss, mockjs
111- External packages (`@jeecg/*`) excluded due to CJS issues
112 
113### Micro-Frontend (Qiankun)
114 
115- Can run as master (hosting sub-apps) or child (embedded in parent)
116- Config in `src/qiankun/`, sub-apps via `VITE_APP_SUB_*` env vars
117- Child mode activated when `VITE_GLOB_QIANKUN_MICRO_APP_NAME` is set
118 
119### Electron Support
120 
121- `src/electron/` — uses hash router mode
122- Platform detected via `VITE_GLOB_RUN_PLATFORM === 'electron'`
123 
124## Key Configuration
125 
126### Environment Variables
127 
128- `.env` — base config (port 3100, app title, SSO/qiankun flags)
129- `.env.development` — mock enabled, proxy to `localhost:8080/jeecg-boot`
130- `.env.production` — mock disabled, gzip compression
131- `.env.docker` — Docker production build config
132- `.env.dockercloud` — Docker cloud production build config
133- `.env.prod_electron` — Electron production build config
134- `VITE_GLOB_*` vars are injected at runtime via `dist/_app.config.js` (changeable post-build)
135 
136### Build
137 
138- Manual chunks: `vue-vendor`, `antd-vue-vendor`, `vxe-table-vendor`, `emoji-mart-vue-fast`, `china-area-data-vendor`
139- Post-build: `build/script/postBuild.ts` generates runtime config; `copyChat.ts` copies chat assets
140- Console/debugger stripped in production via esbuild
141 
142## Code Style
143 
144- **Prettier**: 150 char width, single quotes, trailing commas (es5), 2-space indent, `endOfLine: 'auto'`, `vueIndentScriptAndStyle: true` (indent inside `<script>`/`<style>`), `htmlWhitespaceSensitivity: 'strict'`
145- **ESLint**: Vue3 recommended + TypeScript recommended + Prettier. `any` is allowed. Unused vars prefixed with `_` are ignored. Note: `prettier/prettier` rule is `'off'` — Prettier is not enforced via ESLint, run it separately
146- **Commits**: Conventional commits enforced via commitlint. Types: feat, fix, perf, style, docs, test, refactor, build, ci, chore, revert, wip, workflow, types, release. Max header: 108 chars
147- **i18n**: Chinese (zh-CN) and English supported. Locale files in `src/locales/lang/`
148 
149## Important Directories
150 
151```
152build/                    # Vite plugins, build scripts, theme generation
153src/api/                  # API definitions (sys/, common/, demo/)
154src/components/jeecg/     # Jeecg-specific components (JVxeTable, OnLine, etc.)
155src/layouts/default/      # Main app layout (header, sider, tabs, menu)
156src/settings/             # Project settings (design, components, locale, encryption)
157src/utils/http/axios/     # HTTP client configuration
158src/views/system/         # System management pages (user, role, menu, dict, etc.)
159src/views/super/          # Dynamically-discovered extension modules
160types/                    # Global TypeScript declarations
161```
162