Mapa — Rastreamento e Rotogramas

Android: MapFragment — OSMDroid

Visualização de mapa com rastreamento em tempo real de veículos e exibição de rotogramas (rotas cadastradas). O Android usa OSMDroid (OpenStreetMap); o iOS usa MapKit.

Biblioteca de Mapas

Plataforma	Biblioteca	Notas
Android	OSMDroid (OpenStreetMap)	Inicializado em `MapFragment.onCreate()` via `Configuration.getInstance()`. Tiles armazenados em cache local.
iOS	MapKit (Apple Maps)	Anotações nativas com `MKAnnotationView`. Rota via `MKPolyline`.

Rotogramas

Rotas cadastradas no sistema (rotogramas) são exibidas como polylines sobre o mapa. Os dados são buscados e desempacotados do wrapper data[0]:

// Estrutura da resposta v1
{
  "data": [{
    "rotogram_route": {
      "coordinates": [[lng, lat], [lng, lat], ...]   // GeoJSON: longitude ANTES de latitude
    },
    "instruction": [...]
  }]
}

Ordem das coordenadas: o formato GeoJSON retorna [longitude, latitude]. Inverter para [latitude, longitude] ao criar pontos no OSMDroid (GeoPoint(lat, lng)) e no MapKit (CLLocationCoordinate2D(latitude:, longitude:)).

Rastreamento de Veículos

Marcadores de veículos são exibidos com ícones diferenciados por status. A posição é atualizada periodicamente via polling à API ou via push quando disponível.

Pontos autorizados e áreas de risco

Sobre a rota são desenhados os pontos autorizados (marcadores) e as áreas de risco (polígonos vermelhos) da viagem. A mesma feature está presente nas três telas com mapa: Motorista, Gestor e o detalhe do Grid — Android + iOS.

Endpoint em STAGING: os pontos vêm do endpoint dedicado GET /v1/trip/{tripId}/rotogram, ainda apontando para a base de homologação http://nginx.surubim.monisat.online/v1 (Android ROTOGRAM_TRIP_BASE/NGINX_URL; iOS stopPointsBase). Pendente a troca para produção https://api.monisystem.com/v1. A rota + instruções continuam vindo de /rotograms/trip/{tripId} (já em produção).

A resposta é um data[]; cada item agrega três listas que são concatenadas num único conjunto de pontos:

{
  "data": [{
    "points":        [ ... ],              // pontos do cliente / autorizados
    "apolice_rules": { "risk_points": [ ... ] }, // áreas de risco da apólice
    "deliveries":    [ ... ]               // pontos de entrega
  }]
}

Classificação por tipo

Cada ponto é classificado por type (com fallback para type_return):

`type` / `type_return`	Renderização	Notas
`risk_area`	Polígono vermelho	Geometria em `location.coordinates` (GeoJSON `Polygon`: 1º anel = contorno externo, demais = buracos; cada par `[lon, lat]`). Sempre visível — não segue o toggle.
`client`	Marcador (ponto do cliente)	Centro em `data.center` como `[lon, lat]`.
`authorized`	Marcador (ponto autorizado)	—
`delivery`	Marcador de entrega (pino azul com caixa)	Ponto de entrega da rota.

Toggle, aproximação e cache

Toggle "mostrar todos": alterna a exibição de todos os pontos. Os polígonos de risco ficam sempre visíveis.
Banner de aproximação (só na tela do motorista): ao se aproximar de um ponto por distância, o ponto é exibido mesmo com o toggle desligado; usa histerese para evitar piscar entre entrar/sair do raio.
Persistência: a preferência do toggle é salva localmente no Android; no iOS o botão é protegido por flag remota (ver Motorista).
Cache offline: pontos e áreas de risco são persistidos na sessão do motorista (DriverSessionCache / CachedDriverSession) e redesenhados sem rede.

Renderização: Android desenha via osmdroid — Polygon (áreas de risco) e Marker (pontos). iOS usa MapKit — MKPolygon + MKPolygonRenderer (áreas) e anotações StopPointAnnotation (pontos). Como o payload é GeoJSON, inverter [lon, lat] → [lat, lng] ao criar as coordenadas (mesma regra dos rotogramas acima).

Endpoints

GET /v1/trip/{tripId}/rotogram

Pontos autorizados + áreas de risco + entregas da viagem numa só chamada (data[] { points, apolice_rules.risk_points, deliveries }). Base em STAGING (http://nginx.surubim.monisat.online/v1) — trocar para https://api.monisystem.com/v1 quando subir para produção. Itens com type_return == "risk_area" viram polígono; os demais viram marcadores classificados por type_return (client/authorized/delivery).

GET /v1/rotograms/{routeId}?_detail=true

Retorna um rotograma (pelo id da rota) com coordenadas e instruções de navegação. Acesso via data[0].rotogram_route.coordinates e data[0].instruction.

GET /v1/rotograms/trip/{tripId}?_detail=true

Endpoint consolidado por viagem. Devolve o rotograma principal + alternativas da viagem inteira numa só chamada (data[0].rotogram_route). É o usado por Driver, Manager e pelo detalhe do Grid — base de produção https://api.monisystem.com/v1. Substitui as chamadas legadas listar_rotograma/routesById.

GET /v1/vehicles?type=V

Lista veículos rastreados. Filtrar por type == "V" para obter apenas veículos com rastreador ativo.

GET /v1/trackers?vehicle_id=...

Última posição GPS do rastreador associado ao veículo. Usado para posicionar o marcador no mapa.

Configuração OSMDroid (Android)

// Inicialização obrigatória antes de usar o mapa
Configuration.getInstance().load(context, PreferenceManager.getDefaultSharedPreferences(context))
Configuration.getInstance().userAgentValue = BuildConfig.APPLICATION_ID

O GridTripFragment também chama Configuration.getInstance() no onCreateView, pois pode navegar para o mapa. Isso garante que o OSMDroid esteja configurado antes da transição.