111 lines
5.5 KiB
Markdown
111 lines
5.5 KiB
Markdown
# 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 (`gfast-ui`), 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` is pre-configured with:
|
|
- 50 second request timeout
|
|
- `qs` serialization of query parameters with dot notation for nested objects
|
|
- Automatically adds Bearer token (from cookies via Session utility) to all requests
|
|
- Automatically sends only changed fields for PUT requests (diff comparison with original data via `_originalData` field)
|
|
- Handles token expiration globally with redirect to login (prevents multiple overlapping popups)
|
|
- Provides error message extraction from multiple response formats (`message`, `msg`, `error`, `detail`)
|
|
- Error throttling: maximum one error message every 2 seconds
|
|
- 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 plugins registered:
|
|
- `vue-simple-uploader` - Large file upload component
|
|
- Global event bus via mitt: `app.config.globalProperties.mittBus`
|
|
|
|
4. **Authentication**:
|
|
- Token is stored in cookies via `js-cookie` (through the `Session` utility). Other user session data is stored in `sessionStorage`.
|
|
- The `Session.clearAuth()` method only clears authentication-related keys (`token`, `userInfo`, `userMenu`, `permissions`), preserving other local preferences.
|
|
- 401 responses (HTTP or business code) containing token expiration signals trigger automatic logout with a single confirmation popup.
|
|
|
|
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)
|