Como as Zonas de Geofencing Funcionam

Este artigo fornece uma explicação técnica aprofundada de como as zonas funcionam no Levy Fleets, cobrindo o pipeline de aplicação, validação de término de viagem, registro de eventos e notificações ao cliente.

Visão Geral da Arquitetura

O Levy Fleets usa zonas em dois contextos principais:

1. Aplicação de Telemetria em Tempo Real

Quando um veículo envia coordenadas GPS (latitude/longitude) durante uma viagem ativa, o sistema:

• Carrega todas as zonas de limite de velocidade e zonas proibidas para a subconta do veículo
• Avalia se a localização do veículo está dentro de algum polígono de zona
• Envia comandos IoT para ajustar a velocidade ou desativar o motor conforme necessário
• Registra eventos de entrada/saída de zona
• Envia notificações ao cliente

2. Validação de Término de Viagem

Quando um cliente tenta encerrar uma viagem, o sistema:

• Carrega todas as zonas de estacionamento, estacionamento proibido e zonas proibidas
• Avalia se o local de término satisfaz os requisitos de estacionamento
• Bloqueia ou permite o término da viagem com base na pertinência à zona

Estrutura de Dados da Zona

As zonas são armazenadas com as seguintes propriedades principais:

Formato GeoJSON

Os limites das zonas são armazenados como objetos Feature GeoJSON:

{
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [-46.6339, -23.5505],
        [-46.6325, -23.5505],
        [-46.6325, -23.5491],
        [-46.6339, -23.5491],
        [-46.6339, -23.5505]
      ]
    ]
  }
}

Fluxo de Aplicação em Tempo Real

O pipeline de aplicação executa em cada atualização de telemetria GPS dos veículos durante viagens ativas.

Etapa 1: Condições de Acionamento

A aplicação é acionada quando:

• Uma atualização GPS é recebida de um veículo
• O veículo tem uma viagem ativa (ride_status = 'in_progress')
• O veículo tem um IMEI IoT válido configurado
• Coordenadas válidas são fornecidas (latitude e longitude finitas)

Etapa 2: Carregamento de Zonas

O sistema consulta todas as zonas speed_limit e no_go para a subconta do veículo que não estão excluídas.

Etapa 3: Avaliação de Ponto-no-Polígono

Para cada zona, o sistema usa um algoritmo de ray-casting para determinar se a localização do veículo está dentro do polígono:

1. Projeta um raio do ponto até o infinito
2. Conta quantas vezes o raio cruza as bordas do polígono
3. Contagem ímpar = dentro, Contagem par = fora

O sistema avalia a posição atual do veículo contra todas as zonas carregadas e as categoriza:

• Zonas de velocidade: Todas as zonas speed_limit contendo o veículo
• Zonas proibidas: Todas as zonas no_go contendo o veículo

Etapa 4: Determinar Restrições Ativas

Para zonas de velocidade sobrepostas:

• O sistema calcula o limite de velocidade efetivo para cada zona
• Se a zona tem um valor speed_limit_kph, ele usa esse valor
• Caso contrário, recorre à configuração slow_speed_zone_limit_kph da subconta
• O limite mais baixo entre todas as zonas sobrepostas é aplicado

Para zonas proibidas:

• Qualquer zona proibida contendo o veículo aciona o desligamento do motor
• Apenas uma zona proibida precisa corresponder para aplicação

Etapa 5: Despacho de Comando IoT

Com base na avaliação, comandos IoT são enviados ao veículo para aplicar limites de velocidade ou desativar o motor.

Etapa 6: Deduplicação de Comandos

Para evitar tráfego IoT desnecessário, os comandos são deduplicados:

• Se o veículo já está na mesma zona com o mesmo limite de velocidade, nenhum comando é enviado
• O estado atual da zona do veículo é rastreado:
  • current_speed_limit_zone_id
  • current_speed_limit_kph
  • current_no_go_zone_id
  • engine_disabled_by_zone

Etapa 7: Atualizações de Estado

Após o despacho bem-sucedido do comando, o registro do veículo é atualizado com o novo estado da zona e timestamp de aplicação.

Validação de Término de Viagem

Quando um cliente tenta encerrar uma viagem, o sistema valida sua localização contra as regras de zona.

