> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bulkroute.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Live — Mapa em Tempo Real

> Acompanhe seus motoristas e envios em trânsito num mapa em tempo real, com posição GPS ao vivo e filtros por transportadora.

O Tracking Live mostra todos os seus envios em trânsito num mapa interativo, com posição GPS atualizada dos motoristas da frota própria.

<Note>
  Acesso: **Campo** > **Tracking Live** (`/admin/tracking-live`). Requer perfil Manager.
</Note>

## O que você vê

| Elemento    | Descrição                                                    |
| :---------- | :----------------------------------------------------------- |
| **Mapa**    | Mapa escuro (MapTiler) com marcadores por carrier            |
| **Sidebar** | Lista de envios em trânsito com status, motorista e placa    |
| **KPIs**    | Em Trânsito, Frota Própria, Com Motorista, Saiu para Entrega |

## KPIs no topo

| KPI                   | O que significa                                |
| :-------------------- | :--------------------------------------------- |
| **Em Trânsito**       | Total de envios entre PICKED\_UP e IN\_TRANSIT |
| **Frota Própria**     | Envios sendo executados por seus motoristas    |
| **Com Motorista**     | Envios já atribuídos a um motorista            |
| **Saiu para Entrega** | Envios em OUT\_FOR\_DELIVERY (rota final)      |

## Filtros

| Filtro             | Opções                                                  |
| :----------------- | :------------------------------------------------------ |
| **Tipo de frota**  | Todos / Frota Própria / Terceiros                       |
| **Transportadora** | Dropdown dinâmico com os carriers que têm envios ativos |

## Marcadores no mapa

### Frota própria

* Ícone de caminhão com **posição GPS ao vivo** (atualizada a cada 30s)
* Heading (direção do veículo)
* Popup "Ao vivo" ao clicar

### Carriers terceirizados

* Marcador circular colorido por carrier na **coordena do destinatário**
* Legenda dinâmica no canto inferior esquerdo

## Atualização automática

O mapa atualiza de duas formas:

1. **SSE (Server-Sent Events)** — quando há `shipment_update`, o mapa recarrega instantaneamente
2. **Polling a cada 30s** — fallback caso o SSE não funcione (rede instável, etc.)

## Ações

| Ação                        | Como                                                                              |
| :-------------------------- | :-------------------------------------------------------------------------------- |
| **Atualizar manualmente**   | Clique no botão Atualizar no topo                                                 |
| **Selecionar envio**        | Clique no marcador no mapa ou no item da sidebar                                  |
| **Ver detalhe do shipment** | Clique no ícone de olho na sidebar → navega para `/admin/shipments/:trackingCode` |

## Requisitos

* `VITE_MAPTILER_KEY` configurada no ambiente (tiles do mapa)
* Motoristas da frota própria precisam estar com o app aberto e GPS ativo
* O broadcast GPS só funciona quando o shipment está `OUT_FOR_DELIVERY` — não rastreia o motorista fora do horário de entrega

<Tip>
  Para acompanhar um motorista específico, filtre por "Frota Própria" e clique no marcador. O mapa faz zoom automático na posição dele.
</Tip>