# 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 application built with **Vue 3**, **Vite**, **TypeScript**, and **Vant**. It's a commercial cabinet management system with features including cabinet management, approval workflows, order management, and rental tracking.

## Technology Stack

- **Frontend**: Vue 3 (Composition API), TypeScript (strict mode)
- **UI Library**: Vant (mobile-optimized components)
- **Build Tool**: Vite 6.1
- **State Management**: Pinia
- **Routing**: Vue Router with hash/history mode
- **HTTP Client**: Axios with interceptors
- **CSS Framework**: UnoCSS (atomic CSS)
- **Testing**: Vitest + Happy DOM
- **Linting**: ESLint with @antfu/eslint-config
- **Package Manager**: pnpm

## Common Commands

```bash
# Install dependencies
pnpm i

# Start development server (port 3333, opens browser)
pnpm dev

# Build for staging environment
pnpm build:staging

# Build for production (includes zip)
pnpm build

# Preview production build
pnpm preview

# Lint and auto-fix code
pnpm lint

# Run unit tests
pnpm test
```

## Environment Configuration

Three environment files exist:
- `.env.development` - Development settings
- `.env.staging` - Staging settings
- `.env.production` - Production settings

Key environment variables:
- `VITE_BASE_URL` - API base URL
- `VITE_PUBLIC_PATH` - Public path for deployment
- `VITE_ROUTER_HISTORY` - Router mode (`hash` or `history`)

## Path Aliases

- `@/` - src directory
- `@@/` - src/common directory
- `@img/` - src/assets/images directory

## Code Architecture

### Entry Point (`src/main.ts`)
Application bootstrapping:
1. Creates Vue app instance
2. Installs plugins (global components, custom directives)
3. Mounts app after router is ready

### Routing (`src/router/`)
- **index.ts**: Main router configuration with two route groups:
  - `systemRoutes`: Error pages (403, 404)
  - `routes`: Business routes (cabinet, approval, orders, rentals, products)
  - Each route includes layout config (navbar, tabbar) and metadata
- **guard.ts**: Route navigation guards for authentication and permission checks

### HTTP Client (`src/http/axios.ts`)
- Axios instance with request/response interceptors
- Automatic token handling via cookies
- Standardized error handling for HTTP status codes
- Business logic codes (0 = success, 401 = unauthorized)

### State Management (`src/pinia/`)
Pinia stores for application state. Check `src/pinia/stores/` for store implementations.

### API Layer (`src/common/apis/`)
Organized by business domain:
- `ab98/` - AB98 login integration
- `approval/` - Approval workflow APIs
- `cabinet/` - Cabinet management APIs
- `manage/` - Product management APIs
- `shop/` - Shop-related APIs
- `users/` - User management APIs

### Utilities (`src/common/`)
- `utils/` - Helper functions (cache, datetime, validation, permissions, wx)
- `composables/` - Vue composables (watermark, grayscale, dark mode)
- `components/` - Shared components
- `constants/` - Application constants

### Plugins (`src/plugins/`)
- `index.ts` - Plugin registration
- `console.ts` - VConsole integration for mobile debugging
- `permission-directive.ts` - v-permission directive for button-level permissions

## Code Style & Linting

- **ESLint Config**: @antfu/eslint-config with custom rules
- **Indentation**: 2 spaces
- **Quotes**: Double quotes
- **Semicolons**: No
- **Formatting**: ESLint handles formatting automatically
- **Import Sorting**: Enforced via ESLint (perfectionist/sort-imports)
- **Vue SFC Order**: [script, template, style]

**Important**:
- Disable Prettier in VS Code settings (already configured)
- ESLint auto-fixes on save
- Stylistic rules are silently enforced

## Testing

Tests use **Vitest** with **Happy DOM** environment:
- Test files: `tests/**/*.test.{ts,js}`
- Components use `@vue/test-utils`
- Example test: `tests/demo.test.ts`

## Build Configuration (`vite.config.ts`)

- **Port**: 3333 (auto-opens browser)
- **Proxy**: `/api/v1` → Apifox mock server
- **Legacy Support**: @vitejs/plugin-legacy enabled for older browsers
- **Manual Chunks**: Vue ecosystem packages separated
- **SVG Handling**: vite-svg-loader for importing SVGs as components
- **Auto Imports**: unplugin-auto-import for Vue/Vue Router/Pinia APIs
- **Component Imports**: unplugin-vue-components with VantResolver

## Mobile-Specific Features

1. **Touch Emulator**: @vant/touch-emulator (desktop testing)
2. **PX to VW**: PostCSS plugin for mobile viewport adaptation
3. **VConsole**: Mobile debugging console (src/plugins/console.ts)
4. **Viewport**: Mobile-first responsive design with px→vw conversion
5. **Atomic CSS**: UnoCSS for utility-first styling

## Development Tips

- **Component Auto-Import**: Vant components auto-import, no manual imports needed
- **Keep Alive**: Some routes use `keepAlive: true` for route caching
- **Route Caching**: Configured in Pinia store (src/pinia/stores/keep-alive.ts)
- **Watermark**: Defensive watermarking composable (src/common/composables/useWatermark.ts)
- **Theme**: Dark mode support via CSS variables

## Key Business Modules

1. **Cabinet Management** (`/cabinet`) - Cabinet control interface
2. **Approval System** (`/approval/*`) - Workflow approval processes
3. **Order Management** (`/order*`) - Order listing and details
4. **Product Catalog** (`/product/*`) - Product browsing and checkout
5. **Rental Tracking** (`/rental-list`) - Cabinet rental management
6. **User Profile** (`/me`) - User account management
7. **AB98 Login** (`/ab98`) - External authentication

## VS Code Configuration

Recommended extensions (`.vscode/extensions.json`):
- vue.volar (Vue language support)
- dbaeumer.vscode-eslint (ESLint integration)
- antfu.unocss (UnoCSS support)
- vitest.explorer (Test runner)

Configured settings:
- Use workspace TypeScript version
- Disable default formatter, use ESLint
- Auto-fix ESLint on save
- Disable stylistic rule notifications (but still auto-fix)

## Commit Message Convention

Use conventional commits:
- `feat`: New feature
- `fix`: Bug fix
- `perf`: Performance improvement
- `refactor`: Code refactoring
- `docs`: Documentation
- `types`: Type changes
- `test`: Unit tests
- `ci`: CI/CD
- `revert`: Revert changes
- `chore`: Maintenance tasks