# CLAUDE.md

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

## Project Overview

This is a Vue 3 mobile client application (`af-mobile-client-vue3`) built as a smart gas system (智慧燃气) mobile application. It serves as a micro-frontend main application with comprehensive business components and dynamic form capabilities.

## Development Commands

```bash
# Install dependencies
pnpm install

# Development server (with mock server on port 8086)
pnpm dev

# Build for production
pnpm build:pro

# Build for development environment
pnpm build:dev

# Lint and type checking
pnpm lint

# Auto-fix linting issues
pnpm lint:fix

# Type checking only
pnpm typecheck

# Version release
pnpm release

# Compress build files
pnpm compress
```

## Technology Stack

- **Vue 3** with Composition API and `<script setup>` syntax
- **TypeScript** for type safety
- **Vite** as build tool (port 7190)
- **Vant 4** as primary UI component library
- **Pinia** for state management with persistence
- **pnpm** as package manager (requires Node.js >=20.19.0)
- **UnoCSS** for atomic CSS utilities
- **@micro-zoe/micro-app** for micro-frontend architecture

## Code Style & Standards

From `.cursorrules`:

- Use Composition API and `<script setup>` syntax
- Component names: PascalCase (e.g., `UserProfile`)
- Variables: camelCase (e.g., `userName`)
- Boolean variables: use `is/has/should` prefix (e.g., `isLoading`)
- Event handlers: use `handle` prefix (e.g., `handleSubmit`)
- CSS classes: kebab-case (e.g., `user-profile`)
- **Must explicitly import Vant components** - auto-import is disabled for this component library project
- Use `interface` for type definitions, `type` for unions/intersections
- Props must specify types

## Architecture

### Directory Structure

```
src/
├── components/
│   ├── core/           # Core UI components (NavBar, Tabbar, Uploader)
│   ├── data/           # Business data components
│   │   ├── XReportForm/     # Dynamic form with JSON configuration
│   │   ├── XReportGrid/     # Data grid with reporting
│   │   └── XForm/             # General form components
│   └── layout/         # Layout components
├── stores/             # Pinia state management
├── utils/              # Utility functions
├── views/              # Page components
├── router/             # Vue Router configuration
└── api/               # API layer
```

### Key Business Components

**XReportForm Component** (`src/components/data/XReportForm/index.vue`):

- **Configuration-driven form engine**: Supports two modes - traditional config and pure JSON mode
- **Field types**: `input`, `datePicker`, `timePicker`, `dateTimeSecondsPicker`, `curDateInput`, `signature`, `images`, `inputs`, `inputColumns`
- **Slot-based extensibility**: Advanced slot system with `slotsDeclare` mechanism for complex layouts
- **Deep object binding**: Support for nested data structures using `@@@` separator syntax
- **Dynamic validation**: Built-in field validation with custom error messages
- **Mobile-optimized**: Full Vant UI integration with touch-friendly controls

**XReportGrid Component** (`src/components/data/XReportGrid/XReport.vue`):

- **Dual-mode operation**: Design mode for configuration, Display mode for data presentation
- **Dynamic cell rendering**: Support for various cell types including custom function execution
- **Advanced table features**: Complex rowspan/colspan handling with automatic layout algorithms
- **Export capabilities**: PDF generation, print functionality, and data export
- **Component registry**: Provider pattern for dynamic child component management

### State Management

- **Pinia stores** with persistence via `pinia-plugin-persistedstate`
- **User store**: Authentication, permissions, user data
- **Settings store**: Application configuration
- **Route cache store**: Performance optimization

### API Layer

- **Service architecture**: RESTful wrapper with request/response transformation in `src/services/`
- **V3/V4 API compatibility**: Automatic response format handling across API versions
- **Authentication**: Token-based auth with automatic refresh and crypto-js encryption
- **Mock server integration**: Vite-based mock development server on port 8086
- **Configuration management**: Dynamic API configuration retrieval and caching

### Expression and Logic Engine

