# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Environment Requirements
- **Node.js**: 16.0+ (recommended: Node.js 16 + pnpm 7.30.5)
- **pnpm**: 6.0+

### Common Commands

```bash
# Install dependencies
pnpm install

# Start development server
pnpm dev

# Build for production
pnpm build

# Build for staging
pnpm build:staging

# Preview production build
pnpm preview

# Run type checking
pnpm typecheck

# Run all linters
pnpm lint

# Run individual linters
pnpm lint:eslint    # ESLint with auto-fix
pnpm lint:prettier  # Prettier formatting
pnpm lint:stylelint # Stylelint with auto-fix

# Clean install (removes node_modules and reinstalls)
pnpm clean:cache

# Generate SVG icons
pnpm svgo
```

### API Proxy Configuration
The dev server is configured with a proxy to backend API at `http://localhost:8080`:
- API calls starting with `/dev-api/` are proxied to the backend
- See `vite.config.ts:46-52` for proxy configuration

## Project Architecture

### Technology Stack
- **Frontend Framework**: Vue 3.3.4 with Composition API
- **Language**: TypeScript 5.0.4
- **UI Library**: Element Plus 2.3.6
- **Build Tool**: Vite 4.3.9
- **State Management**: Pinia 2.1.4
- **Router**: Vue Router 4.2.2

### High-Level Structure

```
src/
├── api/                    # API layer - organized by business module
│   ├── ab98/              # Member management APIs
│   ├── cabinet/           # Smart cabinet management APIs
│   ├── common/            # Shared/common APIs
│   ├── qy/                # Enterprise user APIs
│   ├── shop/              # Shop management APIs
│   └── system/            # System administration APIs
├── components/            # Reusable Vue components
├── layout/                # App layout components
├── router/                # Vue Router configuration
│   └── modules/           # Route modules (global, home, error, etc.)
├── store/                 # Pinia state management
│   └── modules/           # Store modules
├── utils/                 # Utility functions
│   └── request.ts         # Axios HTTP client with interceptors
├── views/                 # Page components organized by feature
│   ├── cabinet/           # Smart cabinet management pages
│   ├── shop/              # Shop management pages
│   ├── qy/                # Enterprise management pages
│   ├── system/            # System administration pages
│   └── user/              # User management pages
├── directives/            # Custom Vue directives
├── plugins/               # Vue plugins configuration
└── style/                 # Global styles
```

### Key Configuration Files
- `vite.config.ts`: Vite build configuration with path aliases (@ -> src, @build -> build)
- `tsconfig.json`: TypeScript configuration
- `tailwind.config.js`: Tailwind CSS configuration
- `.eslintrc.js`: ESLint rules
- `.stylelintrc.js`: Stylelint rules

## Core Business Modules

### 1. Smart Cabinet Management (cabinet)
- **柜体管理**: Smart cabinet device management
- **格口管理**: Cabinet cell/compartment management
- **设备操作**: Remote device control
- **MQTT 服务器**: MQTT server management for device communication

Key files:
- `src/api/cabinet/smart-cabinet.ts`
- `src/api/cabinet/cabinet-cell.ts`
- `src/api/cabinet/mqttServer.ts`

### 2. Shop Management (shop)
- **商品管理**: Product management and inventory
- **分类管理**: Product categories
- **订单管理**: Order processing
- **审批中心**: Business approval workflows
- **数据统计**: Analytics dashboard

Key files:
- `src/api/shop/shop.ts`
- `src/api/shop/goods.ts`
- `src/api/shop/order.ts`
- `src/api/shop/stats.ts`

### 3. Enterprise Management (qy)
- **企业用户管理**: Enterprise user management
- **余额管理**: User balance and transaction records

Key files:
- `src/api/qy/qyUser.ts`

### 4. System Administration (system)
- **用户管理**: System user management
- **权限管理**: Role and permission configuration
- **个人中心**: User profile management

Key files:
- `src/api/system/`

### 5. Member Management (ab98)
- **会员信息**: Member profile management
- **会员详情**: Detailed member information

Key files:
- `src/api/ab98/`

## Architecture Patterns

### Request Handling
- Centralized HTTP client: `src/utils/request.ts`
- Request interceptor adds authentication token
- Response interceptor handles errors globally
- API methods return typed responses

### State Management
- Pinia stores organized by feature in `src/store/modules/`
- Includes permission, button权限, system config, and WeChat integration
- Stores can be persisted to localStorage

### Routing
- Dynamic routing based on user permissions
- Static routes in `src/router/modules/`
- Route guards handle authentication and authorization
- Lazy-loaded route components for code splitting

### Component Development
- Composition API with `<script setup>` syntax
- TypeScript interfaces for props and emits
- Reusable components in `src/components/`
- Custom components follow naming conventions (PascalCase)

## Development Best Practices

### Code Style
- **Components**: PascalCase (e.g., `UserProfile.vue`)
- **Files**: kebab-case (e.g., `user-profile.ts`)
- **Variables**: camelCase (e.g., `userName`)
- **Constants**: UPPER_SNAKE_CASE (e.g., `MAX_COUNT`)

### TypeScript Guidelines
- Strict mode is disabled in tsconfig.json for flexibility
- Define interfaces for all API responses
- Use TypeScript generics for typed API calls
- Use `withDefaults` for prop definitions

### Git Workflow
- Husky pre-commit hooks for code quality
- Commit messages follow Conventional Commits format:
  ```
  <type>(<scope>): <subject>
  ```
  Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

## Environment Configuration

### Environment Files
- `.env.development`: Development environment variables
- `.env.staging`: Staging environment variables
- `.env.production`: Production environment variables

### Key Environment Variables
- `VITE_ROUTER_HISTORY`: Router history mode
- `VITE_PORT`: Dev server port
- `VITE_PUBLIC_PATH`: Base path for production builds
- `VITE_API_BASE_URL`: Backend API base URL (in request.ts)

## Build & Deployment

### Build Process
- Vite for bundling and optimization
- Static assets organized by type (js/css/images)
- Source maps disabled in production
- Code splitting and chunk optimization

### Deployment
- Output directory: `dist/`
- Configure server for SPA routing
- Production builds include `serverConfig.json` for server addresses
- See `doc/部署和维护指南.md` for detailed deployment instructions

## Testing
Based on package.json, the project appears to have testing infrastructure in place but specific test commands are not defined. The codebase follows Vue 3 + Vite patterns compatible with:
- Vitest for unit testing
- Vue Test Utils for component testing

## Code Quality Tools

### Linting Stack
- **ESLint**: Code quality with @typescript-eslint
- **Prettier**: Code formatting
- **Stylelint**: CSS/SCSS linting with stylelint-config-standard
- All three are enforced via Husky pre-commit hooks

### Performance Optimization
- Lazy loading for routes and heavy components
- Asset optimization via Vite plugins
- CDN support for third-party libraries
- Tree-shaking for dead code elimination

## Documentation
See the `doc/` directory for detailed documentation:
- `项目说明文档.md`: Project overview and architecture
- `开发指南.md`: Development guide and best practices
- `API接口文档.md`: Complete API documentation
- `部署和维护指南.md`: Deployment and maintenance guide

## Key References
- This project is based on [Pure-Admin](https://github.com/pure-admin/vue-pure-admin)
- Vue 3 Documentation: https://v3.cn.vuejs.org
- Vite Documentation: https://cn.vitejs.dev
- Element Plus Documentation: https://element-plus.org/zh-CN
- Pinia Documentation: https://pinia.vuejs.org