FE-DEVICE-SGW/CLAUDE.md

# 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