- **Custom expression system** (`src/expression/`): Full expression evaluation engine
- **LogicRunner framework**: Business logic execution with plugin architecture
- **Dynamic behavior**: Used in XReportForm and XReportGrid for runtime functionality

## Development Workflow

### Server Configuration

- **Development server**: Port 7190 with hot reload and Vue DevTools
- **Mock server**: Port 8086 with full API mocking via `vite-plugin-mock-dev-server`
- **API proxies**: Multiple endpoints configured in `vite.config.ts` for v3/v4 compatibility
- **Allowed hosts**: Configured for `.aofengcloud.com` domain access

### Build Process

- **Code splitting**: `third` (node_modules), `views` (business pages) for optimal loading
- **Asset organization**: Static files in hashed directories for cache management
- **Mobile optimization**: CSS code splitting disabled, PWA capabilities enabled
- **Legacy support**: Vite legacy plugin for older browser compatibility
- **Compression**: Gzip compression for production builds (threshold: 10KB)

### Git Hooks

- Pre-commit: `pnpm lint-staged` (ESLint auto-fix)
- Commit message: `pnpm commitlint` (conventional commits)

## Micro-Frontend Integration

This is a **main application** for micro-frontend architecture using `@micro-zoe/micro-app`:

- **Route flattening**: Child app routes are automatically flattened for compatibility
- **Component isolation**: Each micro-app maintains separate component registry
- **Custom element registration**: Vite configured to handle `<micro-app>` tags
- **Global unmount**: Window-level unmount function for clean micro-app teardown
- **Child app registration**: Register new micro-apps in `microApps.ts` configuration
- **Environment detection**: Automatic detection when running as child vs main app

## Mobile-Specific Features

- **@vant/touch-emulator** for desktop development
- **postcss-mobile-forever** for viewport handling
- **vite-plugin-pwa** for PWA capabilities
- **VConsole** for mobile debugging
- Dark mode support throughout the application

## Common Patterns

### Adding New Field Types to XReportForm

1. **Add field type support**: Update `generateDefaultRequiredMessage()` function in component
2. **Configure rendering**: Add case in `formatConfigToForm()` switch statement for field processing
3. **Template implementation**: Add corresponding template section with Vant component integration
4. **Data binding**: Follow `@@@` deep object binding patterns for nested data structures
5. **Validation**: Implement field-specific validation rules using existing validation framework

### Component Development

- Use `<script setup lang="ts">` syntax
- Explicitly import Vant components
- Define props with TypeScript interfaces
- Use `defineEmits` for events
- Follow existing component structure patterns

### API Integration

- **HTTP client**: Use service layer in `src/services/` rather than direct HTTP calls
- **V3/V4 compatibility**: Follow established patterns for API version handling in service files
- **Error handling**: Use consistent error patterns with user feedback integration
- **Authentication**: Leverage automatic token management and refresh mechanisms
- **Configuration**: Access dynamic API configuration through common service layer

### Micro-Frontend Development

- **Child app creation**: Derive from existing project structure, update app identifiers
- **Route registration**: Add child app routes to main app's `microApps.ts` configuration
- **Isolation**: Maintain component and state isolation between micro-apps
- **Communication**: Use established patterns for parent-child communication

## Testing & Quality

- **ESLint** with `@antfu/eslint-config`
- **TypeScript** strict mode
- **Vue TSC** for type checking
- **Commitlint** for commit message standards
- **Lint-staged** for pre-commit hooks

## 注意事项 (Important Notes)

- **No auto-import**: This project does NOT use auto-import plugins - you MUST explicitly import all Vue APIs (`ref`, `computed`, etc.) and Vant components
- **Path aliases**: Use `@af-mobile-client-vue3/` to reference `src/` directory (not `@/`) for business project consistency
- **Component library approach**: Explicit imports required for all dependencies to maintain clear component boundaries

# important-instruction-reminders

Do what has been asked; nothing more, nothing less.
NEVER create files unless they're absolutely necessary for achieving your goal.
ALWAYS prefer editing an existing file to creating a new one.
NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested by the User.