af-mobile-client-vue3 1.3.29 → 1.3.31

package/CLAUDE.md

@@ -1,189 +1,218 @@
-# 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
-
-# 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
-```
-
-## 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
-│   │   └── XOlMap/          # OpenLayers map integration
-│   └── 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`):
-
-- Dynamic form generation from JSON configuration
-- Supports field types: `input`, `datePicker`, `timePicker`, `dateTimeSecondsPicker`, `curDateInput`, `signature`, `images`, `inputs`, `inputColumns`
-- Built-in validation with custom error messages
-- Slot-based extensibility for complex layouts
-- Integration with file upload and signature capture
-
-**XReportGrid Component**:
-
-- Data grid with reporting capabilities
-- Print functionality integration
-- Design mode for form configuration
-
-**XOlMap Component**:
-
-- OpenLayers integration for GIS functionality
-- Location picker with coordinate transformation
-
-### 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
-
-- **Axios-based HTTP client** with interceptors
-- **Request/Response transformers** for v3/v4 API compatibility
-- **Automatic token management** and error handling
-- **Mock server integration** for development
-
-## Development Workflow
-
-### Server Configuration
-
-- Development server runs on port 7190
-- Mock server runs on port 8086
-- Multiple API proxy endpoints configured in `vite.config.ts`
-
-### Build Process
-
-- Code splitting: `third` (node_modules), `views` (business pages)
-- Assets organized in `static/` directory with hashing
-- CSS code splitting disabled for mobile optimization
-- Legacy browser support via `@vitejs/plugin-legacy`
-
-### 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:
-
-- Uses `@micro-zoe/micro-app` for micro-app management
-- Child apps register in `microApps.ts`
-- Supports dynamic loading and routing
-- Unmount function available at `window.unmount`
-
-## 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 type to `generateDefaultRequiredMessage()` function
-2. Add case in `formatConfigToForm()` switch statement
-3. Add template section in the component template
-4. Follow existing patterns for validation and data binding
-
-### 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
-
-- Use the existing HTTP client in `src/utils/http/`
-- Follow v3/v4 API patterns established in the codebase
-- Handle errors consistently with existing patterns
-
-## 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
-
-## 注意事项
-
-- 此项目作为组件库项目 所以没有开启自动引入 不能自动引入 vue 中的 ref/compute 等
-- 此项目为了统一业务项目使用，所以 使用 @af-mobile-client-vue3/ 表示 src 而不是 @/
+# 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.