Configuracao de Viagens em Grupo

Viagens em grupo permitem que um unico cliente desbloqueie multiplos veiculos para andar com amigos, familia ou grupos. A carteira ou pacote do piloto principal cobre todos os veiculos, facilitando a organizacao de passeios em grupo.

Visao Geral

Quando viagens em grupo estao habilitadas, clientes podem desbloquear veiculos adicionais alem do seu. Todas as viagens no grupo sao vinculadas a viagem pai para fins de cobranca e rastreamento. Isso e ideal para turistas, familias ou qualquer cenario onde multiplas pessoas querem andar juntas.

Principais Recursos

• Sessoes multi-veiculo - Um cliente, multiplos veiculos
• Cobranca compartilhada - Piloto principal paga por todos os membros do grupo
• Integracao com pacotes - Pacotes de viagem podem definir limites de tamanho do grupo
• Limites configuraveis - Defina tamanho maximo do grupo por localizacao
• Rastreamento em tempo real - Todas as viagens do grupo vinculadas a pai

Como Funciona

Cliente desbloqueia primeiro veiculo (Viagem Pai)
         |
Cliente toca em "Adicionar piloto" ou escaneia outro veiculo
         |
Sistema verifica limite do grupo (pacote ou configuracoes)
         |
Dentro do limite?
    |-- Sim -> Cria viagem filha vinculada a pai
    |         Cliente desbloqueia veiculo adicional
    |         Cobranca vinculada a viagem pai
    +-- Nao  -> Exibe "Limite do grupo atingido"
             Cliente nao pode adicionar mais pilotos

Habilitando Viagens em Grupo

Configuracoes da Subconta

Opcoes de Configuracao

Limites de Grupo Baseados em Pacote

Pacotes de viagem podem substituir o limite de grupo da subconta com sua propria configuracao max_riders. Isso permite que pacotes premium oferecam grupos maiores.

Ordem de Prioridade

1. Pacote Ativo - Se cliente tem pacote com max_riders > 1, usa limite do pacote
2. Configuracoes da Subconta - Fallback para other.group_rides_max
3. Padrao - Usa DEFAULT_GROUP_RIDE_LIMIT (4)

Exemplo de Configuracao de Pacote

Quando um cliente com "Tour em Grupo" desbloqueia um veiculo, ele pode adicionar ate 7 pilotos adicionais (8 total), independente do limite padrao da subconta.

Estrutura da Viagem

Viagens Pai e Filha

Viagens em grupo usam um relacionamento pai-filho:

Viagem Pai (Veiculo do cliente)
    |
    +-- Viagem Filha 1 (Veiculo do amigo)
    +-- Viagem Filha 2 (Veiculo do familiar)
    +-- Viagem Filha 3 (Veiculo de outro amigo)

Viagem Pai:

• Criada primeiro quando cliente desbloqueia
• is_group_ride_parent = true
• Toda cobranca cobrada na pai

Viagens Filhas:

• Criadas quando veiculos adicionais desbloqueados
• parent_ride_id referencia a pai
• Cobranca acumula para viagem pai

Campos do Banco de Dados

Tabela Rides:

Experiencia do Cliente

Iniciando uma Viagem em Grupo

1. Primeiro veiculo - Cliente escaneia/desbloqueia seu veiculo normalmente
2. Adicionar pilotos - Toca em "Adicionar Piloto" ou escaneia veiculos adicionais
3. Confirmar - Cada veiculo adicional mostra vinculado ao grupo
4. Andar junto - Todos os veiculos ativos sob uma sessao

Durante a Viagem

• Todos os membros do grupo pilotam independentemente
• Piloto pai pode ver todas as viagens ativas
• Pausar/retomar afeta veiculos individuais
• Pai pode encerrar todas as viagens de uma vez

Encerrando Viagens em Grupo

Quando a viagem pai termina:

1. Todas as viagens filhas ativas sao solicitadas a encerrar
2. Cobranca total calculada em todas as viagens
3. Cobranca unica na carteira/cartao do piloto pai
4. Recibo mostra detalhamento por veiculo

