Cập nhật README.md
This commit is contained in:
Tran Anh Tuan
284
README.md
284
README.md
@@ -1,53 +1,271 @@
|
|||||||
# Welcome to your Expo app 👋
|
# CLAUDE.md
|
||||||
|
|
||||||
This is an [Expo](https://expo.dev) project created with [`create-expo-app`](https://www.npmjs.com/package/create-expo-app).
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||||
|
|
||||||
## Get started
|
## Project Overview
|
||||||
|
|
||||||
1. Install dependencies
|
**SeaGateway-App-Owner** is a React Native maritime/fishing industry mobile application built with Expo framework and TypeScript. The app is designed for fishing vessel owners and provides GPS tracking, trip management, sensor monitoring, fish species tracking, and emergency alert systems for maritime operations.
|
||||||
|
|
||||||
|
### Technology Stack
|
||||||
|
- **Framework**: Expo ~54.0.20 (managed workflow) with React Native 0.81.5 (New Architecture enabled)
|
||||||
|
- **Navigation**: Expo Router ~6.0.13 (file-based routing)
|
||||||
|
- **Styling**: NativeWind ^4.2.1 (TailwindCSS for React Native) with comprehensive design system
|
||||||
|
- **State Management**: Zustand ^5.0.8
|
||||||
|
- **API Client**: Axios ^1.13.1 with interceptors and 401 handling
|
||||||
|
- **Internationalization**: i18n-js ^4.5.1 (English & Vietnamese support)
|
||||||
|
- **Maps**: React Native Maps ^1.20.1
|
||||||
|
- **Forms**: React Hook Form ^7.66.0 with resolvers
|
||||||
|
- **Animations**: React Native Reanimated ~4.1.0, @legendapp/motion ^2.5.3
|
||||||
|
|
||||||
|
## Development Commands
|
||||||
|
|
||||||
|
### Core Commands
|
||||||
```bash
|
```bash
|
||||||
npm install
|
# Start development server
|
||||||
```
|
npm start
|
||||||
|
# or npx expo start
|
||||||
|
|
||||||
2. Start the app
|
# Platform-specific builds
|
||||||
|
npm run android # Build for Android
|
||||||
|
npm run ios # Build for iOS
|
||||||
|
npm run web # Build for web
|
||||||
|
|
||||||
```bash
|
# Code quality
|
||||||
npx expo start
|
npm run lint # Run ESLint
|
||||||
```
|
|
||||||
|
|
||||||
In the output, you'll find options to open the app in a
|
# Reset to blank template
|
||||||
|
|
||||||
- [development build](https://docs.expo.dev/develop/development-builds/introduction/)
|
|
||||||
- [Android emulator](https://docs.expo.dev/workflow/android-studio-emulator/)
|
|
||||||
- [iOS simulator](https://docs.expo.dev/workflow/ios-simulator/)
|
|
||||||
- [Expo Go](https://expo.dev/go), a limited sandbox for trying out app development with Expo
|
|
||||||
|
|
||||||
You can start developing by editing the files inside the **app** directory. This project uses [file-based routing](https://docs.expo.dev/router/introduction).
|
|
||||||
|
|
||||||
## Get a fresh project
|
|
||||||
|
|
||||||
When you're ready, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm run reset-project
|
npm run reset-project
|
||||||
```
|
```
|
||||||
|
|
||||||
This command will move the starter code to the **app-example** directory and create a blank **app** directory where you can start developing.
|
### Build and Deployment
|
||||||
|
The app is configured for EAS (Expo Application Services) with auto-increment versioning for production builds. Add `eas.json` to root for EAS configuration.
|
||||||
|
|
||||||
## Learn more
|
## Architecture & File Structure
|
||||||
|
|
||||||
To learn more about developing your project with Expo, look at the following resources:
|
### Directory Layout
|
||||||
|
```
|
||||||
|
SeaGateway-App-Owner/
|
||||||
|
├── app/ # File-based routing (Expo Router)
|
||||||
|
│ ├── _layout.tsx # Root layout with providers stack
|
||||||
|
│ ├── (tabs)/ # Main tab navigation screens
|
||||||
|
│ │ ├── index.tsx # Home/Monitor screen
|
||||||
|
│ │ ├── tripInfo.tsx # Trip information
|
||||||
|
│ │ ├── diary.tsx # Diary/journal
|
||||||
|
│ │ ├── sensor.tsx # Sensor data
|
||||||
|
│ │ └── setting.tsx # Settings
|
||||||
|
│ ├── auth/login.tsx # Authentication
|
||||||
|
│ └── modal.tsx # Modal screens
|
||||||
|
├── components/ # Reusable UI components
|
||||||
|
│ ├── ui/ # Base UI components
|
||||||
|
│ ├── themed-*.tsx # Themed components
|
||||||
|
│ └── [various components] # Feature-specific components
|
||||||
|
├── controller/ # Business logic layer (MVC pattern)
|
||||||
|
│ ├── AuthController.ts # Authentication logic
|
||||||
|
│ ├── DeviceController.ts # Device management
|
||||||
|
│ ├── FishController.ts # Fish-related operations
|
||||||
|
│ ├── MapController.ts # Map functionality
|
||||||
|
│ └── TripController.ts # Trip management
|
||||||
|
├── services/ # External service integrations
|
||||||
|
│ ├── map_service.ts # Map services
|
||||||
|
│ ├── device_events.ts # Device event handling
|
||||||
|
│ └── toast_service.tsx # Toast notifications
|
||||||
|
├── state/ # Zustand state stores
|
||||||
|
│ ├── use-trip.ts # Trip state management
|
||||||
|
│ ├── use-banzones.ts # Ban zone state
|
||||||
|
│ └── use-fish.ts # Fish data state
|
||||||
|
├── hooks/ # Custom React hooks
|
||||||
|
│ ├── use-i18n.ts # Internationalization hook
|
||||||
|
│ ├── use-theme-context.tsx # Theme management
|
||||||
|
│ └── use-app-theme.ts # Theme utilities (recommended)
|
||||||
|
├── config/ # Configuration files
|
||||||
|
│ ├── axios.ts # API client with interceptors
|
||||||
|
│ ├── auth.ts # Authentication configuration
|
||||||
|
│ └── localization/ # i18n setup
|
||||||
|
├── constants/ # App constants and API endpoints
|
||||||
|
├── utils/ # Utility functions
|
||||||
|
├── locales/ # Translation files (en.json, vi.json)
|
||||||
|
└── assets/ # Static assets (images, fonts)
|
||||||
|
```
|
||||||
|
|
||||||
- [Expo documentation](https://docs.expo.dev/): Learn fundamentals, or go into advanced topics with our [guides](https://docs.expo.dev/guides).
|
### Key Architecture Patterns
|
||||||
- [Learn Expo tutorial](https://docs.expo.dev/tutorial/introduction/): Follow a step-by-step tutorial where you'll create a project that runs on Android, iOS, and the web.
|
|
||||||
|
|
||||||
## Join the community
|
**MVC Structure**: Controllers handle business logic, state is managed separately, and components focus on UI.
|
||||||
|
|
||||||
Join our community of developers creating universal apps.
|
**Service Layer**: External API integrations (maps, device events, notifications) are abstracted into services.
|
||||||
|
|
||||||
|
**File-based Routing**: Uses Expo Router's file system for automatic route generation.
|
||||||
|
|
||||||
|
**Theme System**: Sophisticated theme management with light/dark/system modes and comprehensive design tokens.
|
||||||
|
|
||||||
|
## Theme System
|
||||||
|
|
||||||
|
The app features an advanced theme system with **3 modes**: Light, Dark, and System (automatic). Theme preferences are persisted in AsyncStorage and synchronized with system changes.
|
||||||
|
|
||||||
|
### Theme Hooks (Usage Priority)
|
||||||
|
1. **`useAppTheme()`** (Recommended) - Full theme utilities with pre-built styles
|
||||||
|
2. **`useThemeContext()`** - Full control (themeMode, setThemeMode, colors)
|
||||||
|
3. **`useColorScheme()`** - Quick light/dark detection
|
||||||
|
4. **`useThemeColor()`** - Color overrides
|
||||||
|
|
||||||
|
### Themed Components
|
||||||
|
Use **ThemedView** and **ThemedText** for automatic theme application:
|
||||||
|
```tsx
|
||||||
|
import { ThemedText } from "@/components/themed-text";
|
||||||
|
import { ThemedView } from "@/components/themed-view";
|
||||||
|
|
||||||
|
<ThemedView>
|
||||||
|
<ThemedText type="title">Title Text</ThemedText>
|
||||||
|
<ThemedText type="subtitle">Subtitle</ThemedText>
|
||||||
|
<ThemedText type="default">Regular Text</ThemedText>
|
||||||
|
<ThemedText type="link">Link Text</ThemedText>
|
||||||
|
</ThemedView>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pre-built Styles (from useAppTheme)
|
||||||
|
```tsx
|
||||||
|
const { styles, utils } = useAppTheme();
|
||||||
|
|
||||||
|
// Containers
|
||||||
|
styles.container // Flex 1 with theme background
|
||||||
|
styles.surface // Surface with padding, border radius
|
||||||
|
styles.card // Card with shadow, elevation
|
||||||
|
|
||||||
|
// Buttons
|
||||||
|
styles.primaryButton // Primary button colors
|
||||||
|
styles.secondaryButton // Secondary button with border
|
||||||
|
styles.primaryButtonText // White text for primary
|
||||||
|
styles.secondaryButtonText // Theme text for secondary
|
||||||
|
|
||||||
|
// Status containers
|
||||||
|
styles.successContainer // Success background with border
|
||||||
|
styles.warningContainer // Warning background with border
|
||||||
|
styles.errorContainer // Error background with border
|
||||||
|
|
||||||
|
// Utilities
|
||||||
|
utils.isDark // Boolean theme check
|
||||||
|
utils.toggleTheme() // Toggle light ↔ dark
|
||||||
|
utils.getOpacityColor("primary", 0.1) // RGBA with opacity
|
||||||
|
```
|
||||||
|
|
||||||
|
## Internationalization (i18n)
|
||||||
|
|
||||||
|
Supports English (`en`) and Vietnamese (`vi`) with automatic device locale detection and persistent storage.
|
||||||
|
|
||||||
|
### Translation Hook
|
||||||
|
```tsx
|
||||||
|
import { useI18n } from "@/hooks/use-i18n";
|
||||||
|
|
||||||
|
const { t, locale, setLocale, isLoaded } = useI18n();
|
||||||
|
|
||||||
|
// Translations
|
||||||
|
t("auth.login") // Simple key
|
||||||
|
t("auth.welcome", { name: "John" }) // With interpolation
|
||||||
|
```
|
||||||
|
|
||||||
|
### Translation Files
|
||||||
|
Located in `locales/`:
|
||||||
|
- `en.json` - English translations
|
||||||
|
- `vi.json` - Vietnamese translations
|
||||||
|
|
||||||
|
Structure uses nested keys for organization (e.g., `"auth.login.title"`).
|
||||||
|
|
||||||
|
## API & State Management
|
||||||
|
|
||||||
|
### API Configuration
|
||||||
|
Base URL: `https://sgw.gms.vn`
|
||||||
|
- Automatic JWT token handling via Axios interceptors
|
||||||
|
- 401 error handling with automatic logout
|
||||||
|
- Comprehensive error messaging with toast notifications
|
||||||
|
- 20-second timeout for all requests
|
||||||
|
|
||||||
|
### State Management (Zustand)
|
||||||
|
```tsx
|
||||||
|
// Trip state
|
||||||
|
import { useTrip } from "@/state/use-trip";
|
||||||
|
|
||||||
|
const { trip, getTrip, error, loading } = useTrip();
|
||||||
|
```
|
||||||
|
|
||||||
|
Key stores:
|
||||||
|
- **useTrip** - Trip data and operations
|
||||||
|
- **useBanzones** - Restricted area management
|
||||||
|
- **useFish** - Fish species data
|
||||||
|
|
||||||
|
### Authentication Flow
|
||||||
|
JWT-based with AsyncStorage persistence:
|
||||||
|
1. Login via `/api/tokens`
|
||||||
|
2. Token stored and auto-added to requests
|
||||||
|
3. 401 responses trigger automatic logout
|
||||||
|
4. Auth state managed through AuthController
|
||||||
|
|
||||||
|
## Maritime-Specific Features
|
||||||
|
|
||||||
|
### Core Functionality
|
||||||
|
- **GPS Tracking**: Real-time vessel position tracking
|
||||||
|
- **Trip Management**: Commercial fishing trip logging and monitoring
|
||||||
|
- **Sensor Data**: Various marine sensor integration
|
||||||
|
- **Ban Zones**: Restricted fishing area enforcement
|
||||||
|
- **Fish Species**: Catch logging with species identification
|
||||||
|
- **SOS System**: Emergency alert functionality
|
||||||
|
- **Map Integration**: Maritime charts and zone visualization
|
||||||
|
|
||||||
|
### API Endpoints
|
||||||
|
Key maritime APIs:
|
||||||
|
- `/api/sgw/gps` - GPS tracking data
|
||||||
|
- `/api/sgw/trip` - Trip management
|
||||||
|
- `/api/sgw/fishingLog` - Catch logging
|
||||||
|
- `/api/sgw/banzones` - Restricted zones
|
||||||
|
- `/api/sgw/sos` - Emergency alerts
|
||||||
|
- `/api/sgw/fishspecies` - Fish species data
|
||||||
|
|
||||||
|
## Development Setup & Configuration
|
||||||
|
|
||||||
|
### TypeScript Configuration
|
||||||
|
- Strict mode enabled
|
||||||
|
- Path aliases: `@/*` maps to root directory
|
||||||
|
- Extends Expo base TypeScript config
|
||||||
|
|
||||||
|
### TailwindCSS Configuration
|
||||||
|
- Comprehensive design system with CSS variables
|
||||||
|
- Custom color palette (primary, secondary, tertiary, error, success, warning)
|
||||||
|
- Custom font families (Inter, Jakarta Sans, Roboto, Source Code Pro)
|
||||||
|
- Custom shadow utilities and spacing
|
||||||
|
- Dark mode support via class-based switching
|
||||||
|
|
||||||
|
### Metro Bundler
|
||||||
|
- Custom metro.config.js with NativeWind integration
|
||||||
|
- Optimized for React Native with CSS-in-JS support
|
||||||
|
|
||||||
|
## Development Best Practices
|
||||||
|
|
||||||
|
### Component Development
|
||||||
|
- Use themed components for consistent theming
|
||||||
|
- Prefer `useAppTheme()` for UI components
|
||||||
|
- Leverage TailwindCSS for styling with NativeWind
|
||||||
|
- Follow file-based routing conventions
|
||||||
|
|
||||||
|
### State Management
|
||||||
|
- Use Zustand stores for complex state
|
||||||
|
- Keep controllers for business logic
|
||||||
|
- Use services for external integrations
|
||||||
|
|
||||||
|
### API Integration
|
||||||
|
- Use the configured Axios instance with interceptors
|
||||||
|
- Handle errors through the existing toast system
|
||||||
|
- Follow the established JWT authentication flow
|
||||||
|
|
||||||
|
### Theme Development
|
||||||
|
- Use the comprehensive theme system for all UI elements
|
||||||
|
- Test all theme modes (light/dark/system)
|
||||||
|
- Leverage pre-built styles from useAppTheme()
|
||||||
|
- Use opacity colors for subtle backgrounds and overlays
|
||||||
|
|
||||||
|
### Internationalization
|
||||||
|
- Always use the `t()` function for user-facing text
|
||||||
|
- Add translations to both en.json and vi.json
|
||||||
|
- Follow nested key structure for organization
|
||||||
|
- Test with both locales
|
||||||
|
|
||||||
- [Expo on GitHub](https://github.com/expo/expo): View our open source platform and contribute.
|
|
||||||
- [Discord community](https://chat.expo.dev): Chat with Expo users and ask questions.
|
|
||||||
|
|
||||||
## Build app
|
## Build app
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user