docs(frontend): 更新前端开发指南文档

- 补充了详细的命令说明和使用场景
- 完善了架构概述中的技术栈描述
- 重新组织了关键目录结构的说明
- 增强了API集成部分的配置细节
- 扩展了组件架构和状态管理的描述
- 新增了静态导出和部署相关的配置说明
- 完善了环境变量和Bun配置的文档
- 添加了代码生成工作流的详细步骤
- 增加了样式系统和错误处理的说明
- 补充了OpenTelemetry集成和部署相关内容

frontend/CLAUDE.md

@@ -5,99 +5,136 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Development Commands
 
 ### Dependency Management
-- `bun install` - Install dependencies
+- `bun install` - Install dependencies using Bun package manager
 - `bun add <package>` - Add dependency
 - `bun remove <package>` - Remove dependency
 - `bun update` - Update dependencies
 
 ### Core Development
 - `bun run dev` - Start development server with Turbopack
-- `bun run build` - Build production version
+- `bun run build` - Build production version (static export)
+- `bun run build:spa` - Build SPA version with output to `out/` directory
 - `bun run start` - Start production server
+- `bun run serve` - Serve static files from `out/` directory using npx serve
 - `bun run lint` - Run ESLint checks
-- `bun run serve` - Serve static files from `out/` directory
 
 ### API Generation
-- `bun run generate:api` - Generate API client code from OpenAPI spec
+- `bun run generate:api` - Generate API client code from OpenAPI spec at `http://localhost:8000/openapi.json`
 - `bun run generate:api:watch` - Generate API client with watch mode
 
 ## Architecture Overview
 
 ### Tech Stack
-- **Framework**: Next.js 15 with App Router
-- **UI**: React 18, Apple-style design with custom components
-- **Styling**: Tailwind CSS + Less for complex styles
+- **Framework**: Next.js 15 with App Router, configured for static export (SPA mode)
+- **UI**: React 18, Apple-style design with custom components and animations
+- **Styling**: Tailwind CSS + Sass/SCSS for complex styles
 - **State Management**: React Context + TanStack Query for server state
 - **Forms**: React Hook Form + Zod validation
-- **HTTP**: Axios with enhanced client
-- **Animation**: Framer Motion
-- **TypeScript**: Full type safety
+- **HTTP**: Axios with enhanced client featuring retry logic and loading states
+- **Animation**: Framer Motion + custom animated UI components
+- **TypeScript**: Full type safety with strict configuration
+- **Package Manager**: Bun with Chinese npm mirror configuration
 
 ### Key Directories
 
-- `src/app/` - Next.js App Router pages
-- `src/components/` - Reusable components
-  - `dashboard/` - Main dashboard components
-  - `forms/` - Form components with validation
-  - `layout/` - Layout and theme components
-  - `ui/` - Base UI components (Apple-style)
-  - `animate-ui/` - Animated UI components
-- `src/lib/` - Utility libraries
-  - `api/` - API client and generated types
-  - `contexts/` - React contexts (theme, refresh)
-  - `hooks/` - Custom React hooks
-  - `telemetry/` - OpenTelemetry integration
+#### App Structure (`src/app/`)
+- `layout.tsx` - Root layout with theme providers and telemetry
+- `page.tsx` - Main dashboard page
+- `orders/` - Order management pages
+
+#### Components (`src/components/`)
+- `dashboard/` - Main dashboard components (gift cards, link management, statistics)
+- `forms/` - Form components with validation (data upload, configuration)
+- `layout/` - Layout and theme components (providers, navigation)
+- `ui/` - Base UI components (Apple-style buttons, inputs, theme toggle)
+- `animate-ui/` - Animated UI components (tooltips, progress, text effects)
+
+#### Library (`src/lib/`)
+- `api/` - API client and generated types from OpenAPI spec
+  - `enhanced-axios-client.ts` - Enhanced HTTP client with retry logic and error handling
+  - `generated/` - Auto-generated API hooks and schemas using Orval
+- `contexts/` - React contexts (theme, refresh, global state)
+- `hooks/` - Custom React hooks
+- `providers/` - React Query provider and other context providers
+- `telemetry/` - OpenTelemetry integration for monitoring
+- `config.ts` - Application configuration
 
 ### API Integration
-- API client code generated automatically from OpenAPI spec at `http://localhost:8000/openapi.json`
-- Generated files in `src/lib/api/generated/` with schemas and React Query hooks
-- Enhanced axios client with interceptors in `src/lib/api/enhanced-axios-client.ts`
+- **Code Generation**: Uses Orval to generate React Query hooks and TypeScript types from OpenAPI spec
+- **Generated Files**: Located in `src/lib/api/generated/` with separate directories for endpoints and schemas
+- **Enhanced Client**: Custom axios client with retry logic, loading states, and comprehensive error handling
+- **Configuration**: `orval.config.ts` defines generation settings and mutator overrides
+- **Source**: Auto-generated from `http://localhost:8000/openapi.json`
 
 ### Component Architecture
