From 5fa7f99011304b43ab9f6f51e52e386df20a1be8 Mon Sep 17 00:00:00 2001
From: JEECG <445654970@qq.com>
Date: Mon, 2 Mar 2026 17:32:43 +0800
Subject: [PATCH] =?UTF-8?q?claude=E5=88=9D=E5=A7=8B=E9=85=8D=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 jeecgboot-vue3/CLAUDE.md | 142 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 142 insertions(+)
 create mode 100644 jeecgboot-vue3/CLAUDE.md

diff --git a/jeecgboot-vue3/CLAUDE.md b/jeecgboot-vue3/CLAUDE.md
new file mode 100644
index 000000000..71d9a0234
--- /dev/null
+++ b/jeecgboot-vue3/CLAUDE.md
@@ -0,0 +1,142 @@
+# 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 20+ required.
+
+## Common Commands
+
+```bash
+pnpm dev              # Start dev server (port 3100, mock enabled)
+pnpm build            # Production build (output: dist/)
+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
+npx jest                        # Run all tests
+npx jest tests/test.spec.ts     # Run specific test
+# Framework: Jest 29 + ts-jest, config in jest.config.mjs
+
+pnpm clean:cache      # Clear Vite cache
+pnpm gen:icon          # Regenerate icon data
+```
+
+## 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` → pinia → i18n → app config → registerPackages (@jeecg/online) → registerGlobComp (core Ant Design components) → SSO login → registerSuper (dynamic module discovery) → router setup → guards → directives → error handler → registerThirdComp (vxe-table, emoji, dayjs) → 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
+
+### 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
+- `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'`
+- **ESLint**: Vue3 recommended + TypeScript recommended + Prettier. `any` is allowed. Unused vars prefixed with `_` are ignored
+- **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
+```