Pular para o conteúdo principal

Configuração de Geofence e Cerca Virtual (Web App)

Pilar: 02 — Funcionalidades Core / Web App
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-web (src/screens/admin/CompanyConfig), gatein-server (app/api/web/config.py, app/models.py), gatein-app (Serviço de Geofence em segundo plano)

1. Visão Geral e Conectividade com o App Mobile​

O módulo de Configuração de Geofence (Cerca Virtual) permite que Administradores de Terminais definam o perímetro geográfico operacional do seu pátio de triagem e gates de entrada através de um editor visual de mapas no Web App.

Essa cerca virtual é sincronizada com o aplicativo mobile dos motoristas. Quando o veículo do motorista cruza o perímetro geográfico definido no Web App, o aplicativo React Native dispara automaticamente o prompt proativo de Check-in Antecipado.

1.1 Diagrama de Sequência e Validação Server-Side​

sequenceDiagram
    autonumber
    actor A as Admin do Terminal (Web App)
    participant W as Web App (Map Editor)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    actor M as Motorista (App Mobile)

    A->>W: Desenha Geofence no mapa (Tipo: Circle / Radius: 500m)
    W->>S: PUT /web/config/geofence (geofence JSON, use_remote_checkin: True)
    S->>DB: Salva em company.geofence (JSONB)
    S-->>W: HTTP 200 (Geofence atualizada)
    
    M->>S: GET /mobile/activities (ou login)
    S->>DB: Fetch geofence do Terminal
    S-->>M: Retorna objeto geofence no payload
    M->>M: Registra cerca no sistema nativo de Geofencing do celular
    
    note over M, S: Motorista aproxima-se do pátio e cruza a cerca virtual
    M->>S: POST /mobile/checkin/{terminal_id} (envia lat/lng do GPS)
    S->>S: Validação de Segurança: calcula distância Haversine ou Ray-Casting
    alt Coordenada fora do perímetro salvo
        S-->>M: HTTP 400 ("Posição GPS fora da Geofence do Terminal")
    else Coordenada Válida dentro do perímetro
        S->>S: Continua o processamento do Check-in
    end

2. Estrutura dos Dados e Schemas Explícitos​

2.1 Modelo de Dados no Banco (company.geofence JSONB)​

A configuração da cerca é gravada na coluna geofence (JSONB) da tabela companies / terminals:

Formato Círculo (circle):​

{
  "type": "circle",
  "center": {
    "lat": -23.55052,
    "lng": -46.633308
  },
  "radius": 500
}

Formato Polígono (polygon):​

{
  "type": "polygon",
  "coordinates": [
    { "lat": -23.5501, "lng": -46.6331 },
    { "lat": -23.5509, "lng": -46.6331 },
    { "lat": -23.5509, "lng": -46.6339 },
    { "lat": -23.5501, "lng": -46.6339 }
  ]
}

2.2 Schema de Requisição do Web App (GeofenceUpdateRequest)​

{
  "use_remote_checkin": true,
  "geofence": {
    "type": "circle",
    "center": { "lat": -23.55052, "lng": -46.633308 },
    "radius": 500
  },
  "address": {
    "street": "Avenida Cais do Porto",
    "number": "1000",
    "city": "Santos",
    "state": "SP",
    "lat": -23.55052,
    "lng": -46.633308
  }
}

3. Regras de Negócio Explícitas (RN-GEO-XXX)​

RN-GEO-001: Validação de Autoridade Server-Side (Client Não é Fonte de Verdade)​

Embora o aplicativo mobile detecte a entrada na cerca via GPS do dispositivo, a validação definitiva é efetuada obrigatoriamente no servidor FastAPI durante o processamento do check-in:

  • Para cercas do tipo circle: O servidor calcula a distância Haversine entre (lat, lng) do motorista e center. Se distancia > radius, a requisição é bloqueada.
  • Para cercas do tipo polygon: O servidor executa o algoritmo de Ray-Casting (Point-in-Polygon). Se o ponto estiver fora, bloqueia com HTTP 400 (OUT_OF_GEOFENCE_BOUNDS).

RN-GEO-002: Limites Mínimo e Máximo de Raio​

Para evitar falsos disparos ou cercas gigantescas desproporcionais:

  • Raio mínimo aceito para tipo circle: 50 metros.
  • Raio máximo aceito para tipo circle: 5.000 metros (5 km). Submissões fora deste intervalo retornam erro de validação de schema.

RN-GEO-003: Mínimo de 3 Pontos para Polígonos​

Geofences do tipo polygon devem conter um array coordinates com no mínimo 3 vértices válidos formando uma área fechada. Polígonos com 1 ou 2 pontos são rejeitados com HTTP 400 (INVALID_POLYGON_STRUCTURE).

RN-GEO-004: Flag de Controle Remote Check-in (use_remote_checkin)​

Se o terminal alterar a flag use_remote_checkin para False, o aplicativo mobile desabilita o disparo de check-in antecipado por geofence. O motorista só poderá realizar o check-in presencialmente no totem/gate.

4. Detalhamento de Endpoints​

4.1 GET /web/config/geofence​

Retorna a geofence configurada, endereço estruturado e status de check-in remoto do terminal.

4.2 PUT /web/config/geofence​

Atualiza a geometria da geofence, coordenadas centrais e parâmetros de check-in remoto.

5. Regras de Segurança e Tabela de Erros​

Código HTTPCódigo InternoCausa RaizAção no Web App
400 Bad RequestOUT_OF_GEOFENCE_BOUNDSCoordenada do motorista fora do perímetro salvoExibir aviso no mapa sobre o raio de cobertura
400 Bad RequestINVALID_RADIUS_LIMITSRaio menor que 50m ou maior que 5000mAjustar o slider de raio no editor de mapa
400 Bad RequestINVALID_POLYGON_STRUCTUREPolígono desenhado possui menos de 3 vérticesOrientar o usuário a fechar a figura geométrica