ai-coding/deploy-ease-platform
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/develop3' into develop3

Browse Source
This commit is contained in:
dengqichen 2025-10-30 21:29:18 +08:00
commit e38fea962c
1 changed files with 267 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

267
frontend/CLAUDE.md Normal file
View File

@ -0,0 +1,267 @@
# 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