WebAgent/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 a mobile web app template built with Vue 3 ecosystem, using Vite as the build tool. The template is designed for rapid development of mobile web applications with TypeScript support and modern tooling.

## Development Commands

### Core Development

```bash
# Start development server with hot reload
pnpm dev

# Build for development environment
pnpm build:dev

# Build for production environment
pnpm build:pro

# Preview production build locally
pnpm preview
```

### Code Quality

```bash
# Run ESLint checks
pnpm lint

# Fix ESLint issues automatically
pnpm lint:fix

# TypeScript type checking
pnpm typecheck
```

### Release Management

```bash
# Version bump with git commit and tag
pnpm release
```

### Git Hooks

- `pre-commit`: Runs ESLint on staged files via `pnpm lint-staged`

## Architecture

### Directory Structure

```
src/
├── api/               # API endpoint definitions and services
├── assets/            # Static assets (images, icons, fonts)
├── components/        # Global reusable components (auto-imported)
├── composables/       # Vue 3 composables (auto-imported)
├── config/            # Application configuration
├── constants/         # Application constants
├── locales/           # i18n translation files
├── pages/             # Route pages with file-based routing
├── router/            # Vue Router configuration
├── stores/            # Pinia state stores
├── styles/            # Global styles and UnoCSS configuration
├── types/             # TypeScript type definitions
├── utils/             # Utility functions
```

### Key Architectural Patterns

1. **File-Based Routing**: Uses `unplugin-vue-router` for automatic route generation from `src/pages/` directory. Routes are defined using `<route>` custom blocks in SFC files.

2. **Auto-Imports**:
   - Components from `src/components/` are auto-imported via `unplugin-vue-components`
   - Vue 3 Composition API and other utilities are auto-imported via `unplugin-auto-import`
   - Generated type definitions in `src/types/auto-imports.d.ts`

3. **State Management**: Uses Pinia with `pinia-plugin-persistedstate` for persistent storage. Stores are in `src/stores/`.

4. **Styling**: Uses UnoCSS for atomic CSS with Vant UI component library integration. Global styles in `src/styles/`.

5. **Internationalization**: Vue I18n configured with `unplugin-vue-i18n`. Translation files in `src/locales/`.

### Configuration Files

- `vite.config.ts`: Vite configuration with plugins for Vue, UnoCSS, auto-imports, mock server, PWA, etc.
- `tsconfig.json`: TypeScript configuration with path aliases (`@/*`, `~root/*`)
- `uno.config.ts`: UnoCSS configuration with Vant presets
- `eslint.config.ts`: ESLint configuration using `@antfu/eslint-config`

### Development Workflow

1. **Mock Server**: Development server runs on port 3000 with optional mock server on port 8086 (`MOCK_SERVER_PORT=8086`)

2. **Type Safety**: TypeScript with `vue-tsc` for Vue SFC type checking

3. **Mobile Optimization**:
   - Vant UI library for mobile components
   - `vant-touch-emulator` for desktop touch simulation
   - `postcss-mobile-forever` for viewport adaptation
   - `vite-plugin-vconsole` for mobile debugging

4. **PWA Support**: Service worker generation via `vite-plugin-pwa`

## Important Conventions

### File-Based Routing

- Pages go in `src/pages/` directory
- Use `<route>` custom block in SFC files for route metadata:
  ```vue
  <route>
  {
    "name": "home",
    "meta": {
      "title": "Home"
    }
  }
  </route>
  ```

### Component Organization

- Global components in `src/components/` are auto-imported
- Use PascalCase for component file names
- Local components should be colocated with their parent components

### State Management

- Pinia stores in `src/stores/` use `defineStore()` with TypeScript
- Stores automatically persist to localStorage via `pinia-plugin-persistedstate`

### API Layer

- API services in `src/api/` use Axios with interceptors
- Mock data in `mock/` directory with `vite-plugin-mock-dev-server`

### Styling

- Use UnoCSS utility classes primarily
- Global styles in `src/styles/`
- Vant component theming via CSS custom properties

### TypeScript

- Path aliases: `@/*` maps to `src/*`, `~root/*` maps to project root
- Auto-generated type definitions in `src/types/`

## Deployment

- **Netlify**: Zero-config deployment via `netlify.toml`
- **Build Modes**: Separate development (`build:dev`) and production (`build:pro`) builds
- **Environment Variables**: `.env`, `.env.development`, `.env.production` files

## Tools Integration

### VS Code Extensions

- Volar for Vue 3 support
- UnoCSS for CSS utilities
- i18n Ally for translation management
- ESLint for code quality

### Git Hooks

- Pre-commit linting via `simple-git-hooks`