Fluxo de Validação

1. Carregar todas as zonas (não filtradas por tipo)
2. Obter dados de localização:
   • devicePoint: Coordenadas GPS do telefone do cliente (do corpo da requisição)
   • vehiclePoint: Últimas coordenadas GPS conhecidas do veículo (da tabela de veículos)
3. Determinar modo de validação das configurações da subconta
4. Avaliar pertinência à zona para cada ponto relevante
5. Retornar resultado (permitir ou bloquear com código de erro)

Regras de Validação

Para cada ponto sendo validado:

• Verificar se o ponto está dentro de QUALQUER zona de estacionamento (type = 'parking')
• Verificar se o ponto está dentro de QUALQUER zona proibida (type = 'no_go')
• Verificar se o ponto está dentro de QUALQUER zona de estacionamento proibido (type = 'no_parking')

Fórmula de Resultado:

valid = inParking && !inNoGo && !inNoParking

Prioridade de Zonas

Quando as zonas se sobrepõem, a seguinte prioridade se aplica:

1. Zonas proibidas - Sempre bloqueiam, independentemente de outras zonas
2. Zonas de estacionamento proibido - Bloqueiam estacionamento mesmo se dentro de uma zona de estacionamento
3. Zonas de estacionamento - Só válido se não estiver em uma zona proibida ou de estacionamento proibido

Modos de Validação de Zona de Estacionamento

As configurações da subconta controlam como a validação de estacionamento funciona. Configure isso em Configurações -> Outros -> Modo de Validação de Zona de Estacionamento.

Apenas Veículo (Padrão)

• Apenas a localização GPS do veículo é verificada
• A localização do telefone do cliente é ignorada
• Recorre à localização do telefone se a localização do veículo não estiver disponível

Caso de uso: Mais confiável para operações centradas em veículos onde o GPS do telefone pode ser impreciso em ambientes fechados.

Ambos

• Tanto veículo QUANTO telefone do cliente devem estar em uma zona de estacionamento válida
• Se algum estiver faltando, a requisição é rejeitada com location_data_missing
• Modo mais restritivo

Caso de uso: Ambientes de alta segurança onde você quer garantir que o cliente está fisicamente com o veículo.

Híbrido

• Tanto veículo OU telefone do cliente pode estar em uma zona de estacionamento válida
• Modo mais permissivo
• Passa se qualquer ponto disponível satisfizer o requisito

Caso de uso: Áreas com cobertura GPS ruim ou quando flexibilidade é preferida.

Registro de Eventos de Zona

Toda entrada e saída de zona durante viagens ativas é registrada para fins de auditoria e análise.

Dados de Evento Capturados

Visualizando Eventos

Eventos de zona podem ser visualizados:

• Na página de detalhes da viagem (Painel -> Viagens -> [viagem] -> aba Zonas)
• Via consultas ao banco de dados para análises
• Através da API de Parceiros para integrações externas

Notificações ao Cliente

Os clientes recebem notificações push ao entrar ou sair de zonas com aplicação.

Notificações de Zona de Velocidade

Entrando:

Título: "Zona lenta ativada"
Corpo: "Seu veículo agora está limitado a 10 km/h na Zona de Pedestres do Centro."

Saindo:

Título: "Zona lenta liberada"
Corpo: "Você saiu da Zona de Pedestres do Centro. Sua velocidade máxima foi restaurada."

Notificações de Zona Proibida

Entrando:

Título: "Zona proibida detectada"
Corpo: "Controles da viagem pausados na Área de Propriedade Privada. Mova para uma área aprovada para continuar."

Saindo:

Título: "Zona proibida liberada"
Corpo: "Você saiu da Área de Propriedade Privada. Os controles da viagem foram restaurados."

Deduplicação de Notificações

Para evitar spam de notificações:

• Um período de espera de 60 segundos se aplica por combinação zona/evento
• Notificações duplicadas dentro desta janela são suprimidas
• Notificações são registradas para auditoria

Considerações de Precisão do GPS

A precisão do GPS varia com base no ambiente, afetando o comportamento da zona.

Faixas Típicas de Precisão

Proteção de Histerese

Para evitar "oscilação" nos limites da zona devido a ruído do GPS, o sistema implementa histerese:

