# FleetLume Dispatch Operations

This release connects load acquisition, rate negotiation, driver routing, compliance monitoring, and real-time truck tracking into one dispatch lifecycle.

## Dispatch lifecycle

1. Open **Dispatch → Control Center**.
2. Add a load opportunity from a broker, customer, load board, email, phone call, or another source.
3. Record outbound offers, inbound counteroffers, accepted rates, and rejected offers in the negotiation timeline.
4. Convert a won opportunity into a booked load. The conversion carries the lane, dates, broker, commodity, weight, miles, and accepted rate into Load Management.
5. Assign a driver, truck, and optional trailer and save a route plan.
6. The route appears in the driver portal with departure time, ETA, distance, dispatch instructions, checkpoints, and a turn-by-turn Google Maps link.
7. Driver status and stop updates automatically advance the route and its checkpoints.
8. Browser GPS or a connected telematics device sends truck locations to the live dispatcher map.
9. Compliance scans flag credential, equipment, authority, HOS, assignment, and stale-tracking risks.

## Access and permissions

Owners and administrators have full access automatically. Dispatcher accounts receive these role defaults:

- `dispatch.view`
- `dispatch.manage`
- `tracking.view`

Additional users can be granted **View dispatch control center**, **Manage dispatch workflows**, and **View live tracking** from **Users & Portals**.

## Real-time tracking methods

### Driver browser tracking

A driver opens an assigned load in the mobile portal and selects **Start Live Tracking**. The page sends browser geolocation updates at the interval configured in Company Settings. Manual location and status updates are also saved to the truck-location history.

Browser tracking requires HTTPS and location permission. Mobile operating systems may pause browser tracking when the browser is closed or the screen remains locked.

### External truck telematics

1. Open **Dispatch → Control Center → Real-Time Tracking**.
2. Select a truck and enter the provider name.
3. Generate the tracking token and copy it immediately. FleetLume stores only its SHA-256 hash.
4. Send normalized JSON updates to the displayed endpoint using the token as a Bearer token.

Example:

```bash
curl -X POST "https://your-domain.com/tracking/telematics" \
  -H "Authorization: Bearer YOUR_PRIVATE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "provider-event-12345",
    "device_id": "gps-device-88",
    "latitude": 41.8781,
    "longitude": -87.6298,
    "speed": 53.4,
    "heading": 271,
    "accuracy": 8,
    "ignition": true,
    "odometer": 482155.7,
    "location_address": "Chicago, IL",
    "recorded_at": "2026-07-13T12:30:00-05:00"
  }'
```

Required fields:

- `latitude`
- `longitude`

Optional fields:

- `event_id` for duplicate-event protection
- `device_id`
- `speed`
- `heading`
- `accuracy`
- `ignition`
- `odometer`
- `location_address`
- `recorded_at`

Provider APIs use different webhook formats. Samsara, Motive, Geotab, Verizon Connect, and similar services should either be configured to send this normalized payload or connected through a small provider-specific webhook adapter.

## Live dispatcher map

The live map refreshes every 10 seconds and shows:

- Moving, stopped, stale, and offline trucks
- Driver, active load, route state, speed, provider, and update age
- Compliance-risk marker rings
- Search and status filters
- Recent truck path and location history

Tracking freshness rules:

- Moving or stopped: update received within 2 minutes
- Stale: update received within 10 minutes
- Offline: no update for more than 10 minutes

## Compliance monitoring

The automatic scan currently checks:

- Driver license expiry or missing expiry date
- Driver medical card expiry or missing expiry date
- HOS violations and clocks nearing their limits
- Truck insurance, registration, and inspection expiry
- Trailer registration and inspection expiry
- Carrier authority and insurance status
- Missing driver or truck assignments on active loads
- Missing or stale GPS updates during an active trip

Alerts can be acknowledged, resolved, or waived. Critical and high alerts notify owner, administrator, and dispatcher roles when first created.

The dispatch page refreshes compliance results when the last scan is older than five minutes. The existing `automation_runner.php` also runs the scan, so the same CLI cron used for FleetLume automation can keep alerts current without opening the page.

## Database update

For a new installation, run `install.php` normally.

For an existing installation:

1. Back up the database, project files, and `storage/uploads`.
2. Replace the application files.
3. Open `install.php?unlock=1`.
4. Use the existing database credentials and complete the updater.
5. Confirm the new dispatch tables were created.
6. Sign in as an owner or administrator and open **Dispatch → Control Center**.

New tables:

- `load_opportunities`
- `rate_negotiations`
- `route_plans`
- `route_waypoints`
- `compliance_alerts`
- `telematics_devices`
- `truck_locations`

## Production checklist

- Use HTTPS for login, GPS, camera uploads, and telematics ingestion.
- Point the domain document root to `public` where hosting permits it.
- Keep generated tracking tokens private and regenerate a token immediately if exposed.
- Validate each provider's webhook mapping in staging before enabling production traffic.
- Confirm the server time zone and Company Settings time zone.
- Review every driver, truck, trailer, and carrier compliance date.
- Test browser GPS from a real driver phone.
- Test the full opportunity-to-delivery lifecycle on staging.
- Configure the existing automation cron for recurring compliance scans.
- Restrict `install.php` after deployment.