Rastreamento de Entregas

A tela de Rastreamento de Entregas (/admin/delivery-tracking) exibe todas as entregas ativas em um mapa interativo ao lado de uma tabela detalhada com filtros. É a visão operacional padrão para monitorar pedidos em trânsito.

Acesso

Menu lateral → Operações → Rastreamento (ícone de pin de mapa).

Requer permissão orders.view.all.

---

Interface

┌─ Cabeçalho ────────────────────────────────────────────┐
│  [Todos][Confirmado][Preparando][Pronto][Em Entrega]    │
│                              [Ao Vivo ●][▶ Demo]        │
├─────────────────────────────┬──────────────────────────┤
│                             │  #    Cliente  Status ETA │
│        MAPA (60%)           │  0001 Ana      ● Entrega  │
│   (LogisticsMap)            │  0002 Carlos   ● Pronto   │
│                             │  ...                      │
└─────────────────────────────┴──────────────────────────┘

• Filtros de status — Chips no cabeçalho filtram o mapa e a tabela simultaneamente.
• Toggle Ao Vivo / Demo — Alterna entre dados reais e simulados (ver abaixo).
• Mapa — Mesma engine do Dashboard de Logística (Mapbox GL, cluster de filiais, rotas LOD).
• Tabela — DataTable com colunas: #, Cliente, Origem, Status, Bairro, Tempo, ETA.

---

Mapa

O mapa usa o mesmo componente LogisticsMap do Dashboard de Logística:

• Filiais exibidas com agrupamento automático (clustering).
• Entregadores como pontos dourados com seta de direção.
• Rotas aparecem apenas para o pedido selecionado (clique na linha da tabela ou no marcador do mapa).
• Centro inicial = filial HQ → primeira filial com coordenadas → fallback SP.

Ao selecionar um pedido na tabela, o mapa voa (flyTo) para a posição do entregador com zoom 16.

---

Coluna ETA

A coluna ETA mostra o tempo estimado de chegada em minutos:

• ~12m em dourado → tempo calculado pela Mapbox Directions API (rota filial → destino).
• Ícone GPS verde → entregador rastreado, mas rota ainda sendo calculada.
• Ícone GPS cinza → sem posição GPS disponível.

O ETA usa a filial de origem do pedido como ponto de partida (não a posição atual do entregador), tornando a rota estável durante toda a entrega.

---

Toggle Ao Vivo / Demo

Localizado no canto direito da barra de filtros:

Modo	Dados
● Ao Vivo	WebSocket /delivery + polling REST 30s. Indicador de conexão no mapa.
▶ Demo	10 entregas animadas usando coordenadas reais das suas filiais como origem.

No Modo Demo, os pedidos simulados exibem comportamentos distintos:

• Pedidos Atrasados: movem-se lentamente (~4,5s por passo), simulando tráfego parado.
• Pedidos Próximo ao destino: movem-se rapidamente (~1,1s por passo).
• Pedidos Em Entrega: velocidade normal (~1,8s por passo).

---

Indicador de Conexão

No canto superior direito do mapa (apenas no modo Ao Vivo):

Estado	Cor	Texto
Conectado	Verde	Ao vivo
Reconectando	Âmbar	Reconectando...
Desconectado	Cinza	Desconectado

Em caso de desconexão, o sistema faz polling REST automaticamente a cada 30s como fallback.

---

Dados Técnicos

Item	Valor
Endpoint REST	GET /t/:slug/delivery/active-locations
WebSocket	/delivery → evento adminLocationUpdate
Filiais	GET /t/:slug/admin/branches
Variável de ambiente	VITE_MAPBOX_TOKEN

Segurança

• O endpoint GET /t/:slug/delivery/:orderId/last-location requer autenticação JWT + permissão orders.view.all.
• As posições são armazenadas no Redis com prefixo de tenant (delivery:loc:{tenantId}:{orderId}), impedindo vazamento entre tenants.

---

Entregadores Próprios (Driver Registry — W14)

Os entregadores são cadastrados no módulo drivers (backend/src/drivers/). O mapa exibe entregadores que:

1. Estão com status: 'on_route'
2. Possuem lastKnownLocation atualizado recentemente

Para atribuir um entregador a um pedido, use POST /t/:slug/admin/drivers/auto-assign/:orderId ou POST /t/:slug/admin/drivers/:id/assign/:orderId.

Veja: Cadastro de Entregadores