diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 675c767..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,230 +0,0 @@ -# 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. - -## Repository Collaboration Rules - -These rules capture long-term repository preferences confirmed by the user and should be applied in future sessions unless the user explicitly overrides them. - -### Pagination Rules - -- Prefer the project global `pagination` component by default. -- Pagination should be fixed and visible as part of the page or dialog layout, not conditionally hidden only because the dataset is small. -- In single-page scenarios, the UI should still show total count together with the pagination area. -- Avoid designs where pagination only appears after data exceeds one page. - -### Dialog Layout Rules - -- For dialogs that contain searchable tabular data, prefer this structure: - 1. search area - 2. table/content area - 3. pagination area placed under the table inside the dialog body - 4. footer action buttons -- The pagination area should remain visually stable and should not be omitted just because the current result set is small. - -### Theme and Style Rules - -- When functionality and existing theme style conflict, prioritize making the feature clearly visible and usable first. -- After ensuring usability, align the implementation with the repository's existing theme and style system as much as possible. -- Be cautious about global theme styles that may affect local pagination, dialog, or table layouts. - -### Problem-solving Workflow - -- For repeated UI issues, analyze in this order: - 1. interface/request data and returned structure - 2. component logic and render conditions - 3. theme and style coverage/conflicts - 4. then decide whether a rewrite is necessary -- Do not jump straight to a rewrite before checking interface behavior and style interference. - -### Execution Workflow Rules - -- When modifying a feature, locate it in this order: usage location, component definition, API definition, then at least one similar implementation in the project. -- For common UI features such as pagination, dialogs, and tables, align with an existing similar implementation before making changes. -- Prefer componentization. If a page or Vue SFC is already large, or a block has a clear independent responsibility, split it into components instead of continuing to extend the same file. -- For very long files such as complex page-level `index.vue` files, treat further component splitting as the default direction rather than the exception. -- Before editing large files or complex Vue SFCs, first read the target context; if a replacement fails once, do not repeat the same replacement blindly, and instead expand the context or switch to smaller targeted edits. -- After UI or interaction changes, verify not only lint status for edited files but also render conditions, interface fields, and possible style impact. -- If the same issue is not resolved after one attempt, pause and ask the user before continuing with more speculative changes. -- Do not proactively rewrite a component unless the user explicitly asks for a rewrite. -- At the start of a new conversation, read `CLAUDE.md` before making changes. -- When code changes appear not to take effect, check in this order: compile/HMR status, render conditions, API data, then style overrides. -- Turn repeated low-level mistakes into explicit workflow checks and follow those checks in future edits. - -### Environment and Tool Selection Rules - -- Before running environment-dependent commands, first follow the known runtime context already provided by the IDE, such as OS and default shell. -- On Windows projects with PowerShell as the active shell, prefer PowerShell-native commands and scripts by default. -- Do not assume Python, bash, sed, awk, or other non-default tooling is installed locally unless the user or repository explicitly indicates that they are available. -- For reading and editing repository files, prefer dedicated file tools first; use shell-based text replacement only when file tools are not suitable for the change. -- When a replacement fails once, do not keep retrying the same method blindly. Re-read the exact target content and switch to a smaller or more reliable edit strategy that matches the current environment. -- Avoid trial-and-error probing for basic tooling when the available environment is already known from context. - -### Componentization and Structure Rules - -- If a view block has an independent responsibility, prefer extracting it into a component instead of keeping it inside a large page file. -- When a file is already long, or a new feature would further expand responsibilities, proactively split it into components. -- Child components may keep their own local logic when that logic belongs clearly to the child’s responsibility; only shared state and necessary events should stay in the parent. -- For complex pages, small-scale components can stay in `component/`, while larger feature areas may be grouped by responsibility in subdirectories. -- For very long page files, prefer keeping the parent focused on composition, state orchestration, and data flow, while moving feature UI and local behavior into child components. -- When extracting new child components from a large file, move their related local styles with them to avoid continued growth of the parent file. - -### API and Data Handling Rules - -- Follow the project’s common response structure by default, but add moderate component-side compatibility handling when equivalent APIs return slightly inconsistent fields. -- For page-level error handling, use global handling by default, but use page-level or silent handling when the interaction requires local control. -- Prefer a unified parameter-building entry for request params instead of assembling the same parameters across multiple functions. - -### Form and Interaction Rules - -- Follow the project’s existing form behavior style: required fields should be clearly validated on submit, while avoiding unnecessarily disruptive validation during input. -- For shared create/edit forms, initialize, patch, and reset form state through a unified initialization path to avoid stale state. -- Search interactions should behave consistently across button click, Enter key, and clear actions, and should reset to the first page by default. - -### Dialog and Selector Rules - -- Dialogs should clear temporary internal state on close by default; any state that needs to persist should be explicitly provided back by the parent. -- Selector components should follow a consistent pattern: `v-model` for visibility, a default value prop, and a `confirm` event for returning the selected result. -- For temporary selectors and lightweight dialogs, prefer `destroy-on-close`; for more complex stateful forms, decide deliberately rather than applying it blindly. - -### Styling Rules - -- Prefer local scoped style changes first; only modify global theme styles after confirming the issue is truly shared across multiple places. -- When overriding Element Plus internals, prefer local `:deep()` overrides before considering global style changes. -- Use semantic, area-based class names instead of short or overly generic names. - -### Debugging and Validation Rules - -- Minimal temporary debugging is allowed when necessary, but all temporary debugging code must be removed before final delivery. -- Temporary `console` output is acceptable only when debugging is genuinely needed and must be removed before final delivery. -- For UI and interaction changes, verify lint, key render conditions, interface fields, and style impact before considering the task complete. - -### Change Scope and Consistency Rules - -- Prefer the smallest necessary change set, but do not pretend a local-only fix is sufficient when the real root cause is elsewhere in the chain. -- Only fix nearby issues when they are strongly related to the current task; otherwise ask the user before expanding the scope. -- Within the current modification scope, move code toward repository rules when practical, but avoid broad unrelated refactors. - -### Communication and Risk Rules - -- 默认使用中文进行回复、说明、提问与思考表达；如果用户明确要求使用其他语言，再按用户要求切换。 -- Before changing code, confirm with the user when a change involves a rewrite, global side effects, unclear requirements, or a second attempt that still has not solved the issue. -- After changes, explain what changed, why it was changed that way, and any remaining risks or points worth confirming. -- When a requirement still depends on a meaningful assumption, ask the user first instead of silently choosing a direction. - -### Repository Memory Rules - -- When collaboration reveals a repeated problem pattern, proactively suggest turning it into an explicit repository rule in `CLAUDE.md`. -- Project-specific experience or pitfall notes may be added when they become necessary, but do not expand them prematurely without clear recurring value. - -### Rule Documentation Style - -- Keep long-term repository rules concise and practical. -- Prefer short rule lists with a small amount of explanation over overly long documentation. - -## 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 `