# Nearby drivers map (Step 39)

Customer Google Map shows **AVAILABLE** drivers near the customer.
Active assigned-driver tracking remains **`ride.updated`** (separate).

## REST

`GET /drivers/nearby?latitude=&longitude=&radiusKm=`

- Auth: JWT + **customer**
- Radius default: `NEARBY_DRIVERS_DEFAULT_RADIUS_KM` (or `MATCHING_RADIUS_KM`, default 5)
- Max radius: `NEARBY_DRIVERS_MAX_RADIUS_KM` (default 10)
- Stale GPS excluded: `NEARBY_DRIVER_LOCATION_STALE_SECONDS` (default 30)

Only drivers who are:

- `AVAILABLE`
- verification `APPROVED`
- user `active`
- fresh location
- within radius

## Socket (customer map watch)

| Client → server | Purpose |
|-----------------|---------|
| `nearby_drivers:join` | Start watching `{ latitude, longitude, radiusKm? }` |
| `nearby_drivers:update` | Move map center / radius |
| `nearby_drivers:leave` | Stop watching |

| Server → client | Purpose |
|-----------------|---------|
| `nearby_drivers:joined` | Ack (also returned as handler result) |
| `nearby_drivers.updated` | Live marker updates |

### `nearby_drivers.updated` types

- `INITIAL_DRIVERS` — after join
- `DRIVER_ADDED` — entered radius
- `DRIVER_LOCATION_UPDATED` — moved while visible
- `DRIVER_REMOVED` — left radius / became BUSY / offline

Identity always comes from JWT. Do not send `customerId` / `driverId` for auth.

## Redis (optional scale)

| Key | Use |
|-----|-----|
| `nearby:drivers` | GEO of AVAILABLE drivers |
| `nearby:customers` | GEO of map watchers |
| `nearby:driver:{id}` | Meta hash (heading, etc.) |
| `nearby:customer:{id}` | Watcher meta |
| `nearby:customer:{id}:visible` | Drivers currently shown to that customer |

MySQL `driverlocation` remains the source of truth. Redis unavailable → in-memory fallbacks.

## Flutter markers

1. `GET /drivers/nearby` → create markers  
2. `nearby_drivers:join` → listen `nearby_drivers.updated`  
3. `DRIVER_ADDED` → create marker  
4. `DRIVER_LOCATION_UPDATED` → move marker  
5. `DRIVER_REMOVED` → remove marker  
6. Assigned ride → use **`ride.updated`**, not this event

## Config

```
NEARBY_DRIVERS_DEFAULT_RADIUS_KM=5
NEARBY_DRIVERS_MAX_RADIUS_KM=10
NEARBY_DRIVER_LOCATION_STALE_SECONDS=30
NEARBY_DRIVER_SOCKET_THROTTLE_MS=2000
```