Pular para o conteúdo principal

Preferências de Notificação do Usuário

Pilar: 03 — Notificações
Status: 🟡 Parcial
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/models.py, app/api/mobile/notifications.py), gatein-app (src/screens/Profile/NotificationSettings)

1. Visão Geral do Controle de Preferências​

O aplicativo mobile disponibiliza uma tela de Configurações de Notificação no perfil do motorista. Essa interface permite personalizar quais categorias de mensagens informativas o motorista deseja receber, mantendo contudo as notificações críticas e operacionais obrigatoriamente ativas por motivos de segurança e cumprimento contratual.

2. Categorias e Níveis de Opt-Out​

Categoria de NotificaçãoPermite Opt-Out (Desativar)?Padrão InicialJustificativa de Segurança
Aprovação / Rejeição de Check-in❌ Não (Obrigatório)EnabledNecessário para liberação física de gates e docas no pátio
Alertas de Segurança / SOS❌ Não (Obrigatório)EnabledExigência de conformidade e emergência em transporte de carga
Lembretes de Véspera (1 dia / 12h)✅ Sim (Opcional)EnabledInformativo de conveniência do motorista
Notificação de Janela Aberta✅ Sim (Opcional)EnabledInformativo de status operacional
Atribuição de Novas Viagens✅ Sim (Opcional)EnabledNotificação comercial/logística
Comunicados e Anúncios✅ Sim (Opcional)EnabledMarketing/Informativo corporativo do terminal

3. Modelo de Dados e Endpoint de Preferências​

3.1 Armazenamento no Banco (drivers.notification_preferences)​

As preferências são salvas em uma coluna tipo JSONB na tabela drivers:

{
  "reminders_1day": true,
  "reminders_12h": true,
  "window_open": true,
  "trip_assigned": true,
  "announcements": false
}

3.2 Endpoint de Leitura e Atualização​

GET /mobile/profile/notification-preferences​

Retorna a configuração atual do motorista autenticado.

PATCH /mobile/profile/notification-preferences​

Atualiza os seletores de preferências.

Request Payload:​

{
  "reminders_1day": true,
  "reminders_12h": false,
  "window_open": true,
  "trip_assigned": true,
  "announcements": false
}

4. Lógica de Checagem no Servidor (Checagem Pré-Envio)​

Antes de invocar o envio do FCM no módulo app/core/firebase.py, a função notify_user_by_tax_id avalia as preferências gravadas:

def should_send_notification(driver: Driver, push_type: str) -> bool:
    # 1. Categorias Críticas que NUNCA podem ser bloqueadas
    CRITICAL_TYPES = {"CHECKIN_APPROVED", "CHECKIN_REJECTED", "SECURITY_ALERT"}
    if push_type in CRITICAL_TYPES:
        return True

    # 2. Leitura do JSONB de preferências
    prefs = driver.notification_preferences or {}
    
    # 3. Mapeamento de push_type para a chave de preferência
    key_map = {
        "REMINDER_1DAY": "reminders_1day",
        "COUNTDOWN": "reminders_12h",
        "WINDOW_OPEN": "window_open",
        "TRIP_ASSIGNED": "trip_assigned",
        "ANNOUNCEMENT_PUBLISHED": "announcements"
    }

    pref_key = key_map.get(push_type)
    if not pref_key:
        return True # Por padrão, permite se não houver chave definida

    # 4. Retorna o valor configurado (padrão True se ausente no JSON)
    return prefs.get(pref_key, True)

5. Regras de Negócio (RN-PREF-XXX)​

RN-PREF-001: Imutabilidade das Categorias de Segurança e Check-in​

Tentativas de enviar um payload no endpoint PATCH /mobile/profile/notification-preferences alterando os valores de categorias críticas (CHECKIN_APPROVED, SECURITY_ALERT) serão ignoradas ou rejeitadas com HTTP 400 (CRITICAL_PREFERENCES_IMMUTABLE).

RN-PREF-002: Opt-In Automático para Novos Cadastros​

Todo motorista recém-cadastrado no sistema inicia com todas as categorias opcionais ativadas por padrão (true), garantindo a recepção imediata dos alertas logísticos.