291 lines
17 KiB
Markdown
291 lines
17 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.
|
||
|
||
## 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)
|