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

# Development Guide - Plan B Logistics Flutter App

This guide covers building and running the Plan B Logistics Flutter app on Android devices (KM10) with local backend communication.

## Prerequisites

- Flutter SDK installed and configured
- Android SDK installed (with platform-tools for adb)
- Android device (KM10) connected via USB with USB debugging enabled
- Backend API running on localhost (Mac)

## Device Setup

### 1. Verify Device Connection

Check that your Android device is connected and recognized:

```bash
flutter devices
```

You should see output similar to:
```
KM10 (mobile) • 24117ad4 • android-arm64 • Android 13 (API 33)
```

Alternatively, use adb directly:
```bash
/Users/mathias/Library/Android/sdk/platform-tools/adb devices -l
```

### 2. Configure ADB Reverse Proxy

The app needs to communicate with your local backend API running on `localhost:7182`. Since the Android device cannot access your Mac's localhost directly, you need to set up a reverse proxy using adb.

#### Get Device Serial Number

First, identify your device's serial number:
```bash
/Users/mathias/Library/Android/sdk/platform-tools/adb devices
```

Example output:
```
24117ad4	device
```

#### Set Up Reverse Proxy

Forward the device's localhost:7182 to your Mac's localhost:7182:

```bash
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182
```

Replace `24117ad4` with your actual device serial number.

#### Verify Reverse Proxy

Check that the reverse proxy is active:
```bash
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list
```

Expected output:
```
tcp:7182 tcp:7182
```

#### Test Backend Connectivity (Optional)

From the device shell, test if the backend is accessible:
```bash
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell "curl -k https://localhost:7182/api/query/simpleDeliveryRouteQueryItems -X POST -H 'Content-Type: application/json' -d '{}' -m 5 2>&1 | head -10"
```

## Building and Running

### 1. Install Dependencies

```bash
flutter pub get
```

### 2. Run on Connected Device

Run the app on the KM10 device in debug mode:

```bash
flutter run -d KM10
```

Or using the device serial number:
```bash
flutter run -d 24117ad4
```

### 3. Hot Reload and Restart

While the app is running:
- **Hot Reload** (r): Reload changed code without restarting
- **Hot Restart** (R): Restart the entire app
- **Quit** (q): Stop the app

### 4. Build Release APK

To build a release APK:

```bash
flutter build apk --release
```

The APK will be located at:
```
build/app/outputs/flutter-apk/app-release.apk
```

## Development Workflow

### Full Development Session

```bash
# 1. Check device connection
flutter devices

# 2. Set up ADB reverse proxy (do this once per device connection)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182

# 3. Verify reverse proxy
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list

# 4. Run the app
flutter run -d KM10
```

### If Backend Connection Fails

If the app cannot connect to the backend API:

1. Verify backend is running on Mac:
   ```bash
   curl https://localhost:7182/api/query/simpleDeliveryRouteQueryItems \
     -X POST \
     -H 'Content-Type: application/json' \
     -d '{}'
   ```

2. Check ADB reverse proxy is active:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --list
   ```

3. Re-establish reverse proxy if needed:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse --remove-all
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 reverse tcp:7182 tcp:7182
   ```

4. Check device logs for errors:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -d -t 100
   ```

## API Configuration

The app is configured to use the following API endpoints:

- **Query Base URL**: `https://localhost:7182/api/query`
- **Command Base URL**: `https://localhost:7182/api/command`

These are configured in `lib/api/openapi_config.dart`.

## Common Commands Reference

### Device Management

```bash
# List all connected devices
flutter devices

# List devices with adb
/Users/mathias/Library/Android/sdk/platform-tools/adb devices -l

# Get device info
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell getprop
```

### ADB Reverse Proxy

```bash
# Set up reverse proxy for port 7182
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse tcp:7182 tcp:7182

# List all reverse proxies
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --list

# Remove specific reverse proxy
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --remove tcp:7182

# Remove all reverse proxies
/Users/mathias/Library/Android/sdk/platform-tools/adb -s <DEVICE_ID> reverse --remove-all
```

### Logging

```bash
# View Flutter logs (last 100 lines)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -d -t 100

# View Flutter logs in real-time
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -s flutter:I -v time

# View all logs (last 300 lines)
/Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -d -t 300
```

### Build Commands

```bash
# Debug build (default)
flutter build apk --debug

# Release build
flutter build apk --release

# Profile build (for performance testing)
flutter build apk --profile

# Install APK directly
flutter install -d KM10
```

## Troubleshooting

### Device Not Found

If `flutter devices` doesn't show your device:

1. Check USB debugging is enabled on the device
2. Check device is authorized (check device screen for prompt)
3. Restart adb server:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb kill-server
   /Users/mathias/Library/Android/sdk/platform-tools/adb start-server
   ```

### App Crashes on Startup

1. Check logs:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 logcat -d | grep -i error
   ```

2. Clear app data:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 shell pm clear com.goutezplanb.planb_logistic
   ```

3. Uninstall and reinstall:
   ```bash
   /Users/mathias/Library/Android/sdk/platform-tools/adb -s 24117ad4 uninstall com.goutezplanb.planb_logistic
   flutter run -d KM10
   ```

### Backend Connection Issues

1. Verify reverse proxy is active
2. Check backend API is running
3. Check SSL certificate issues (app uses `https://localhost:7182`)
4. Review network logs in the Flutter output

## Additional Resources

- Flutter Documentation: https://docs.flutter.dev
- Android Debug Bridge (adb): https://developer.android.com/studio/command-line/adb
- Project-specific guidelines: See CLAUDE.md for code standards and architecture