diff --git a/.claude/settings.local.json b/.claude/settings.local.json index c14d84d..7d976d8 100644 --- a/.claude/settings.local.json +++ b/.claude/settings.local.json @@ -1,7 +1,8 @@ { "permissions": { "allow": [ - "Bash(mkdir:*)" + "Bash(mkdir:*)", + "Bash(tree -L 3 -I 'node_modules|dist')" ], "deny": [], "ask": [] diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..67bc5b1 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,193 @@ +# 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