jeecgboot/JeecgBoot

# CLAUDE.md

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

## Project Overview

JeecgBoot 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"`).

## Common Commands

```bash
pnpm dev              # Start dev server (port 3100, mock enabled)
pnpm build            # Production build (output: dist/)
pnpm build:docker     # Docker production build
pnpm build:dockercloud # Docker cloud production build
pnpm build:report     # Build with bundle visualizer
pnpm preview          # Build + preview

# Linting (no unified "lint" script — run individually)
npx eslint src/path/to/file.vue          # Lint specific file
npx stylelint "src/**/*.{vue,less,css}"  # Stylelint
pnpm batch:prettier                       # Format all src files

# Testing (Jest configured but not integrated into npm scripts)
# Tests exist in tests/ directory but no test script in package.json
# Run manually if needed: npx jest

pnpm clean:cache      # Clear Vite cache
pnpm gen:icon         # Regenerate icon data
pnpm reinstall        # Clean reinstall all dependencies
```

## Path Aliases

- `/@/` and `@/` → `src/`
- `/#/` and `#/` → `types/`
- `~icons/{collection}/{name}` → unplugin-icons (compile-time icon imports)

The `/@/` prefix (with leading slash) is the project's conventional alias — prefer it for consistency.

## Architecture

### Bootstrap Sequence (src/main.ts)

`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

### Routing & Permissions

- **Permission mode: BACK** — routes and menus are fetched from the backend API via `getBackMenuAndPerms()`
- Dynamic routes added at runtime in `src/store/modules/permission.ts`
- Static routes: login, oauth2-login, token-login, error pages, AI dashboard
- Router mode: HTML5 history (hash mode when running in Electron)
- Super modules discovered dynamically via `import.meta.glob('./**/register.ts')` in `src/views/super/registerSuper.ts`

### State Management (Pinia)

Key stores in `src/store/modules/`:
- `user.ts` (app-user) — auth token, user info, roles, tenant, dict items
- `permission.ts` (app-permission) — dynamic routes, permission codes, backend menus
- `app.ts` (app) — project config, theme, layout settings
- `locale.ts` (app-locale) — i18n locale
- `multipleTab.ts` (app-multiple-tab) — tab state

Auth persisted in localStorage via `src/utils/auth/index.ts`.

### API Layer

- Custom Axios wrapper: `src/utils/http/axios/` — configured instance exported as `defHttp`
- All requests signed with MD5 via `signMd5Utils`
- Tenant ID injected as header when `VITE_GLOB_TENANT_MODE` is enabled
- Response format: `{ code, result, message, success }` where `code === 200` is success

### Component Registration

- **Auto-import**: `unplugin-vue-components` with `AntDesignVueResolver` auto-imports all Ant Design Vue components (no manual import needed in templates)
- **Global manual**: `registerGlobComp.ts` registers Icon, AIcon, JUploadButton, Button, TinyMCE Editor
- **Third-party**: `registerThirdComp.ts` registers vxe-table (full import), custom vxe cell components, emoji picker, dayjs plugins
- **Async loading**: Heavy components use `src/utils/factory/createAsyncComponent.tsx`

### Icon System

Three icon approaches:
1. **Iconify runtime** — `<Icon icon="mdi:home" />` via `@iconify/iconify` CDN lazy-load
2. **SVG sprites** — `<Icon icon="icon-name|svg" />` via `vite-plugin-svg-icons`
3. **unplugin-icons** — `import IconName from '~icons/collection/name'` for compile-time tree-shaken icons

### Theme System

- Less variables generated by `build/generate/generateModifyVars.ts`
- Dark mode via Ant Design Vue `theme.darkAlgorithm`
- CSS variable `--j-global-primary-color` set dynamically from theme color
- CSS class prefix: `jeecg` (defined in `src/settings/designSetting.ts`)

### External Packages

- `@jeecg/online` and `@jeecg/aiflow` are external monorepo packages excluded from Vite optimizeDeps (CJS compatibility issues)
- Registered via `registerPackages(app)` in main.ts

### Performance Optimization Patterns

**Critical: Use dynamic imports for non-critical modules**
- Static `import` at top of file causes the entire dependency chain to load on initial page
- Use `await import('module')` or `import('path/to/module').then()` for lazy loading
- Key files using dynamic imports:
  - `src/settings/registerThirdComp.ts` — vxe-table, emoji picker (loaded after mount)
  - `src/views/super/registerSuper.ts` — dynamic module discovery
  - Non-critical Ant Design Vue components loaded asynchronously

**Vite optimizeDeps**
- 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
- External packages (`@jeecg/*`) excluded due to CJS issues

### Micro-Frontend (Qiankun)

- Can run as master (hosting sub-apps) or child (embedded in parent)
- Config in `src/qiankun/`, sub-apps via `VITE_APP_SUB_*` env vars
- Child mode activated when `VITE_GLOB_QIANKUN_MICRO_APP_NAME` is set

### Electron Support

- `src/electron/` — uses hash router mode
- Platform detected via `VITE_GLOB_RUN_PLATFORM === 'electron'`

## Key Configuration

### Environment Variables

- `.env` — base config (port 3100, app title, SSO/qiankun flags)
- `.env.development` — mock enabled, proxy to `localhost:8080/jeecg-boot`
- `.env.production` — mock disabled, gzip compression
- `.env.docker` — Docker production build config
- `.env.dockercloud` — Docker cloud production build config
- `.env.prod_electron` — Electron production build config
- `VITE_GLOB_*` vars are injected at runtime via `dist/_app.config.js` (changeable post-build)

### Build

- Manual chunks: `vue-vendor`, `antd-vue-vendor`, `vxe-table-vendor`, `emoji-mart-vue-fast`, `china-area-data-vendor`
- Post-build: `build/script/postBuild.ts` generates runtime config; `copyChat.ts` copies chat assets
- Console/debugger stripped in production via esbuild

## Code Style

- **Prettier**: 150 char width, single quotes, trailing commas (es5), 2-space indent, `endOfLine: 'auto'`, `vueIndentScriptAndStyle: true` (indent inside `<script>`/`<style>`), `htmlWhitespaceSensitivity: 'strict'`
- **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
- **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
- **i18n**: Chinese (zh-CN) and English supported. Locale files in `src/locales/lang/`

## Important Directories

```
build/                    # Vite plugins, build scripts, theme generation
src/api/                  # API definitions (sys/, common/, demo/)
src/components/jeecg/     # Jeecg-specific components (JVxeTable, OnLine, etc.)
src/layouts/default/      # Main app layout (header, sider, tabs, menu)
src/settings/             # Project settings (design, components, locale, encryption)
src/utils/http/axios/     # HTTP client configuration
src/views/system/         # System management pages (user, role, menu, dict, etc.)
src/views/super/          # Dynamically-discovered extension modules
types/                    # Global TypeScript declarations
```