JeecgBoot/jeecgboot-vue3/AGENTS.md

AGENTS.md

This file provides repository guidance for Codex when working in this project.

Communication

• Always answer in Simplified Chinese first, unless the user explicitly requests another language.

Project Overview

JeecgBoot Vue3 (v3.8.3) is an enterprise low-code admin platform frontend. It is built on Vue 3, TypeScript, Vite, Ant Design Vue 4, and Pinia. It was originally forked from Vben Admin and customized with JeecgBoot-specific components such as online forms, code generation, workflow, and related low-code modules.

This workspace uses SVN for version control. Do not assume Git is available in this directory.

Backend: Spring Boot (JeecgBoot), expected at http://127.0.0.1:8080/jeecg-boot during development.

Related Projects

Project	Path
Frontend (Vue3, this repo)	E:\workspace-cc-jeecg\jeecgboot-vue3-2026
Backend (Spring Boot 3)	E:\workspace-cc-jeecg\jeecg-boot-framework-2026

Commands

pnpm install
pnpm dev
pnpm build
pnpm batch:prettier

• pnpm dev starts the dev server on port 3100.
• pnpm build creates the production build in dist/.
• pnpm batch:prettier formats all matching files under src/; run it only when broad formatting is intended.
• No regular test script is configured in package.json; a Jest config exists, but there is no test script.

Path Aliases

• /@/ or @/ maps to src/.
• /#/ or #/ maps to types/.
• Prefer the /@/ prefix with the leading slash, which is the convention used throughout this codebase.

Source Structure

Directory	Purpose
src/api/	HTTP request functions organized by domain, such as sys/ and common/.
src/components/	Reusable components, including generic components and JeecgBoot-specific components under jeecg/.
src/hooks/	Composition API hooks, including web/, setting/, and system/.
src/layouts/	App layouts, including default/, iframe/, and page/.
src/router/	Vue Router setup with dynamic route registration based on backend permissions.
src/store/	Pinia stores for app, user, permission, tabs, locale, and lock state.
src/settings/	Global project, component, and design settings.
src/utils/	HTTP client, auth/token management, encryption, dict helpers, and shared utilities.
src/views/	Feature pages, including system/, dashboard/, monitor/, and super/.
src/locales/	i18n files such as zh_CN and en.
src/enums/	TypeScript enums for constants.
src/directives/	Custom directives such as v-auth, v-loading, v-click-outside, and v-ripple.

View Conventions

Each feature module in src/views/ typically includes:

• index.vue for the main list page.
• *.data.ts for table column definitions and form schemas.
• *.api.ts for API endpoint calls.
• *Modal.vue or *Drawer.vue for detail and edit components.

Component Patterns

Use BasicTable and BasicForm for list pages:

import { BasicTable, useTable } from '/@/components/Table';

const [registerTable] = useTable({ api, columns, formConfig: { schemas } });

Use useModal and useDrawer for detail panels:

const [registerModal, { openModal }] = useModal();
openModal(true, { isUpdate: true, record });

Use useListPage from src/hooks/system/ for standard CRUD pages that combine table, form, modal, and drawer behavior.

Form schemas use FormSchema[] with component specifying Ant Design Vue or custom components such as Input, Select, JDictSelectTag, and JSearchSelect.

HTTP Client

defHttp in src/utils/http/axios/ wraps Axios with:

• Token injection through interceptors.
• MD5 request signing for API security.
• Multi-tenant header support.
• Standard response unwrapping through the result field.

API functions usually follow this pattern:

enum Api {
  List = '/sys/user/list',
}

export const list = (params) => defHttp.get({ url: Api.List, params });

Authentication And Permissions

• Tokens are stored in localStorage through auth utilities.
• src/router/guard/permissionGuard.ts fetches user info and dynamic menus from the backend.
• Permission mode is BACK, meaning routes and button permissions are backend-driven.
• Button-level auth uses the v-auth="'system:user:add'" directive or the usePermission() hook.

Component Settings

Table pagination uses pageNo and pageSize params and expects records and total in the response. This is configured in src/settings/componentSetting.ts.

Environment Variables

• .env contains base config such as port, app title, SSO, and qiankun toggles.
• .env.development contains dev proxy, mock toggle, and backend URL.
• .env.production contains production API URL and gzip config.
• Key variables include VITE_GLOB_DOMAIN_URL, VITE_GLOB_API_URL, and VITE_PROXY.

Build System

vite.config.ts delegates plugin setup to build/vite/plugin/. Plugins include HTML template handling, mock data, gzip compression, SVG sprites, dynamic theme, qiankun micro-frontend, and PWA. Build scripts under build/script/ handle post-build tasks.

Online Forms

Online forms are a JeecgBoot low-code core feature. They generate CRUD pages from configuration. The full schema reference is in src/views/super/online/cgform/online-form-schema.md and covers table metadata, field configuration, control types, validation rules, and JavaScript enhancements.

Code Style

• Prettier uses 150 character line width, single quotes, trailing commas for ES5, semicolons, and 2-space indentation.
• ESLint uses vue/vue3-recommended, @typescript-eslint/recommended, and Prettier with Prettier rules disabled.
• Unused variables prefixed with _ are allowed.
• Prefer <script setup> for new Vue components.
• Use Less for styling.

Working Exclusions

Treat the existing .claudeignore as the source for routine Codex work exclusions.

Avoid broad searches, reads, or edits in these paths unless the task explicitly targets them or verification requires them:

• .git/, .svn/, .idea/, .vscode/
• node_modules/, dist/, target/, docker/data/
• backup/, .history/, .cursor/
• doc/, docs/
• IDE metadata such as *.iml, *.iws, *.ipr, .classpath, .project, .settings/, and out/
• OS files such as .DS_Store, Thumbs.db, and desktop.ini
• Logs and generated artifacts such as *.log, logs/, *.class, *.zip, *.qqy, 代码修改.log, and 代码修改日志

The .claudeignore file lists build/, but this frontend uses build/ for Vite plugins and build scripts. Avoid broad scans there, but allow targeted reads and edits when working on build tooling.