feat(localization): Add en/vi language
This commit is contained in:
Tran Anh Tuan
323
CLAUDE.md
Normal file
323
CLAUDE.md
Normal file
@@ -0,0 +1,323 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is a React-based **Ship Monitoring System** (Hệ thống giám sát tàu cá) built with **UmiJS Max** framework for Mobifone. The application provides real-time monitoring of fishing vessels with GPS tracking, alarm management, and trip logging capabilities.
|
||||
|
||||
**Domain**: Maritime & Fishing Industry
|
||||
**Target Users**: Fishing vessel operators and monitoring centers
|
||||
**Language**: Vietnamese (Primary) with English development comments
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Core Framework
|
||||
- **UmiJS Max 4.5.0** - Enterprise-level React application framework
|
||||
- **React 18** - UI library with hooks and functional components
|
||||
- **TypeScript** - Type-safe JavaScript
|
||||
- **Ant Design 5.x** - UI component library with Pro Components
|
||||
- **TailwindCSS** - Utility-first CSS framework
|
||||
|
||||
### Mapping & Visualization
|
||||
- **OpenLayers 10.6.1** - Interactive maps and geospatial visualization
|
||||
- **GeoJSON** - Geospatial data format
|
||||
- **WKT (Well-Known Text)** - Geometry representation
|
||||
|
||||
### State Management
|
||||
- **UmiJS Model Plugin** - Global state management
|
||||
- **Event Bus Pattern** - Custom event-driven communication
|
||||
- **React Hooks** - Local state management
|
||||
|
||||
### Development Tools
|
||||
- **Husky + Lint-staged** - Git hooks for code quality
|
||||
- **Prettier** - Code formatting
|
||||
- **ESLint** - Code linting
|
||||
- **pnpm** - Package manager
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
src/
|
||||
├── app.tsx # Global app configuration & layout
|
||||
├── access.ts # User permissions & access control
|
||||
├── constants/ # Application constants & enums
|
||||
│ ├── index.ts # Global constants
|
||||
│ └── enums.ts # Application enums
|
||||
├── models/ # Global state models (UmiJS Model plugin)
|
||||
│ ├── global.ts # Global state
|
||||
│ ├── getTrip.ts # Trip management state
|
||||
│ └── getSos.ts # SOS/Alarm state
|
||||
├── pages/ # Application pages (routes)
|
||||
│ ├── Auth/ # Authentication page
|
||||
│ ├── Home/ # Map monitoring page
|
||||
│ └── Trip/ # Trip management page
|
||||
├── components/ # Reusable UI components
|
||||
│ ├── 403/ # Access denied page
|
||||
│ ├── 404/ # Not found page
|
||||
│ ├── 500/ # Server error page
|
||||
│ └── Footer/ # Footer component
|
||||
├── services/ # API services & controllers
|
||||
│ ├── controller/ # API endpoint controllers
|
||||
│ │ ├── AuthController.ts
|
||||
│ │ ├── DeviceController.ts
|
||||
│ │ ├── MapController.ts
|
||||
│ │ ├── TripController.ts
|
||||
│ │ └── UserController.ts
|
||||
│ └── service/ # Business logic services
|
||||
│ └── MapService.ts
|
||||
├── utils/ # Utility functions
|
||||
│ ├── eventBus.ts # Custom event bus
|
||||
│ ├── localStorageUtils.ts
|
||||
│ ├── jwtTokenUtils.ts
|
||||
│ ├── mapUtils.ts
|
||||
│ ├── geomUtils.ts
|
||||
│ ├── format.ts
|
||||
│ └── cacheStore.ts
|
||||
├── types/ # TypeScript type definitions
|
||||
│ └── geojson.d.ts
|
||||
├── assets/ # Static assets (icons, images)
|
||||
└── .umi-production/ # UmiJS build artifacts (auto-generated)
|
||||
```
|
||||
|
||||
## Key Architectural Patterns
|
||||
|
||||
### 1. Event-Driven Architecture
|
||||
The application uses a custom **Event Bus** pattern for decoupled component communication:
|
||||
|
||||
```typescript
|
||||
// src/utils/eventBus.ts
|
||||
export const eventBus = new EventBus();
|
||||
|
||||
// Components emit events
|
||||
eventBus.emit('gpsData:update', data);
|
||||
|
||||
// Components listen to events
|
||||
eventBus.on('gpsData:update', handleUpdate);
|
||||
```
|
||||
|
||||
**Key Events:**
|
||||
- `gpsData:update` - GPS position updates
|
||||
- `ship:update` - Ship marker updates
|
||||
- `alarm:update` - Alarm status changes
|
||||
- `trackpoints:update` - Track history updates
|
||||
- `entities:update` - Geographic entities updates
|
||||
|
||||
### 2. Real-time Data Flow
|
||||
```
|
||||
GPS API (5s interval) → Event Bus → Multiple Components
|
||||
↓
|
||||
Ship Marker Updates
|
||||
Alarm Status Updates
|
||||
Track History Updates
|
||||
Zone Boundary Updates
|
||||
```
|
||||
|
||||
### 3. Controller Pattern
|
||||
API endpoints are organized in controllers following REST conventions:
|
||||
|
||||
```typescript
|
||||
// src/services/controller/DeviceController.ts
|
||||
export async function getGPS(): Promise<API.GPSResponse>
|
||||
export async function queryAlarms(): Promise<API.AlarmResponse>
|
||||
export async function queryEntities(): Promise<API.EntityResponse[]>
|
||||
```
|
||||
|
||||
### 4. UmiJS Model Pattern
|
||||
Global state management using UmiJS Models:
|
||||
|
||||
```typescript
|
||||
// src/models/getTrip.ts
|
||||
export default function useGetTripModel() {
|
||||
const [data, setData] = useState<API.Trip | null>(null);
|
||||
const getApi = useCallback(async () => {
|
||||
// API call and state update
|
||||
}, []);
|
||||
return { data, loading, getApi };
|
||||
}
|
||||
```
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Available Scripts
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Build for production
|
||||
npm run format # Format code with Prettier
|
||||
npm run setup # Initial setup
|
||||
```
|
||||
|
||||
### Package Management
|
||||
- **Primary**: `pnpm` (configured in .umirc.ts)
|
||||
- **Fallback**: `npm`
|
||||
|
||||
### Code Quality Tools
|
||||
- **Prettier**: Code formatting (80 char width, single quotes)
|
||||
- **ESLint**: Code linting via UmiJS `max lint`
|
||||
- **Husky**: Git hooks for pre-commit checks
|
||||
- **Lint-staged**: Staged file processing
|
||||
|
||||
### Environment Configuration
|
||||
- **Development**: `REACT_APP_ENV=dev` (localhost:8000)
|
||||
- **Test**: `REACT_APP_ENV=test` (test server)
|
||||
- **Production**: `REACT_APP_ENV=prod` (production server)
|
||||
|
||||
## Key Features & Components
|
||||
|
||||
### 1. Real-time GPS Monitoring (`/map`)
|
||||
- **VietNamMap**: Interactive OpenLayers map
|
||||
- **Ship Tracking**: Real-time vessel position updates
|
||||
- **Alarm Management**: Visual alert system
|
||||
- **Zone Boundaries**: Geographic restriction zones
|
||||
- **SOS Functionality**: Emergency button
|
||||
|
||||
### 2. Trip Management (`/trip`)
|
||||
- **Trip Creation/Update**: Fishing trip lifecycle
|
||||
- **Haul Logging**: Fish catch records
|
||||
- **Crew Management**: Team member tracking
|
||||
- **Cost Tracking**: Expense management
|
||||
- **Alarm Table**: Real-time alerts display
|
||||
|
||||
### 3. Authentication System
|
||||
- **JWT Token Management**: Secure authentication
|
||||
- **Auto-refresh**: Token expiration handling
|
||||
- **Route Protection**: Login redirects
|
||||
|
||||
### 4. Dynamic API Configuration
|
||||
The application supports **dynamic API endpoints** based on deployment environment:
|
||||
|
||||
```typescript
|
||||
// Auto-detects device IP and configures API accordingly
|
||||
const deviceApiUrl = `http://${window.location.hostname}:81`;
|
||||
```
|
||||
|
||||
## Map & Geospatial Features
|
||||
|
||||
### Map Components
|
||||
- **VietNamMap**: Main map component
|
||||
- **BaseMap**: OpenLayers integration
|
||||
- **MapManager**: Map state and interaction management
|
||||
|
||||
### Geographic Data
|
||||
- **GPS Coordinates**: WGS84 format
|
||||
- **GeoJSON**: Layer data format
|
||||
- **WKT**: Well-Known Text for geometries
|
||||
- **Zone Types**: Fishing zones, restricted areas
|
||||
|
||||
### Ship Icons & States
|
||||
- **Online/Offline**: Connection status
|
||||
- **Fishing/Non-fishing**: Activity state
|
||||
- **Alarm Levels**: Warning, alarm, SOS states
|
||||
- **Custom Icons**: Activity-specific markers
|
||||
|
||||
## API Integration
|
||||
|
||||
### Base URL Configuration
|
||||
- **Development**: `http://192.168.30.103:81`
|
||||
- **Test**: `https://test-sgw-device.gms.vn`
|
||||
- **Production**: `https://prod-sgw-device.gms.vn`
|
||||
|
||||
### Key API Endpoints
|
||||
```typescript
|
||||
GPS: /api/sgw/gps
|
||||
Trips: /api/sgw/trip
|
||||
Alarms: /api/io/alarms
|
||||
Entities: /api/io/entities
|
||||
Ship Info: /api/sgw/shipinfo
|
||||
SOS: /api/sgw/sos
|
||||
```
|
||||
|
||||
### Request Interceptors
|
||||
- **Authentication**: JWT token injection
|
||||
- **Error Handling**: Global error management
|
||||
- **Timeout**: 20-second timeout
|
||||
|
||||
## State Management
|
||||
|
||||
### Global State Models
|
||||
1. **global.ts** - User authentication state
|
||||
2. **getTrip.ts** - Trip management state
|
||||
3. **getSos.ts** - SOS and alarm state
|
||||
|
||||
### Local State Patterns
|
||||
- **useState**: Local component state
|
||||
- **useEffect**: Side effects and subscriptions
|
||||
- **useCallback**: Function memoization
|
||||
- **useRef**: DOM references and persistent values
|
||||
|
||||
## Development Guidelines
|
||||
|
||||
### Code Style
|
||||
- **TypeScript**: Strict typing enabled
|
||||
- **Component Structure**: Functional components with hooks
|
||||
- **File Naming**: PascalCase for components, camelCase for functions
|
||||
- **Import Organization**: Third-party libs → Local imports
|
||||
|
||||
### Best Practices
|
||||
1. **Error Boundaries**: Implement error boundaries for maps
|
||||
2. **Performance**: Use React.memo for expensive components
|
||||
3. **Memory Management**: Clean up event listeners and intervals
|
||||
4. **API Calls**: Use proper error handling and loading states
|
||||
5. **Type Safety**: Define TypeScript interfaces for all API responses
|
||||
|
||||
### Testing Approach
|
||||
- **Component Testing**: React Testing Library (if added)
|
||||
- **Integration Testing**: Manual testing with real API endpoints
|
||||
- **E2E Testing**: Browser testing scenarios
|
||||
|
||||
## Deployment
|
||||
|
||||
### Build Process
|
||||
```bash
|
||||
npm run build
|
||||
# Creates dist/ folder for deployment
|
||||
```
|
||||
|
||||
### Static Deployment
|
||||
1. Build application
|
||||
2. Copy `dist` folder to target device
|
||||
3. Serve via web server (nginx, apache, etc.)
|
||||
4. Ensure backend API runs on port 81
|
||||
|
||||
### Multi-Device Support
|
||||
- **Auto-detection**: Application detects device IP
|
||||
- **Dynamic API**: Base URL configured automatically
|
||||
- **CORS**: Ensure proper CORS configuration on backend
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
1. **Map Loading**: Check OpenLayers dependencies
|
||||
2. **API Calls**: Verify proxy configuration and network access
|
||||
3. **Event Bus**: Ensure proper event listener cleanup
|
||||
4. **State Management**: Check model initialization
|
||||
5. **Authentication**: Verify JWT token expiration
|
||||
|
||||
### Debug Mode
|
||||
- Enable console logging for GPS updates
|
||||
- Check network requests in browser dev tools
|
||||
- Monitor event bus emissions
|
||||
- Verify map coordinate transformations
|
||||
|
||||
## Contributing
|
||||
|
||||
### Adding New Features
|
||||
1. Create new page in `src/pages/`
|
||||
2. Add route in `.umirc.ts`
|
||||
3. Create API controller in `src/services/controller/`
|
||||
4. Add TypeScript types in `src/types/`
|
||||
5. Update constants in `src/constants/`
|
||||
|
||||
### Code Review Checklist
|
||||
- TypeScript types defined
|
||||
- Error handling implemented
|
||||
- Performance considerations
|
||||
- Accessibility compliance
|
||||
- Code style guidelines followed
|
||||
- Testing coverage (if applicable)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-01-20
|
||||
**Maintainers**: Mobifone Development Team
|
||||
**Version**: 1.2.2 - Dynamic API
|
||||
Reference in New Issue
Block a user