# CLAUDE.md

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

## Project Overview

Deploy Ease Platform is a modern enterprise deployment management system frontend built with React 18, TypeScript, and Vite. It provides a comprehensive UI for managing applications, workflows, deployments, servers, and system configurations.

## Tech Stack

- **Framework**: React 18 + TypeScript 5.3
- **Build Tool**: Vite 5.x
- **Routing**: React Router 6
- **State Management**: Redux Toolkit
- **UI Components**: Radix UI + Ant Design + shadcn/ui
- **Styling**: TailwindCSS 3.x
- **Forms**: React Hook Form + Zod validation
- **HTTP Client**: Axios (with centralized request handler in `src/utils/request.ts`)
- **Code Editor**: Monaco Editor
- **Flow Visualization**: XYFlow + ReactFlow + Dagre
- **Form Builder**: @react-form-builder libraries

## Development Commands

```bash
# Install dependencies
pnpm install

# Start development server (runs on http://localhost:3000)
pnpm dev

# Build for production (TypeScript + Vite)
pnpm build

# Lint code (ESLint for .ts, .tsx files)
pnpm lint

# Preview production build locally
pnpm preview

# Compile page generator script
npx tsc -p scripts/tsconfig.json

# Run page generator (interactive mode)
node dist/scripts/generate-page.js

# Run page generator (with CLI arguments)
node dist/scripts/generate-page.js <moduleName> "<displayName>" "<apiEndpoint>"
```

## High-Level Architecture

### Directory Structure

```
src/
├── components/          # Reusable components
│   └── ui/             # Radix UI + shadcn/ui component library
├── pages/              # Page components (organized by feature module)
│   ├── Dashboard/      # Dashboard and overview
│   ├── Deploy/         # Deployment features (applications, deployments, servers, etc.)
│   ├── System/         # System management (users, roles, menus, departments, etc.)
│   ├── Workflow/       # Workflow engine (design, instance, monitoring)
│   ├── Form/           # Form management system
│   ├── LogStream/      # Log streaming and viewing
│   └── Login/          # Authentication
├── layouts/            # Layout components (BasicLayout, etc.)
├── router/             # React Router configuration (index.tsx)
├── store/              # Redux state management (user slice, etc.)
├── services/           # API service layer (weather.ts, etc.)
├── utils/              # Utility functions
│   ├── request.ts      # Axios HTTP client with interceptors and error handling
│   ├── table.ts        # Table-related utilities
│   ├── page.ts         # Page-related utilities
│   └── jsonSchemaUtils.ts
├── hooks/              # Custom React hooks (useTableData, usePageData, etc.)
├── types/              # TypeScript type definitions
├── config/             # Configuration files (icons, etc.)
└── main.tsx            # Application entry point
```

### Architecture Patterns

#### 1. **Page Structure**
Each feature page follows a consistent pattern:
```
pages/[Feature]/[Module]/
├── List/
│   ├── index.tsx           # Main list component
│   ├── components/         # Page-specific components (modals, etc.)
│   ├── service.ts          # API service calls
│   ├── types.ts            # TypeScript interfaces
│   └── schema.ts           # Form validation schemas (Zod)
└── Detail/                 # If applicable
```

#### 2. **API Layer**
All HTTP requests use the centralized `http` client from `src/utils/request.ts`:
- **Request Interceptor**: Automatically adds Bearer token from localStorage
- **Response Interceptor**: Handles standardized Response<T> format with error handling
- **Error Handling**: Global error handling with toast notifications
- **Token Expiration**: Auto-logout on 401 with localStorage cleanup

Example:
```typescript
import http from '@/utils/request';
const data = await http.get<DataType>('/api/endpoint');
const result = await http.post<ResultType>('/api/endpoint', payload);
```

#### 3. **State Management**
Redux Toolkit is used minimally for global state (currently just user state):
```typescript
// src/store/userSlice.ts - User authentication and info
// Access via: useSelector((state: RootState) => state.user)
```

Form-level state uses React Hook Form (not Redux) for better performance and reduced boilerplate.

#### 4. **Routing**
React Router 6 with lazy-loaded pages and route guards:
- Private routes check Redux store for user token
- Pages are code-split with Suspense boundaries
- Dynamic menu loading from backend (stored in localStorage)