Histerese de Saída de Zona Proibida:

• O veículo deve transmitir pontos GPS fora da zona por pelo menos 15 segundos antes que a energia do motor seja restaurada
• Evita saídas falsas de uma única leitura GPS que deriva para fora
• Rastreado via timestamp no_go_enforced_at no veículo

Recomendações de Design

1. Zonas de buffer: Deixe margens de 5-10 metros em limites críticos
2. Simplicidade de polígono: Formas mais simples são menos afetadas por tremulação do GPS
3. Dimensionamento de zona: Zonas muito pequenas (< 20m de raio) podem não aplicar de forma confiável
4. Testes: Valide os limites da zona com dispositivos reais em campo

Cache e Desempenho

Cache de Limite de Velocidade

A configuração slow_speed_zone_limit_kph da subconta é cacheada por 60 segundos:

• Reduz consultas ao banco de dados durante processamento de telemetria de alta frequência
• Cache é por subconta
• Alterações nas configurações levam até 60 segundos para propagar

Cache de Velocidade do Modelo do Veículo

A velocidade máxima do modelo do veículo é cacheada por 5 minutos:

• Usado ao restaurar a velocidade após sair de zonas de velocidade
• Cache é por ID do modelo do veículo

Carregamento de Zonas

As zonas são carregadas frescas em cada chamada de aplicação (não cacheadas):

• Garante que alterações de zona entrem em vigor imediatamente
• Consultas são otimizadas com índices em subaccount_id, type e deleted_at

Dicas de Desempenho

1. Limite a contagem de zonas: Menos zonas = avaliação mais rápida
2. Polígonos simples: Menos vértices = verificações de ponto-no-polígono mais rápidas
3. Evite zonas sobrepostas: Reduz o número de avaliações necessárias

Manual de Cenários

Cenário 1: Encerrando uma Viagem com Validação de Estacionamento

Configuração:

• Modo de validação: both
• Uma zona de estacionamento cobre a rua
• Uma zona de estacionamento proibido cobre uma doca de carga dentro da zona de estacionamento

Ação: Cliente tenta encerrar viagem na doca de carga

Resultado:

1. Ponto do dispositivo: dentro da zona de estacionamento, dentro da zona de estacionamento proibido
2. Ponto do veículo: dentro da zona de estacionamento, dentro da zona de estacionamento proibido
3. Validação: inParking=true, inNoParking=true
4. Resultado: valid = true && !true = false
5. API retorna erro not_in_parking_zone
6. Cliente deve realocar o veículo

Cenário 2: Transição de Zona de Velocidade

Configuração:

• Zona A: speed_limit = 12 km/h
• Zona B: speed_limit = 8 km/h
• slow_speed_zone_limit_kph da subconta = 10 km/h

Ação: Veículo move de fora das zonas -> Zona A -> sobreposição Zona A+B -> Zona B -> fora

Resultado:

1. Fora -> Zona A: Comando de velocidade enviado com limite = min(12, 10) = 10 km/h
2. Zona A -> A+B: Comando de velocidade enviado com limite = min(8, 10) = 8 km/h
3. A+B -> Zona B: Sem alteração (ainda 8 km/h, deduplicado)
4. Zona B -> Fora: Velocidade restaurada para máximo do modelo do veículo (ex.: 25 km/h)

Cenário 3: Zonas de Velocidade e Proibidas Sobrepostas

Configuração:

• Zona de velocidade cobrindo um parque (10 km/h)
• Zona proibida cobrindo um canteiro de obras dentro do parque

Ação: Veículo entra no canteiro de obras

Resultado:

1. Limite de velocidade aplicado: 10 km/h (da zona de velocidade)
2. Motor desativado (da zona proibida)
3. Ambos os eventos registrados
4. Cliente recebe notificação de zona proibida
5. Veículo deve sair da zona proibida E aguardar 15 segundos antes que o motor seja restaurado
6. Limite de velocidade permanece em 10 km/h até que o veículo também saia da zona de velocidade

Cenário 4: Deriva do GPS no Limite da Zona

Configuração:

• Limite de zona proibida
• Veículo está fisicamente na borda
• Leituras GPS flutuam dentro/fora

