admin-ui/CLAUDE.md

CLAUDE.md

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

Project Overview

This is the GFast UI project, a Vue 3 admin management system based on the vue-next-admin template, customized for a digital advertising/trading platform.

Commands

• npm install - Install dependencies (use npm install --registry=https://registry.npmmirror.com for China mainland)
• npm run dev - Start development server
• npm run build - Build for production
• npm run lint - Run ESLint check
• npm run lint-fix - Fix ESLint issues automatically
• npm run type-check - Run TypeScript type checking
• npm run quality - Run both lint and type-check

Architecture Overview

Tech Stack:

• Vue 3 with Composition API (script setup)
• TypeScript
• Vite
• Element Plus (UI framework)
• Pinia (state management)
• Vue Router (with hash mode)
• Axios (HTTP client)
• i18n (internationalization)
• mitt (event bus)

Directory Structure:

• src/api/ - API client methods organized by business domain (ads, assets, cid, customerService, digitalHuman, knowledge, login, menu, settings, system, etc.)
• src/components/ - Reusable Vue components
• src/directives/ - Custom Vue directives
• src/i18n/ - Internationalization configuration
• src/layout/ - Main layout components
• src/router/ - Route configuration
  • index.ts - Router setup and guard
  • backEnd.ts - Backend-controlled route initialization
  • frontEnd.ts - Frontend-controlled route initialization
  • route.ts - Static route definitions
• src/stores/ - Pinia state stores
  • themeConfig.ts - Theme and global configuration
  • userInfo.ts - User information
  • routesList.ts - Dynamic route management
  • keepAliveNames.ts - keep-alive cache management
• src/theme/ - Theme related styles
• src/types/ - TypeScript type definitions
• src/utils/ - Utility functions
  • request.ts - Axios instance with interceptors, error handling, and token management
  • storage.ts - Session storage wrapper
  • gfast.ts - GFast-specific helpers (file URL construction, tree building, date formatting)
  • diffUtils.ts - Field change detection for PUT requests
• src/views/ - Page components organized by business module

Key Patterns:

1. Routing: Supports both frontend and backend controlled routing. When backend control is enabled (isRequestRoutes: true in themeConfig), routes are fetched from the backend and dynamically added.

2. API Requests:

   • API methods are organized by domain in src/api/ (each subdomain has its own directory structure)
   • The Axios instance in src/utils/request.ts automatically:
     • Adds Bearer token from session storage
     • Sends only changed fields for PUT requests (diff comparison with original data)
     • Handles token expiration globally with redirect to login
     • Provides error message extraction from multiple response formats (message, msg, error, detail)
     • Supports error mode configuration via requestOptions.errorMode:
       • global: (default) Global error popup with backend message
       • page: No automatic popup, reject the error for page-level handling
       • silent: Completely silent, no error display
     • Special handling for code === 402: Triggers module not enabled subscription flow (except for specific asset endpoints)
   • Response format expects code, message/msg, and data. Known success codes: 0, 200.
   • Use getApiErrorMessage(error) from /@/utils/request to extract user-friendly error messages in catch blocks when using page or silent mode.

3. Global Properties & Components:

   • Helpers registered globally for template use:
     • getUpFileUrl, handleTree, useDict, selectDictLabel, parseTime, getItems, setItems, getOptionValue, isEmpty
   • Global components:
     • pagination - Reusable pagination component
   • Global event bus via mitt: app.config.globalProperties.mittBus

4. Authentication: Token is stored in session storage via the Session utility. 401 responses (HTTP or business code) trigger automatic logout.

5. Keep-alive: Route components can be cached via keep-alive, managed by the useKeepALiveNames store.

Environment Variables

• .env.development - Development environment settings
• .env.production - Production environment settings
• VITE_API_URL - Backend API base URL
• VITE_PORT - Dev server port
• VITE_PUBLIC_PATH - Public base path for production build
• VITE_OPEN_CDN - Enable CDN for external dependencies

Development Notes

• The project uses /@ alias for src/
• Components use the Composition API with <script setup lang="ts">
• Styling is done with SCSS
• ESLint enforces code quality
• Node version requirement: >=16.0.0 (supported: v16.x ~ v20.x)