# gRPC Integration E2E Verification Guide

This document provides steps for verifying the gRPC integration end-to-end.

## Prerequisites

1. gRPC backend server running at `192.168.88.228:5011`
2. Flutter environment configured
3. Valid test credentials for authentication

## Step 1: Enable gRPC Mode

To enable gRPC mode, override the `apiModeConfigProvider` in the app's `ProviderScope`:

### Option A: Code Change (for testing)

Edit `lib/main.dart` to add the provider override:

```dart
import 'package:planb_logistic/providers/providers.dart';

void main() {
  runApp(
    ProviderScope(
      overrides: [
        // Enable gRPC mode with fallback to HTTP
        apiModeConfigProvider.overrideWithValue(ApiModeConfig.developmentGrpc),
      ],
      child: const MyApp(),
    ),
  );
}
```

### Option B: Environment-Based Toggle

The app can also be configured to check an environment variable or build flag:

```dart
final useGrpc = const bool.fromEnvironment('USE_GRPC', defaultValue: false);
final apiMode = useGrpc ? ApiModeConfig.developmentGrpc : ApiModeConfig.development;
```

Then run with:
```bash
flutter run -d chrome --dart-define=USE_GRPC=true
```

## Step 2: Login to App

1. Launch the app in Chrome browser:
   ```bash
   flutter run -d chrome
   ```

2. Click "Login with Keycloak" button
3. Enter valid credentials
4. Wait for redirect back to the app

**Expected:** User is authenticated and redirected to the main app.

## Step 3: Navigate to Routes Page

1. After login, navigate to the Routes page
2. The app should fetch delivery routes via gRPC

**Expected Behavior:**
- Routes list should populate with delivery route data
- No console errors related to gRPC
- In browser DevTools console, you should see:
  - No "gRPC failed" messages (unless backend is unavailable)
  - If gRPC fails and fallback is enabled, you may see: "gRPC failed, falling back to HTTP: ..."

**Verification Points:**
- Routes display with correct data (id, name, deliveries count)
- Loading indicator shows during fetch
- Error state handled gracefully if backend unavailable

## Step 4: Select a Route - Verify Deliveries Load

1. Click on a route from the list
2. Navigate to the deliveries page for that route

**Expected Behavior:**
- Deliveries list should populate with delivery data for the selected route
- Each delivery should show:
  - Delivery index/number
  - Customer name
  - Address information
  - Status (delivered/pending/skipped)
- Warehouse delivery should appear at the end of the list

**Verification Points:**
- Correct number of deliveries loaded
- All delivery fields properly mapped from gRPC response
- Warehouse delivery appended correctly

## Step 5: Mark a Delivery Complete

1. Select an uncompleted delivery
2. Mark it as complete (tap completion button)

**Expected Behavior:**
- Command sent via gRPC to `completeDelivery` endpoint
- Delivery status updates to "completed"
- UI refreshes to show new status

**Verification Points:**
- No error messages
- Delivery marked as completed in the list
- Timestamp recorded for completion

## Step 6: Check Browser Console for gRPC Logs

Open browser DevTools (F12) and check the Console tab for:

### Success Indicators:
- No error messages related to gRPC
- Successful data loading without fallback messages

### Warning Indicators (acceptable):
- "gRPC failed, falling back to HTTP: ..." - indicates gRPC failed but HTTP fallback worked

### Error Indicators (need investigation):
- "UNAUTHENTICATED" errors - token issue
- "UNAVAILABLE" errors - backend not reachable
- "DEADLINE_EXCEEDED" errors - timeout
- Unhandled exceptions

## Verification Checklist

| Step | Check | Status |
|------|-------|--------|
| 1 | gRPC mode enabled via provider override | [ ] |
| 2 | Login successful | [ ] |
| 3 | Routes load (via gRPC or HTTP fallback) | [ ] |
| 4 | Deliveries load for selected route | [ ] |
| 5 | Complete delivery command works | [ ] |
| 6 | No critical console errors | [ ] |

## Troubleshooting

### gRPC Backend Unavailable

If the gRPC backend at `192.168.88.228:5011` is not reachable:

1. **With fallback enabled (default):** App falls back to HTTP automatically
2. **Without fallback:** App shows error state

To test with HTTP only:
```dart
apiModeConfigProvider.overrideWithValue(ApiModeConfig.development)
```

### Authentication Issues

If you see UNAUTHENTICATED errors:

1. Check that the auth token is valid
2. Try logging out and back in
3. Verify the token is being sent in gRPC metadata

### Connection Timeout

If requests are timing out:

1. Check network connectivity to `192.168.88.228:5011`
2. Verify the backend server is running
3. Check firewall/VPN settings

## Production Configuration

For production deployment, use:

```dart
apiModeConfigProvider.overrideWithValue(ApiModeConfig.productionGrpc)
```

This connects to `grpc-route.goutezplanb.com:443` with TLS enabled.

## Test Commands

```bash
# Run unit tests (no backend required)
flutter test

# Run with gRPC enabled
flutter run -d chrome --dart-define=USE_GRPC=true

# Check gRPC backend is reachable (requires grpcurl)
grpcurl -plaintext 192.168.88.228:5011 list
```