Pular para o conteúdo principal

Integração de Segurança e Rastreamento (App Mobile)

Pilar: 02 — Funcionalidades Core / App Mobile
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/api/mobile/activities.py, app/models.py), gatein-app (src/screens/SafetyIntegration, src/screens/Security)

1. Visão Geral e Arquitetura do Módulo​

O módulo de Integração de Segurança e Rastreamento assegura a conformidade de motoristas com os treinamentos, regras de pátio e protocolos de segurança exigidos por cada Terminal ou Transportadora. Além disso, provê mecanismos de rastreamento de localização durante viagens ativas, alertas de pânico/emergência e monitoramento de saída inesperada de cercas virtuais (geofences).

1.1 Diagrama de Sequência e Liberação de Pendência​

sequenceDiagram
    autonumber
    actor M as Motorista / App Mobile
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL
    participant SEC as Sistema Externo de Segurança / WebView

    M->>S: GET /mobile/activities
    S->>DB: Consulta SafetyIntegrations (company_id, user_tax_id)
    alt Sem integração válida ou expirada (expires_at < now())
        S-->>M: Retorna is_safety_integration_pending = True
        M->>M: Exibe aviso de pendência no card + Bloqueia Check-in
        M->>SEC: Abre Tela SafetyIntegration (Vídeo / Quiz de Segurança)
        SEC->>S: POST /mobile/safety/complete (Token de Conclusão)
        S->>DB: Insere/Atualiza registro em safety_integrations (Validade: 30 dias)
        S-->>M: Liberação efetuada! is_safety_integration_pending = False
    else Integração Válida
        S-->>M: Retorna is_safety_integration_pending = False (Check-in Liberado)
    end

2. Estruturas de Dados e Schemas Explícitos​

2.1 Modelo Relacional no Banco de Dados (safety_integrations)​

ColunaTipo SQLConstraintsDescrição / Regra
idUUIDPRIMARY KEY, Default gen_random_uuid()Identificador único interno
company_idUUIDFOREIGN KEY (companies.id), NOT NULLEmpresa detentora da exigência de segurança
user_tax_idVARCHAR(14)NOT NULL, INDEXCPF do motorista validado
statusVARCHAR(32)NOT NULL, Default 'COMPLETED'Estado da integração (COMPLETED, EXPIRED, REVOKED)
completed_atTIMESTAMPTZNOT NULL, Default now()Timestamp em que o motorista concluiu a integração
expires_atTIMESTAMPTZNOT NULLTimestamp em que o certificado/integração expira
certificate_urlVARCHAR(512)NULLABLEURL do comprovante em PDF gerado (opcional)

2.2 Schemas de Resposta da API Mobile (SafetyIntegrationResponseSchema)​

{
  "success": true,
  "data": {
    "company_id": "p4k2n8m9",
    "company_name": "Terminal Marítimo de Santos",
    "is_pending": false,
    "completed_at": "2026-07-15T14:30:00Z",
    "expires_at": "2026-08-14T14:30:00Z",
    "days_remaining": 11,
    "integration_url": "https://seguranca.terminal.com.br/treinamento?cpf=12345678901"
  }
}

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

RN-SEC-001: Trava de Check-in por Pendência de Segurança​

user_tax_id == CPF_Motorista AND company_id == ID_Empresa AND expires_at > now()

Enquanto is_safety_integration_pending == True, o botão de check-in permanece desabilitado no app mobile e o servidor rejeitará qualquer submissão REST com HTTP 403 (SAFETY_INTEGRATION_REQUIRED).

RN-SEC-002: Renovação e Período de Validade​

A validade padrão de uma integração de segurança é configurável por empresa (padrão: 30 dias corridos a partir da data de conclusão completed_at). Quando faltarem 5 dias para a expiração, o app exibirá um alerta preventivo convidando o motorista a renovar a integração antes da chegada ao pátio.

RN-SEC-003: Rastreamento de Localização Exclusivo em Viagens Ativas​

O envio de coordenadas GPS em segundo plano (telemetria de rastreamento) só é ativado se o motorista possuir uma viagem (Trip) ou agendamento (Appointment) com o status IN_PROGRESS ou ON_GOING.

  • Assim que a operação transiciona para COMPLETED ou CANCELLED, o serviço de localização em segundo plano do React Native (BackgroundGeolocation) é imediatamente suspenso.

RN-SEC-004: Alerta Manual de Emergência / Pânico​

Dentro do módulo de Segurança, o motorista possui um botão de "Alerta de Emergência". Ao ser acionado:

  1. O app captura instantaneamente a posição GPS exata, nível de bateria e velocidade do veículo.
  2. Dispara POST /mobile/security/panic-alert.
  3. O servidor notifica o painel Web do Terminal em tempo real via WebSocket e envia e-mail/SMS para a equipe de segurança da empresa.

RN-SEC-005: Política de Retenção e Privacidade de Dados de Localização​

Em conformidade com a LGPD e regras de privacidade, dados de telemetria e localização de viagens finalizadas possuem um período máximo de retenção de 90 dias no PostgreSQL, sendo expurgados por rotinas automáticas do APScheduler.

4. Detalhamento de Endpoints​

4.1 GET /mobile/safety-integration/{company_id}​

Consulta o status da integração de segurança do motorista autenticado para determinada empresa.

4.2 POST /mobile/safety-integration/complete​

Registra a conclusão de um treinamento de segurança e emite a validade.

4.3 POST /mobile/security/panic-alert​

Dispara um sinal auditável de emergência com coordenadas GPS para a equipe de pátio do terminal.

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

Código HTTPCódigo InternoCausa RaizAção no App Mobile
403 ForbiddenSAFETY_INTEGRATION_REQUIREDTentativa de check-in com integração pendenteRedirecionar para tela de treinamento
400 Bad RequestEXPIRED_INTEGRATION_TOKENToken de conclusão de treinamento inválidoSolicitar refazer o treinamento
404 Not FoundCOMPANY_SAFETY_NOT_CONFIGUREDEmpresa não possui integração de segurança configuradaLiberar fluxo padrão sem restrição