Eventos de Segurança e Integração

Pilar: 04 — Banco de Dados e Eventos / Eventos
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/models.py, app/api/mobile/activities.py), gatein-app (src/screens/Security)

---

1. Visão Geral da Arquitetura de Segurança

O módulo de Eventos de Segurança e Integração é responsável por garantir a conformidade dos motoristas de frete antes da entrada nas instalações físicas dos Terminais. Ele engloba a validação de integração de segurança prévia (vídeo/formulário de segurança obrigatório) e o monitoramento/alerta em tempo real de situações de emergência (botão SOS e desvio de cerca virtual).

sequenceDiagram
    autonumber
    actor M as Motorista (Mobile App)
    participant S as Gatein Server (FastAPI)
    participant DB as PostgreSQL (safety_integrations)
    participant FCM as Firebase Messaging (Channel: security)
    actor T as Operador do Terminal / Web App

    M->>S: POST /mobile/checkin/{terminal_id}
    S->>DB: Consulta safety_integrations por tax_id + company_id
    alt Sem Integração de Segurança Válida (is_safety_integration_pending == True)
        S-->>M: Rejeita Check-in (HTTP 403 / SAFETY_INTEGRATION_REQUIRED)
        M->>M: Exibe tela com link do vídeo/form de treinamento de segurança
        M->>S: POST /mobile/security/complete-training
        S->>DB: Salva registro em safety_integrations (expires_at = +1 ano)
    else Integração Válida
        S->>S: Prossegue com o Check-in normalmente
    end

    rect rgb(45, 15, 15)
        note over M, T: Disparo de Alerta de Emergência SOS
        M->>S: POST /mobile/security/sos-alert (lat, lng, reason)
        S->>DB: Registra alerta de segurança com prioridade crítica
        S->>FCM: Push de emergência (Priority: MAX, Sound: alarm_siren)
        S->>T: Notifica painel web em tempo real (Alerta no pátio)
    end

---

2. Modelagem da Tabela safety_integrations

A conformidade de treinamento do motorista é gravada na tabela safety_integrations:

Coluna	Tipo SQL	Constraints	Descrição / Regra
id	BigInteger	PRIMARY KEY, autoincrement=True	ID do registro de integração
tax_id	VARCHAR(14)	NOT NULL, INDEX	CPF do motorista integrado
company_id	BigInteger	FOREIGN KEY (companies.id, CASCADE), NOT NULL, INDEX	Terminal onde a integração é válida
watched_at	TIMESTAMPTZ	NULLABLE	Timestamp de conclusão do treinamento de segurança
expires_at	TIMESTAMPTZ	NULLABLE	Data de expiração da integração (ex: validade de 1 ano)
created_at	TIMESTAMPTZ	NOT NULL, Default now()	Timestamp de inclusão

Unique Constraint:

• unique_safety_integration_per_company: UniqueConstraint('tax_id', 'company_id') impedindo duplicação de registros de integração para a mesma combinação de motorista e terminal.

---

3. Eventos de Domínio de Segurança

3.1 Evento security.integration_required (Bloqueio de Check-in)

• Trigger: Invocação da rota GET /mobile/activities ou tentativa de check-in.
• Condição: Terminal possui safety_integration_active = True na coluna config E o motorista não possui registro em safety_integrations onde expires_at > now().
• Efeito: O campo computado is_safety_integration_pending retorna True, desabilitando a execução de check-in até a conclusão da integração.

3.2 Evento security.sos_alert (Alerta Crítico de Emergência)

• Trigger: Motorista aciona o botão de emergência SOS no aplicativo mobile.
• Ação: Registra o alerta com latitude e longitude exatas.
• Notificação: Dispara Push FCM com prioridade MAXIMISADA (Priority: HIGH, canal Notifee security com som de sirene de alarme e padrão de vibração crítico [300ms, 500ms, 300ms, 500ms]).

---

4. Regras de Negócio Explícitas (RN-SEG-EVT-XXX)

RN-SEG-EVT-001: Validade Dinâmica de Integrações de Segurança

A validade de uma integração é verificada dinamicamente pelo servidor comparando expires_at > now(). Registros expirados são automaticamente considerados inválidos, forçando o motorista a refazer o vídeo de segurança ao agendar novo atendimento naquele terminal.

RN-SEG-EVT-002: Impossibilidade de Inibição de Alertas SOS

Notificações e alertas gerados pelo evento security.sos_alert ignoram completamente as preferências de notificação configuradas pelo motorista (notification_preferences), garantindo o recebimento mesmo com o modo "Não Perturbe" ou regras de opt-out ativas.