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 (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

AI Skills

本项目已全局安装 gstack 和 Superpowers 两组技能（skill），通过斜杠命令调用。

gstack — 浏览器验证与发布

负责 QA 测试、浏览器自动化、安全审计、代码审查和发布部署。

阶段	命令	功能
审查	/gstack-review	代码审查，自动修复明显问题，标记完整性缺口
	/gstack-cso	安全审计（OWASP Top 10 + STRIDE），含漏洞验证
QA 测试	/gstack-qa <url>	打开浏览器进行功能测试，发现 bug 并自动修复
	/gstack-qa-only <url>	仅检测并报告 bug，不修改代码
	/gstack-browse	AI 浏览网页内容（通过 Playwright + 系统 Chrome）
	/gstack-scrape	抓取网页内容
性能	/gstack-benchmark	页面加载性能基准测试
	/gstack-canary	部署后监控：控制台错误、性能回归、页面故障
发布	/gstack-ship	同步主分支、运行测试、推送、创建 PR
	/gstack-land-and-deploy	合并 PR、等待 CI、部署、验证生产环境
诊断	/gstack-investigate	系统性根因调试
	/gstack-retro	迭代回顾分析

浏览器功能依赖 Playwright，已配置使用系统 Chrome（C:\Program Files\Google\Chrome\Application\chrome.exe），无需额外下载浏览器。

Superpowers — 思考与计划

负责头脑风暴、方案设计、计划编写与执行、系统性调试。

阶段	命令	功能
构思	/sp-brainstorm	交互式头脑风暴，梳理需求和方案
	/sp-using-superpowers	Superpowers 使用指南
计划	/sp-write-plan	编写实现计划
	/sp-execute-plan	按批次执行计划
开发	/sp-subagent-dev	子代理驱动开发：规范→审查→实现→验证
	/sp-tdd	测试驱动开发工作流
	/sp-dispatch-agents	并行分发子代理任务
调试	/sp-debug	系统性调试方法论
审查	/sp-request-review	请求代码审查
	/sp-receive-review	接收并处理审查反馈
完成	/sp-verify	完成前验证检查
	/sp-finish-branch	完成开发分支
工具	/sp-write-skills	编写自定义 skill
	/sp-git-worktrees	Git 工作树使用指南

工作流建议

推荐开发流程按此顺序使用两组 skill：

/sp-brainstorm          →  梳理需求
/sp-write-plan          →  编写实现计划
(编码实现)
/gstack-review          →  代码审查
/gstack-qa <url>        →  QA 测试
/gstack-cso             →  安全检查
/gstack-ship            →  发布

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)