shop-web/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 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

# 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