#### 5. **Form Management**
- **React Hook Form**: Form state and submission
- **Zod**: Schema validation (type-safe)
- **Modal Pattern**: Most forms are in modal dialogs using Radix UI Dialog

#### 6. **Styling**
- **TailwindCSS**: Utility-first CSS framework
- **Ant Design**: Used for complex components (Table, Form, etc.)
- **Radix UI**: Headless UI for modals, dialogs, popover, etc.
- **shadcn/ui**: Pre-built components built on Radix UI

## Key Development Patterns

### HTTP Requests with Error Handling
All HTTP requests automatically:
1. Include Bearer token from localStorage
2. Handle 401 responses (logout and redirect to /login)
3. Display error toast notifications
4. Return typed data or reject with standardized error structure

### Type-Safe API Responses
```typescript
interface Response<T> {
    code: number;
    message: string;
    data: T;
    success: boolean;
}
```

### Common Hooks
- `useTableData`: Fetch and manage table data with pagination
- `usePageData`: Generic page data fetching
- `useSelector` / `useDispatch`: Redux integration

### Form Pattern Example
```typescript
// Use Zod for schema
const schema = z.object({
    name: z.string().min(1),
    email: z.string().email(),
});

// Use React Hook Form with Zod resolver
const form = useForm({
    resolver: zodResolver(schema),
});
```

## Important Files Reference

- **`src/utils/request.ts`**: HTTP client - read this to understand API communication
- **`src/store/index.ts`**: Redux store configuration
- **`src/router/index.tsx`**: All routing configuration
- **`src/layouts/BasicLayout.tsx`**: Main application layout
- **`vite.config.ts`**: Build configuration (Monaco Editor asset copying, code splitting)
- **`tsconfig.json`**: TypeScript configuration with `@/*` path alias

## Code Splitting & Performance

The Vite build config includes manual chunks for the System module to optimize loading:
```typescript
// System pages grouped in separate bundle
manualChunks: {
    'system': [
        './src/pages/System/User/index.tsx',
        './src/pages/System/Role/index.tsx',
        // ... other system pages
    ]
}
```

## Environment & Backend Integration

- **Dev Server**: Runs on port 3000 with Vite HMR
- **API Proxy**: `/api/*` requests proxy to `http://localhost:8080` (configured in vite.config.ts)
- **LocalStorage**: Stores token, userInfo, menus, tenantId for persistence

## Common Tasks

### Adding a New CRUD Page
Use the page generator:
```bash
node dist/scripts/generate-page.js myFeature "My Feature" "/api/v1/my-feature"
```

This generates complete page structure with types, schema, service, and components.

### Making an API Call
```typescript
import http from '@/utils/request';

// GET request
const users = await http.get<User[]>('/api/users');

// POST with data
const newUser = await http.post<User>('/api/users', userData);

// PUT/DELETE
await http.put<User>('/api/users/1', updatedData);
await http.delete('/api/users/1');

// File upload
await http.upload('/api/upload', file);

// File download
await http.download('/api/export', 'export.xlsx');
```

### Form Validation with Zod
```typescript
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

const schema = z.object({
    username: z.string().min(1, 'Required'),
    email: z.string().email('Invalid email'),
});

const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: zodResolver(schema),
});
```

## Known Patterns & Conventions

1. **Prefixes**: Type files are named `types.ts`, validation schemas `schema.ts`, API services `service.ts`
2. **Components**: UI components in `components/ui/`, page-specific components in page folders
3. **Async Operations**: Use async/await, error handling via request interceptor
4. **Imports**: Use `@/*` path alias extensively
5. **Chinese Locale**: Ant Design configured for zh_CN, toast messages in Chinese
6. **Modules**: Pages are organized by business module first, then by feature (List, Detail, Design, etc.)

## Notes for Future Development

- The page generator tool is powerful for rapid CRUD page creation
- Monaco Editor assets need to be copied at build time (see vite.config.ts)
- Token authentication is automatically handled; focus on feature logic
- All error handling is centralized; individual components don't need error boundaries for HTTP calls
- Form state is separate from Redux; Redux only for user/auth data
- The architecture supports adding new Redux slices as the app grows