Encerrando Viagens em Grupo

O recurso Encerrar Viagens em Grupo permite que um cliente que iniciou uma sessao de viagem em grupo encerre todas as viagens daquela sessao simultaneamente. Isso e usado quando uma pessoa alugou multiplos veiculos para um grupo (familia, amigos, grupo de turismo) e precisa encerrar toda a sessao de uma vez.

Visao Geral

Viagens em grupo permitem que um cliente inicie multiplos veiculos para um passeio em grupo. Quando o grupo termina, eles precisam de uma forma eficiente de encerrar todas as viagens juntas. O recurso Encerrar Viagens em Grupo:

• Encerra a viagem pai e todas as viagens filhas em uma sessao de grupo
• Calcula e cobra tarifas finais para cada viagem
• Envia comandos de bloqueio para todos os veiculos afetados
• Retorna um resumo de todas as viagens encerradas

Conceitos Principais

Principais Recursos

• Baseado em sessao - Encerra viagens vinculadas a uma viagem pai especifica
• Seguranca primeiro - Bloqueia todos os veiculos apos encerrar
• Cobranca abrangente - Calcula tarifa precisa para cada viagem
• Resiliencia a erros - Continua processando mesmo se viagens individuais falharem
• Resposta detalhada - Reporta sucesso/falha para cada viagem

Como Viagens em Grupo Funcionam

Iniciando uma Viagem em Grupo

Durante a Viagem em Grupo

• Todas as viagens rodam independentemente (cobranca separada, rotas separadas)
• Cliente pode pausar/retomar viagens individuais
• Cliente pode encerrar viagens individuais se alguem sair mais cedo
• Painel mostra todas as viagens vinculadas pelo relacionamento pai

Encerrando a Sessao de Grupo

Ao encerrar todo o grupo:

1. Cliente toca em "Encerrar Todas as Viagens" no app
2. App chama o endpoint end-all com o ID da viagem pai
3. Sistema valida que a viagem pai existe e esta ativa
4. Sistema encerra pai + todas as viagens filhas ativas
5. Cliente ve resumo de todas as viagens encerradas e cobranças totais

Endpoint da API

Requisicao

POST /api/mobile/rides/end-all/

Autenticacao: Obrigatoria (token JWT do cliente)

Corpo da Requisicao:

{
  "parent_ride_id": "uuid-da-viagem-pai",
  "end_location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Resposta

Sucesso (200 OK):

{
  "ok": true,
  "ended_rides": [
    {
      "ride_id": "uuid-pai",
      "ride_number": "R-12345",
      "vehicle_id": "VH-001",
      "final_amount_cents": 685,
      "duration_seconds": 912,
      "distance_m": 2340,
      "status": "completed",
      "is_parent": true
    },
    {
      "ride_id": "uuid-filha-1",
      "ride_number": "R-12346",
      "vehicle_id": "VH-002",
      "final_amount_cents": 445,
      "duration_seconds": 654,
      "distance_m": 1890,
      "status": "completed",
      "is_parent": false
    }
  ],
  "total_charged_cents": 1130,
  "warnings": []
}

Sucesso Parcial (200 OK com avisos):

{
  "ok": true,
  "ended_rides": [
    {
      "ride_id": "uuid-pai",
      "ride_number": "R-12345",
      "vehicle_id": "VH-001",
      "final_amount_cents": 685,
      "status": "completed"
    }
  ],
  "total_charged_cents": 685,
  "warnings": [
    {
      "ride_id": "uuid-filha-1",
      "ride_number": "R-12346",
      "message": "Falha ao bloquear veiculo - timeout de comando"
    }
  ]
}

Respostas de Erro:

Configuracao de Viagem em Grupo

Maximo de Viagens por Sessao

Configure o maximo de veiculos permitidos em uma unica sessao de grupo:

Localizacao: Configuracoes > Outros

{
  "group_rides_max": 5
}

Casos de Uso Comuns

Detalhes do Processamento

Sequencia de Encerramento de Viagem

Para cada viagem no grupo (pai + filhas):

1. Atualizacao de Status

   • Define ride_status como completed
   • Registra timestamp ended_at
   • Registra coordenadas end_location

2. Calculo de Tarifa

   • Calcula cobranças de tempo ativo
   • Calcula cobranças de tempo de pausa
   • Aplica quaisquer descontos (codigos promo, assinaturas)
   • Aplica limite diario se atingido
   • Aplica preco minimo se aplicavel

3. Deducao da Carteira

   • Debita valor final da carteira do cliente
   • Registra transacao no historico da carteira
   • Trata saldo negativo se fundos insuficientes

4. Comandos do Veiculo

   • Envia comando de bloqueio para o veiculo
   • Desativa acelerador (para veiculos suportados)
   • Atualiza status do veiculo para "disponivel"

5. Notificacoes

   • Envia notificacao push de conclusao de viagem
   • Inclui valor da cobranca final
   • Links para recibo da viagem

Tratamento de Erros

O sistema usa abordagem de "melhor esforco":

• Se uma viagem filha falhar ao encerrar, outras ainda processam
• Falhas de bloqueio de veiculo sao registradas mas nao bloqueiam conclusao
• Erros de cobranca sao registrados para revisao manual
• Cliente ve avisos para quaisquer problemas

O Que Pode Falhar

Validacao de Zona

Ao encerrar viagens em grupo, o sistema valida zonas de estacionamento:

Verificacao de Zona de Estacionamento

Cada viagem no grupo e validada:

1. Verifica se end_location esta dentro de uma zona de estacionamento designada
2. Se fora da zona de estacionamento:
   • Verifica se configuracao allow_end_ride_outside_parking_zone e true
   • Se nao permitido, aquela viagem permanece ativa (aviso retornado)
3. Se em zona proibida para estacionamento:
   • Aquela viagem permanece ativa (aviso retornado)
   • Cliente deve mover aquele veiculo para zona valida

Fontes de Localizacao

O sistema usa duas fontes de localizacao para validacao:

A configuracao parking_zone_validation_mode determina qual fonte e usada:

• vehicle_only - Apenas verifica GPS do veiculo
• both - Ambos devem estar em zona valida
• hybrid - Qualquer um pode satisfazer o requisito

Implicacoes de Cobranca

Cobranças de Multiplas Viagens

Cada viagem no grupo e calculada independentemente:

Viagem Pai: R$34,25 (15 min ativo, R$5 desbloqueio, R$1,95/min)
Viagem Filha 1: R$25,25 (10 min ativo + 2 min pausa, R$5 desbloqueio)
Viagem Filha 2: R$22,25 (8 min ativo, R$5 desbloqueio)
────────────────────────────────────────────
Total: R$81,75 cobrado na carteira

Limite Diario Entre Grupo

O limite diario aplica por cliente em todas as viagens do grupo:

Cliente tem limite diario de R$150
Viagem Pai: R$60,00
Viagem Filha 1: R$75,00
Viagem Filha 2: R$90,00 (excederia limite)
────────────────────────────────────────────
Viagem Filha 2 limitada a: R$15,00 (atinge R$150 total)
Total cobrado: R$150,00

Saldo Insuficiente na Carteira

Se saldo da carteira for insuficiente:

1. Todas as viagens ainda encerram normalmente
2. Saldo da carteira fica negativo
3. Cliente nao pode iniciar novas viagens ate recarregar
4. Recarga automatica aciona se habilitada

Casos de Uso

Dia em Familia

1. Pai inicia viagem para si mesmo (viagem pai)
2. Pai inicia viagens para 2 filhos (viagens filhas)
3. Familia anda junto por 45 minutos
4. No destino, pai toca em "Encerrar Todas as Viagens"
5. Todos os 3 veiculos bloqueiam, cobranca unica na carteira

Tour Guiado

1. Guia de turismo inicia viagem pai
2. Guia inicia 8 viagens filhas para participantes do tour
3. Grupo completa rota de tour de 2 horas
4. No ponto final do tour, guia encerra todas as viagens
5. Todos os 9 veiculos seguros, total cobrado na conta do guia

Grupo de Amigos se Separando

1. Um amigo inicia 4 viagens para o grupo
2. Apos 30 minutos, uma pessoa sai mais cedo
3. Aquela viagem individual e encerrada separadamente
4. Depois, 3 viagens restantes encerradas juntas via end-all
5. Apenas viagens filhas ativas sao afetadas pelo end-all

Gerenciamento no Painel

Visualizando Viagens em Grupo

Na lista de Viagens:

• Viagens pai mostram indicador (icone de grupo)
• Filtro disponivel para mostrar apenas viagens em grupo
• Clique na viagem pai para ver todas as filhas vinculadas

Pagina de Detalhes da Viagem

Para viagens pai:

• Secao "Viagens Filhas" lista todas as viagens na sessao
• Clique em qualquer viagem filha para ver seus detalhes
• Mostra estatisticas agregadas (duracao total, receita total)

Acoes Administrativas

Operadores podem:

• Encerrar viagens individuais de uma sessao de grupo
• Encerrar todas as viagens em um grupo do painel
• Ver historico de viagens em grupo para um cliente

Notas de Integracao

Para Desenvolvedores de App

Ao implementar o recurso Encerrar Viagens em Grupo:

1. Rastreie ID da Viagem Pai - Armazene o ID da viagem pai ao iniciar sessao de grupo
2. Permissao de Localizacao - Garanta acesso a localizacao antes de chamar
3. UX de Confirmacao - Mostre preview de todas as viagens sendo encerradas
4. Estado de Carregamento - Endpoint pode levar varios segundos para multiplas viagens
5. Exibicao de Erro - Mostre quaisquer avisos para o cliente
6. Tela de Recibo - Navegue para resumo apos conclusao

Tempos de Resposta Esperados

Tratamento de Erros

Se a requisicao exceder timeout:

• Verifique status de viagens individuais antes de tentar novamente
• Algumas viagens podem ter encerrado com sucesso
• Mostre estado atual para o cliente
• Apenas viagens ativas restantes serao processadas no retry

Solucao de Problemas

"parent_ride_id required"

Causa: Corpo da requisicao faltando o ID da viagem pai Resolucao: Garanta que app envia o UUID da viagem pai armazenado

"Ride is not a group ride parent"

Causa: O ID de viagem fornecido e uma viagem filha, nao a pai Resolucao: Use o ID original da viagem pai de quando a sessao iniciou

"Failed to lock vehicle"

Causa: Comando IoT do veiculo falhou Impacto: Viagem encerra mas veiculo pode permanecer desbloqueado Resolucao: Bloqueie manualmente via painel ou despache equipe de campo

"Location not in valid zone"

Causa: Um ou mais veiculos estao em zona proibida/proibida para estacionamento Resolucao:

• Aquelas viagens especificas permanecem ativas
• Cliente deve mover aqueles veiculos para estacionamento valido
• Outras viagens no grupo ainda encerram com sucesso

Timeout Durante Processamento

Causa: Problemas de rede ou alta carga Resolucao:

1. Aguarde 30 segundos
2. Verifique lista de Viagens para status atual
3. Encerre manualmente quaisquer viagens ativas restantes

Permissoes e Seguranca

Autenticacao

• Requer token JWT de cliente valido
• Token nao deve estar expirado
• Conta do cliente deve estar ativa (nao suspensa)

Autorizacao

• Cliente so pode encerrar suas proprias viagens em grupo
• Viagem pai deve pertencer ao cliente autenticado
• Nao pode encerrar sessao de grupo de outro cliente
• Endpoints admin existem para intervencao de operador

Limitacao de Taxa

Para prevenir abuso:

• Maximo de 10 requisicoes por minuto por cliente
• Ajuda a prevenir requisicoes duplicadas acidentais

Artigos Relacionados

• Gerenciando Viagens
• Pagina de Detalhes da Viagem
• Pausa de Viagens