Ação: Leituras GPS alternam: dentro -> fora -> dentro -> fora (rapidamente)

Resultado:

1. Primeira leitura "dentro": Motor desativado, timer inicia
2. Primeira leitura "fora": Verificação de histerese - timer não expirou, motor permanece desativado
3. Segunda leitura "dentro": Ainda na zona, motor permanece desativado
4. Segunda leitura "fora": Verificação de histerese - se >15s fora, motor restaurado

A histerese de 15 segundos evita que o motor oscile rapidamente liga/desliga devido a ruído do GPS.

Área de Serviço e Alertas Fora da Zona

Zonas de Área de Serviço definem o limite operacional da sua frota e acionam alertas quando veículos saem desta área.

Configurando Alertas Fora da Zona

Ative o recurso:

1. Vá para Painel -> Configurações
2. Navegue até a seção Outros
3. Ative Alerta Fora da Zona

Configure destinatários de e-mail:

1. Vá para Configurações -> Alertas
2. Ative Alertas Fora da Zona em Alertas Operacionais
3. Defina o endereço de E-mail de Alertas Críticos

Condições de Acionamento de Alerta

Um alerta fora da zona é enviado quando:

1. Um veículo tem uma viagem ativa
2. A localização GPS do veículo está fora de todas as zonas service_area da subconta
3. A configuração out_of_zone_alert_enabled está verdadeira
4. A notificação por e-mail out_of_zone_alerts está ativada

Conteúdo do Alerta

O e-mail inclui:

• Número do veículo
• Última localização conhecida
• Hora da detecção
• Link para visualizar a viagem no painel

Configuração de Zona de Buffer

A configuração de zona de buffer adiciona uma margem de precisão do GPS em torno dos limites da zona.

Propósito

Sinais GPS podem variar de 5-15 metros dependendo do ambiente. A configuração de zona de buffer ajuda a considerar essa variação:

• Adicionando margem em torno dos limites da zona
• Reduzindo falsos positivos nas bordas da zona
• Melhorando a confiabilidade da aplicação

Configuração

Defina a zona de buffer em Configurações -> Outros:

• Padrão: 10 metros
• Faixa recomendada: 5-15 metros

Exibição de Zonas no Aplicativo Móvel

As zonas são exibidas no mapa do aplicativo móvel do cliente com cores e comportamentos específicos.

Visibilidade da Zona

Comportamento do Aplicativo Móvel

Carregamento de Zonas:

• Zonas são buscadas do endpoint da API móvel
• Cacheadas por 5 minutos para reduzir chamadas de API
• Atualizadas quando o app vem para o primeiro plano

Renderização de Zonas:

• Exibidas como sobreposições de polígonos coloridos no mapa
• Cor da borda (stroke) é mais saturada que o preenchimento
• Largura da borda: 2 pixels

Tratamento de Coordenadas Inválidas:

• O aplicativo móvel valida as coordenadas da zona antes de renderizar
• Verifica arrays válidos com pelo menos 3 coordenadas
• Valida que cada ponto é um número e finito
• Silenciosamente pula zonas com geometria inválida

Análises e Relatórios de Zonas

O Levy Fleets fornece análises abrangentes para interações de zona.

Estatísticas de Zona

As estatísticas de zona fornecem dados agregados:

Análises do Painel

Análises de zona são visíveis em vários locais do painel:

1. Página de Detalhes da Viagem -> Aba Zonas

   • Lista cronológica de eventos de zona
   • Horários de entrada/saída
   • Ações de aplicação tomadas
   • Duração em cada zona

2. Página de Gerenciamento de Zonas

   • Contagens de uso de zona (quando expandido)
   • Timestamp da última atividade

Exportando Dados de Zona

Dados de eventos de zona podem ser exportados via:

• Consultas diretas ao banco de dados para análise avançada
• Exportações CSV de viagens (incluem eventos de zona quando disponíveis)
• API de Parceiros para integração com ferramentas de BI externas

O Que Vem a Seguir?

• Criando e Gerenciando Zonas - Como criar e configurar zonas
• Zonas de Limite de Velocidade - Mergulho profundo na aplicação de limites de velocidade
• Visão Geral do Painel - Guia completo do painel