docs: 添加 CLAUDE.md 开发指南文件
- 创建项目开发指南文档 - 添加开发命令说明 - 描述项目架构和目录结构 - 说明 API 架构和状态管理方式 - 提供开发注意事项和常见模式 - 配置环境变量和代码质量工具说明
This commit is contained in:
danial
163
CLAUDE.md
Normal file
163
CLAUDE.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a Vue 3 frontend application built with Arco Design Pro, TypeScript, and Vite. The project is a management system for various card/account services including Apple Card, JD accounts, Walmart accounts, and T-Mall game accounts.
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Development server
|
||||
pnpm dev
|
||||
|
||||
# Build for production
|
||||
pnpm build
|
||||
|
||||
# Type checking
|
||||
pnpm type:check
|
||||
|
||||
# Linting and formatting
|
||||
pnpm lint # Run all linting checks
|
||||
pnpm lint:fix # Fix all linting issues
|
||||
pnpm eslint # ESLint only
|
||||
pnpm eslint:fix # Fix ESLint issues
|
||||
pnpm prettier # Check formatting
|
||||
pnpm prettier:fix # Fix formatting
|
||||
pnpm stylelint # Stylelint only
|
||||
pnpm stylelint:fix # Fix style issues
|
||||
|
||||
# API generation
|
||||
pnpm generate:api # Generate TypeScript API client from OpenAPI spec
|
||||
|
||||
# Clear cache
|
||||
pnpm clean:cache # Clear eslint cache and reinstall
|
||||
```
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Stack
|
||||
|
||||
- **Framework**: Vue 3 with Composition API
|
||||
- **UI Library**: Arco Design Vue
|
||||
- **State Management**: Pinia
|
||||
- **Router**: Vue Router 4
|
||||
- **Data Fetching**: TanStack Vue Query + Axios
|
||||
- **Build Tool**: Vite
|
||||
- **Language**: TypeScript
|
||||
- **Package Manager**: pnpm
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── api/ # API layer with manual and generated clients
|
||||
│ ├── generated/ # Auto-generated API clients from OpenAPI
|
||||
│ └── *.ts # Manual API definitions for different services
|
||||
├── components/ # Reusable Vue components
|
||||
│ ├── navbar/ # Navigation bar components
|
||||
│ ├── tab-bar/ # Tab navigation
|
||||
│ ├── menu/ # Menu components
|
||||
│ └── ...
|
||||
├── views/ # Page components organized by feature
|
||||
│ ├── dashboard/ # Dashboard pages
|
||||
│ ├── login/ # Authentication pages
|
||||
│ ├── merchant/ # Merchant management
|
||||
│ ├── card-*/ # Various card management (apple, jd, walmart, etc.)
|
||||
│ └── user-center/ # User management
|
||||
├── store/ # Pinia stores
|
||||
│ └── modules/ # Separate store modules (app, user, tab-bar)
|
||||
├── router/ # Vue Router configuration
|
||||
│ ├── routes/ # Route definitions
|
||||
│ └── guard/ # Route guards
|
||||
├── utils/ # Utility functions
|
||||
├── types/ # TypeScript type definitions
|
||||
├── hooks/ # Vue 3 composables
|
||||
├── plugins/ # Vue plugins (TanStack Query setup)
|
||||
└── layout/ # Layout components
|
||||
```
|
||||
|
||||
### API Architecture
|
||||
|
||||
The project uses a dual API approach:
|
||||
|
||||
1. **Manual API definitions** in `src/api/*.ts` for specific services
|
||||
2. **Generated API client** from OpenAPI spec in `src/api/generated/`
|
||||
|
||||
API base URL is configured via environment variables:
|
||||
|
||||
- Development: `http://127.0.0.1:12401`
|
||||
- Production: Set in `.env.production`
|
||||
|
||||
### State Management
|
||||
|
||||
Uses Pinia with modular stores:
|
||||
|
||||
- `useAppStore` - Application-wide settings
|
||||
- `useUserStore` - User authentication and profile
|
||||
- `useTabBarStore` - Tab navigation state
|
||||
|
||||
### Authentication
|
||||
|
||||
- JWT token-based authentication stored in local storage
|
||||
- Automatic token refresh via response interceptors
|
||||
- Route guards protect authenticated pages
|
||||
- Token expiration handling with user prompts
|
||||
|
||||
### Key Features
|
||||
|
||||
- Multi-service card/account management platform
|
||||
- Real-time dashboard with charts (ECharts integration)
|
||||
- Role-based access control
|
||||
- Responsive design with Arco Design components
|
||||
- CodeMirror integration for code editing
|
||||
- Milkdown integration for rich text editing
|
||||
|
||||
## Development Notes
|
||||
|
||||
### API Generation
|
||||
|
||||
The project uses OpenAPI Generator to create TypeScript clients:
|
||||
|
||||
```bash
|
||||
pnpm generate:api
|
||||
```
|
||||
|
||||
This generates clients from `http://127.0.0.1:12401/api.json`
|
||||
|
||||
### Component Registration
|
||||
|
||||
Global components are auto-registered via `src/components/index.ts`
|
||||
|
||||
### Path Aliases
|
||||
|
||||
- `@/*` maps to `src/*`
|
||||
- `@config/*` maps to `config/*`
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
Development settings in `.env.development`, production in `.env.production`
|
||||
|
||||
### Code Quality
|
||||
|
||||
- ESLint for JavaScript/TypeScript linting
|
||||
- Stylelint for CSS/Less linting
|
||||
- Prettier for code formatting
|
||||
- Husky for Git hooks
|
||||
- Lint-staged for pre-commit checks
|
||||
- Commitlint for conventional commits
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### API Calls
|
||||
|
||||
Use generated API clients or manual definitions from `src/api/`. All calls go through axios interceptors for auth handling.
|
||||
|
||||
### Component Structure
|
||||
|
||||
Follow Vue 3 Composition API patterns with `<script setup>` syntax. Use Arco Design components for UI consistency.
|
||||
|
||||
### State Management
|
||||
|
||||
Create Pinia stores for feature-level state that needs to be shared across components. Use TanStack Query for server state management.
|
||||
Reference in New Issue
Block a user