-- Apple-style design system with custom components
-- Theme switching with `next-themes` and custom context
-- Global refresh system with context provider
-- Loading states and error handling built into components
+- **Apple Design System**: Custom components following Apple's Human Interface Guidelines
+- **Theme System**: Dual theme providers (next-themes + custom context) for enhanced theme switching
+- **Animation**: Smooth transitions using Framer Motion and custom animated components
+- **Loading States**: Global loading manager integrated with API client
+- **Error Handling**: Comprehensive error handling with user-friendly messages
 
 ### State Management
-- **Global State**: React Context for theme and refresh settings
-- **Server State**: TanStack Query for API data management
-- **Local State**: React hooks for component state
-- **Form State**: React Hook Form with Zod schemas
+- **Global State**: React Context for theme, refresh settings, and UI state
+- **Server State**: TanStack Query for API data management with caching and synchronization
+- **Local State**: React hooks for component state management
+- **Form State**: React Hook Form with Zod schemas for validation
 
 ### Key Features
-- Real-time dashboard with auto-refresh
-- File upload and data management
-- Order and task monitoring
-- Link management system
-- Apple-style UI with animations
-- OpenTelemetry telemetry integration
+- **Real-time Dashboard**: Auto-refreshing statistics and monitoring
+- **File Management**: Batch upload and processing of data files
+- **Order Monitoring**: Real-time order and task tracking
+- **Link Management**: Weight-based link rotation and management system
+- **Theme Switching**: Apple-style theme toggle with smooth transitions
+- **OpenTelemetry**: Integrated monitoring and telemetry
+- **Responsive Design**: Mobile-first responsive layout
 
 ## Development Notes
 
 ### Environment Variables
 Required in `.env.local`:
-- `NEXT_PUBLIC_API_URL` - Backend API URL
+- `NEXT_PUBLIC_API_URL` - Backend API URL (e.g., `http://localhost:8000/api`)
 - `NEXT_PUBLIC_ENV` - Environment (development/production)
 - `NEXT_PUBLIC_TELEMETRY_ENDPOINT` - OpenTelemetry endpoint
 
 ### Bun Configuration
-- Uses `bunfig.toml` for configuration
-- Registry set to `https://registry.npmmirror.com` (Chinese mirror)
-- Network access allowed for scripts
+- **Registry**: Uses Chinese npm mirror (`https://registry.npmmirror.com`)
+- **Network Access**: Allows scripts to access network resources
+- **Configuration**: `bunfig.toml` contains Bun-specific settings
 
-### Code Generation
-- Run `bun run generate:api` after backend API changes
-- Uses Orval to generate React Query hooks and TypeScript types
-- Automatically formats output with Prettier
+### Static Export Configuration
+- **Output Mode**: Configured for static export (`output: 'export'`)
+- **SPA Mode**: Trailing slash enabled for SPA routing
+- **Image Optimization**: Disabled for static export compatibility
+- **Deployment**: Outputs to `out/` directory for static hosting
 
-### Styling
-- Primary styling with Tailwind CSS
-- Less for complex styles in `src/styles/less/main.less`
-- Apple design system with custom colors and components
-- Dark/light theme support with smooth transitions
+### Code Generation Workflow
+1. Backend API changes trigger OpenAPI spec updates
+2. Run `bun run generate:api` to regenerate client code
+3. Orval processes OpenAPI spec and generates:
+   - React Query hooks for all endpoints
+   - TypeScript schemas for request/response types
+   - Enhanced client integration with custom axios instance
+4. Prettier automatically formats generated code
 
-### Testing
-- Currently no test framework configured
-- ESLint for code quality
-- TypeScript for type safety
+### Styling System
+- **Tailwind CSS**: Primary styling framework with custom Apple-inspired design tokens
+- **Sass/SCSS**: Complex styles and component-specific stylesheets
+- **Theme Variables**: CSS custom properties for light/dark theme switching
+- **Animation**: Framer Motion for complex animations, CSS transitions for simple effects
+
+### OpenTelemetry Integration
+- **Initialization**: `TelemetryInitializer` component sets up monitoring
+- **Configuration**: Endpoint configurable via environment variables
+- **Performance**: Automatic performance tracking and error reporting
+
+### Error Handling
+- **Global Handler**: Comprehensive error handling in enhanced axios client
+- **User Messages**: User-friendly error messages for different HTTP status codes
+- **Retry Logic**: Automatic retry for network errors and 5xx responses
+- **Loading States**: Global loading manager with subscription support
+
+### Deployment
+- **Static Export**: Fully static SPA deployment compatible with any static hosting
+- **Docker**: Container configuration available in `Dockerfile`
+- **Build Process**: `bun run build:spa` creates optimized static files in `out/` directory
+- **Serve**: Use `bun run serve` for local testing of static build