API Reference: Push Notifications

Sistema de notificacoes push via Web Push API com chaves VAPID (sem Firebase). O service worker sw.js recebe e exibe as notificacoes.

Variaveis de Ambiente

Variavel	Descricao
`VAPID_PUBLIC_KEY`	Chave publica VAPID (compartilhada com frontend)
`VAPID_PRIVATE_KEY`	Chave privada VAPID (somente backend)
`VAPID_EMAIL`	Email de contato para o protocolo VAPID

PushService

Servico NestJS para gerenciar subscricoes e envio de push notifications.

Metodo	Descricao
`subscribe(usuarioId, subscription)`	Salva a subscription do browser na tabela `push_subscriptions`
`unsubscribe(usuarioId, endpoint)`	Remove a subscription do usuario
`sendPush(usuarioId, payload)`	Envia push para todas as subscriptions de um usuario
`sendPushToAll(nucleoId, payload)`	Envia push para todos os membros ativos do nucleo
`getVapidPublicKey()`	Retorna a chave publica VAPID para o frontend

Endpoints

POST /push/subscribe

Registra uma subscription de push para o usuario logado.

Body

{
  "endpoint": "https://fcm.googleapis.com/fcm/send/...",
  "keys": {
    "p256dh": "base64-encoded-key",
    "auth": "base64-encoded-auth"
  }
}

Response 201

{ "message": "Subscription registrada com sucesso" }

POST /push/unsubscribe

Remove a subscription de push do usuario logado.

Body

{ "endpoint": "https://fcm.googleapis.com/fcm/send/..." }

Response 200

{ "message": "Subscription removida" }

GET /push/vapid-key

Retorna a chave publica VAPID para o frontend usar no PushManager.subscribe().

Response 200

{ "publicKey": "BEl62i..." }

POST /push/test

Envia uma notificacao push de teste para o usuario logado.

Permissao: Qualquer usuario autenticado

Response 200

{ "message": "Push de teste enviado" }

Tabela: push_subscriptions

Coluna	Tipo	Descricao
`id`	uuid	PK
`usuario_id`	uuid	FK para usuarios
`endpoint`	text	URL do endpoint push do browser
`p256dh`	text	Chave publica do cliente (base64)
`auth`	text	Token de autenticacao do cliente (base64)
`nucleo_id`	uuid	FK para nucleos (multi-tenant)
`criado_em`	timestamptz	Data de registro

Service Worker (sw.js)

O service worker trata dois eventos relacionados a push:

push — recebe o payload e exibe a notificacao com self.registration.showNotification()
notificationclick — ao clicar na notificacao, abre ou foca a janela do app na URL do payload

// Exemplo de payload enviado pelo backend
{
  "title": "Novo comunicado",
  "body": "Confira o comunicado sobre a acao de sabado",
  "url": "/dashboard/comunicados/uuid"
}

PushPermission Component

Componente React exibido no dashboard para solicitar permissao de push ao usuario. Fluxo de duas etapas: banner amigavel → prompt nativo do browser.

Comportamento

Aparece automaticamente 3 segundos apos o carregamento da pagina
Exibe banner com botao "Ativar" (etapa 1: banner amigavel)
Ao clicar, dispara o prompt nativo do browser (Notification.requestPermission()) (etapa 2: prompt nativo)
Se o usuario aceitar, chama POST /push/subscribe com a subscription gerada pelo PushManager
Se o usuario recusar ou fechar, o banner e ocultado
Nao aparece se o usuario ja tem permissao concedida
Nao aparece se o browser nao suporta Push API

Push Seletivo em Comunicados

O sistema de push seletivo nos comunicados permite controlar quem recebe a notificacao:

Todos: Envia para todos os membros ativos do nucleo (padrao)
Por cargo: Envia apenas para membros com cargos selecionados
Membros especificos: Envia apenas para membros selecionados por ID

Ver API Comunicados para detalhes do campo pushDestinatarios.

Push Opcional (Checkbox)

Ao criar comunicados e enquetes, o formulario exibe um checkbox "Enviar push" (ativado por padrao). Quando desmarcado, o backend nao chama PushService — apenas cria notificacoes in-app.

VAPID Keys

O sistema utiliza chaves VAPID para autenticacao com o servico de push do browser:

VAPID_PUBLIC_KEY e usada no frontend para criar a subscription via PushManager.subscribe()
VAPID_PRIVATE_KEY e usada no backend para assinar os payloads enviados via Web Push
As chaves sao geradas uma vez e configuradas via variaveis de ambiente
O endpoint GET /push/vapid-key fornece a chave publica ao frontend

Preferencias do Usuario

O envio de push respeita as preferencias individuais armazenadas em preferencias_notificacao (JSONB):

push_tarefa — notificacoes de tarefas
push_evento — notificacoes de eventos
push_comunicado — notificacoes de comunicados
push_enquete — notificacoes de enquetes
push_pagamento — notificacoes de pagamentos
push_conquista — notificacoes de conquistas

Todas as preferencias sao true por padrao. O usuario pode desativa-las nas configuracoes do perfil.