ionic-planb-logistic-app-flutter/SETUP_GUIDE.md

# Fleet Driver App - Setup Guide

## Overview
This is a mobile application for drivers to manage their delivery routes, handle pickups/dropoffs, and navigate to destinations using Google Maps integration.

## Prerequisites

- Flutter SDK 3.7.2 or higher
- Dart SDK
- Android Studio / Xcode
- Google Maps API Key

## Getting Started

### 1. Install Dependencies

```bash
flutter pub get
```

### 2. Configure Google Maps API Key

#### Get Your API Key

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the following APIs:
   - Maps SDK for Android
   - Maps SDK for iOS
   - Directions API (for navigation)
   - Places API (optional, for address autocomplete)
4. Create credentials (API Key)
5. Copy your API key

#### Android Configuration

1. Open `android/app/src/main/AndroidManifest.xml`
2. Replace `YOUR_GOOGLE_MAPS_API_KEY_HERE` with your actual API key:

```xml
<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR_ACTUAL_API_KEY"/>
```

#### iOS Configuration

1. Open `ios/Runner/AppDelegate.swift`
2. Replace `YOUR_GOOGLE_MAPS_API_KEY_HERE` with your actual API key:

```swift
GMSServices.provideAPIKey("YOUR_ACTUAL_API_KEY")
```

### 3. Configure Backend API (Optional)

If you have a backend API, update the API configuration in:
`lib/core/constants/app_constants.dart`

```dart
static const String baseApiUrl = 'https://your-api-url.com/api';
```

### 4. Run the App

#### Android
```bash
flutter run
```

#### iOS
```bash
cd ios
pod install
cd ..
flutter run
```

## Project Structure

```
lib/
├── core/
│   ├── constants/          # App-wide constants
│   ├── theme/              # App theme and colors
│   ├── utils/              # Utility functions
│   └── widgets/            # Reusable widgets
│
├── features/
│   ├── routes/
│   │   ├── data/
│   │   │   ├── models/     # Data models
│   │   │   └── repositories/
│   │   ├── domain/
│   │   │   ├── entities/
│   │   │   └── repositories/
│   │   └── presentation/
│   │       ├── pages/      # UI screens
│   │       ├── widgets/    # Feature-specific widgets
│   │       └── providers/  # State management
│   │
│   └── navigation/
│
├── services/
│   ├── location/           # Location services
│   ├── maps/              # Navigation services
│   └── api/               # API services
│
└── main.dart              # App entry point
```

## Features

### Current Features

1. **Route Management**
   - View assigned routes
   - Track route progress
   - Start/complete routes

2. **Stop Management**
   - View pickup and dropoff locations
   - Navigate to stops
   - Mark stops as completed
   - View stop details (customer info, items, etc.)

3. **Map Integration**
   - View all stops on a map
   - Real-time location tracking
   - Navigate to destinations using Google Maps

4. **Status Tracking**
   - Route status (not started, in progress, completed)
   - Stop status (pending, in progress, completed, failed)
   - Progress indicators

### Upcoming Features

- Photo capture for proof of delivery
- Signature collection
- Offline mode
- Push notifications
- Route optimization
- Driver performance metrics

## API Integration

The app is designed to work with a backend API. The main API endpoints expected are:

- `GET /routes/:driverId` - Get driver routes
- `GET /routes/detail/:routeId` - Get route details
- `PUT /routes/:routeId/status` - Update route status
- `PUT /stops/:stopId/status` - Update stop status
- `POST /stops/:stopId/issue` - Report an issue

### Mock Data for Development

If you don't have a backend yet, you can modify the `RouteApiService` to return mock data:

```dart
// In lib/services/api/route_api_service.dart
Future<List<RouteModel>> getDriverRoutes(String driverId) async {
  // Return mock data instead of API call
  return [
    // Your mock route data here
  ];
}
```

## Permissions

### Android
The following permissions are configured in `AndroidManifest.xml`:
- `INTERNET` - For API calls
- `ACCESS_FINE_LOCATION` - For precise location
- `ACCESS_COARSE_LOCATION` - For approximate location
- `FOREGROUND_SERVICE` - For background location tracking

### iOS
The following permissions are configured in `Info.plist`:
- Location When In Use
- Location Always (for background tracking)

## Troubleshooting

### Google Maps Not Showing

1. Verify your API key is correct
2. Make sure you've enabled the required APIs in Google Cloud Console
3. Check if you've restricted your API key (it should allow your app's package name)

### Location Not Working

1. Check device location settings are enabled
2. Grant location permissions when prompted
3. Test on a real device (emulators may have location issues)

### Build Errors

```bash
# Clean and rebuild
flutter clean
flutter pub get
flutter run
```

## Testing

```bash
# Run tests
flutter test

# Run with coverage
flutter test --coverage
```

## Building for Production

### Android
```bash
flutter build apk --release
# or
flutter build appbundle --release
```

### iOS
```bash
flutter build ios --release
```

## Support

For issues or questions, please contact your development team or refer to the Flutter documentation at https://flutter.dev/docs