Driver — Viagem Ativa

Android: /ui/driver/ · /ui/travels/ · TripFragment · TripManagementFragment

Módulo exclusivo para usuários com papel motorista. Exibe a viagem ativa com navegação assistida, botões de gerenciamento (iniciar, pausar, finalizar) e rastreamento de localização em tempo real.

Acesso restrito: Motoristas acessam apenas nav_trip_menu_driver / nav_trips_buttons na Home. Os demais módulos são bloqueados pela lógica de papel (user_role == "motorista").

Fragmentos do Módulo

Fragmento	Pacote	Responsabilidade
`TripFragment`	`/ui/travels/`	Tela principal da viagem ativa do motorista
`TripManagementFragment`	`/ui/travels/`	Ações de gerenciamento: iniciar, pausar, finalizar viagem
`FragmentButtonsTravels`	`/ui/travels/`	Botões rápidos de ação sobre a viagem
`DriverTripViewModel`	`/ui/travels/`	Lógica de negócio e chamadas à API

Viagem Ativa

O motorista visualiza apenas a viagem atribuída a ele. Os dados são buscados via GET /v1/trips?driver_id=... ou a viagem específica quando há uma em andamento. O fragment usa o DriverTripViewModel para gerenciar o estado.

Gerenciamento de Viagem

Ação	Endpoint	Condição
Iniciar	`POST /v1/trips/{id}/start`	Viagem no status agendado/pendente
Pausar	`POST /v1/trips/{id}/pause`	Viagem em andamento
Finalizar	`POST /v1/trips/{id}/finalize`	Viagem em andamento ou pausada

Rastreamento de Localização

Para usuários com papel motorista, o HomeFragment.onResume() solicita permissões de localização em foreground e background. A posição GPS é enviada ao backend periodicamente via serviço de background (FusedLocationProviderClient).

// Verificação de papel no onResume
if (userRole == "motorista") {
    requestForegroundLocationPermission()
    requestBackgroundLocationPermission()
}

Prominent Disclosure (Android 13+): antes de solicitar permissão de localização em background, o app exibe obrigatoriamente um diálogo explicativo exigido pelo Google Play. Esse dialog deve descrever claramente por que a localização em background é necessária.

Navegação Turn-by-Turn (NavigationManager1)

Atualizado junho/2026

O NavigationManager1 conduz a navegação assistida no mapa (OSMDroid) com instruções faladas via TextToSpeech. Cada instrução é um NavigationInstruction, montado a partir de rotogram_instruction da API. O campo type_id mapeia o ícone/voz da manobra:

`type_id`	Manobra	`type_id`	Manobra
`0` / `1`	continue (siga em frente)	`4` / `5`	destination
`2` / `-2`	turn_right / turn_left	`6`	roundabout
`3` / `-3`	turn_sharp_right / turn_sharp_left	`7` / `-7`	keep_right / keep_left
`8`	turn_around (retorno em U)	valores negativos = à esquerda

As coordenadas da instrução vêm como [lng, lat] (ordem GeoJSON) — latitude = coordinates[1], longitude = coordinates[0].

Cache Offline da Sessão (DriverSessionCache)

Atualizado junho/2026

O DriverSessionCache é o equivalente Android do DriverCacheManager do iOS: guarda, num único blob por tripId_routeId, tudo que o motorista precisa para continuar a viagem sem rede.

Lacuna que isto fecha: antes, no Android, só a geometria da rota + coordenadas (e a info textual, via worker TripAtributtedWorkService) sobreviviam offline. Instruções turn-by-turn, rotas alternativas e pontos de parada se perdiam. Agora tudo é persistido junto.

Campo do blob	Conteúdo
`mainGeoJson`	Geometria da rota principal (`rotogram_route` com `coordinates`)
`mainInstructions`	Instruções turn-by-turn da rota principal
`alternatives`	Rotas alternativas — pontos + instruções de cada uma
`stopPoints`	Pontos de parada (id, nome, lat/lng, categoria)
`coordStart` / `coordDestination`	Coordenadas de origem e destino
`routeName`, `startName`, `destinationName`	Textos da viagem
`forecastStart` / `forecastEnd`	Previsões de início/fim
`createdByRoute`, `createdByTrip`, `driverNames`	Criadores e motoristas

Cada save* persiste o blob inteiro (mesmo padrão do iOS), então a sessão no disco é sempre consistente. A chave (driver_session_{tripId}_{routeId}, prefs driver_session_cache) é por viagem + rota para não misturar dados entre viagens que reusem a mesma rota. load() retorna false se não há cache para a viagem/rota.

Helpers relacionados desta entrega: TripCacheCleaner (limpeza de cache de viagens) e NavigationManager1 (consome as instruções cacheadas para navegar offline).

Paridade iOS: mesma estrutura de blob consolidado no DriverCacheManager. O objetivo é que Android e iOS tenham exatamente o mesmo comportamento offline na viagem do motorista.

ViewModels e Arquitetura

Classe	Responsabilidade
`TripViewModel`	Estado e dados da viagem ativa
`TripViewModelNew`	Versão migrada para API v1
`DriverTripViewModel`	Ações específicas de motorista (start/pause/finalize)
`TripViewModelFactory`	Factory para injeção de dependências no ViewModel

SharedPreferences relevantes

Nome	Chave	Uso
`user_id`	`user_role`	Papel do usuário: `"motorista"` habilita o módulo
`driver`	`driver`	Boolean que controla exibição de botões de motorista em Config
`jwt_tokens`	`jwt_token`	Bearer JWT para chamadas v1
`driver_session_cache`	`driver_session_{tripId}_{routeId}`	Blob offline consolidado da sessão de viagem (Gson)