Consideracoes de Cobranca

Como Cobranças Funcionam

Todos os custos de viagem em grupo sao cobrados do piloto pai:

Viagem Pai: 30 min x R$1,25 = R$37,50
Viagem Filha 1: 28 min x R$1,25 = R$35,00
Viagem Filha 2: 32 min x R$1,25 = R$40,00
Viagem Filha 3: 25 min x R$1,25 = R$31,25
-----------------------------------
Total: R$143,75 cobrado do pai

Consumo de Pacote

Ao usar um pacote de viagem:

• Tempo e deduzido proporcionalmente
• Todos os pilotos compartilham beneficios do pacote
• max_riders do pacote determina tamanho do grupo
• Tempo excedente cobrado nas taxas padrao

Taxas de Desbloqueio

Referencia da API

Obter Limite Efetivo de Grupo

import { getEffectiveGroupRideLimit } from '@/lib/rides/group-session'

const result = await getEffectiveGroupRideLimit(admin, customerUuid, subaccountId)
// Retorna: { limit: number, source: 'package' | 'settings' | 'default', packageInfo? }

Contar Filhas Ativas do Grupo

import { countActiveGroupChildren } from '@/lib/rides/group-session'

const childCount = await countActiveGroupChildren(admin, parentRideId)
// Retorna: numero de viagens filhas ativas

Verificar Propriedade da Viagem

import { rideBelongsToCustomer } from '@/lib/rides/group-session'

const isOwner = rideBelongsToCustomer(ride, customer, userId)
// Retorna: boolean

Melhores Praticas

Definindo Limites de Grupo

1. Considere disponibilidade de veiculos - Limites maiores podem esgotar frota
2. Combine com publico-alvo - Turistas podem precisar de grupos maiores
3. Balance valor do pacote - Pacotes premium podem oferecer grupos maiores
4. Consideracoes de seguranca - Grupos grandes podem precisar de coordenacao

Consideracoes Operacionais

1. Consciencia da equipe - Treine equipe em suporte a viagens em grupo
2. Proximidade de veiculos - Grupos podem estacionar juntos
3. Comunicacao com cliente - Instrucoes claras para inicio de grupo
4. Tratamento de fim de viagem - Ajude grupos a encerrar todas as viagens

Design de Pacotes

1. Crie pacotes de grupo - Pacotes dedicados para grupos
2. Precifique apropriadamente - Descontos de grupo encorajam uso
3. Marketing claro - Destaque max_riders na descricao do pacote
4. Alocacao de tempo - Considere duracoes maiores para grupos

Solucao de Problemas

Nao Consegue Adicionar Mais Pilotos

1. Verifique limite atingido - Conte viagens filhas ativas
2. Verifique pacote - Pacote suporta mais pilotos?
3. Verifique configuracoes - Configuracao group_rides_max da subconta
4. Pai ativa - Viagem pai ainda deve estar ativa

Problemas de Cobranca

1. Verifique viagem pai - Todas as cobranças vao para pai
2. Verifique vinculacao de filhas - parent_ride_id deve estar definido
3. Revise pacote - Beneficios do pacote podem aplicar diferentemente

Viagem Filha Nao Vinculada

1. Verifique criacao da viagem - parent_ride_id foi definido?
2. Verifique correspondencia de cliente - Mesmo cliente para todas as viagens
3. Revise fluxo de desbloqueio - Opcao de viagem em grupo selecionada?

Esquema do Banco de Dados

Consultas Principais

Encontrar viagem pai:

SELECT * FROM rides
WHERE customer_uuid = 'uuid'
  AND ride_status IN ('active', 'paused')
  AND is_group_ride_parent = true

Contar tamanho do grupo:

SELECT COUNT(*) FROM rides
WHERE parent_ride_id = 'parent-uuid'
  AND ride_status IN ('active', 'paused')

Obter total do grupo:

SELECT SUM(total_cost) as group_total
FROM rides
WHERE parent_ride_id = 'parent-uuid'
   OR id = 'parent-uuid'