deploy-ease-platform/frontend/CLAUDE.md

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

# 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 format with error handling
• Error Handling: Global error handling with toast notifications
• Token Expiration: Auto-logout on 401 with localStorage cleanup

Example:

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):

// 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

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

// 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:

// 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:

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

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

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