# Guia das notificações no navegador (Web Push) — passo a passo fácil

**O que é, em uma frase:** faz o Nexus mandar **notificações** para o navegador do
morador/portaria (celular ou computador), de graça, sem app de loja.

**Fique tranquilo:** vem **desligado**; enquanto você não ligar, ninguém recebe pedido
de permissão e nada muda.

**Você vai precisar de:** o computador **servidor**, uns **10 minutos**, e o site
rodando em **HTTPS** (endereço `https://…`) — isso é obrigatório para notificações.

---

## Passo 1 — gerar as "chaves" (uma vez)

As notificações usam um par de chaves de segurança (VAPID). O Nexus gera pra você:

1. Abra o **Prompt de Comando** (Menu Iniciar → digite `cmd` → Enter).
2. Cole e aperte Enter (ajuste o caminho se o seu projeto não estiver em `C:\wamp64\www`):

```
C:\wamp64\bin\php\php8.3.28\php.exe C:\wamp64\www\api\scripts\push_generate_keys.php
```

3. Vão aparecer **4 linhas** prontas (PUSH_ENABLED, VAPID_PUBLIC_KEY,
   VAPID_PRIVATE_KEY, VAPID_SUBJECT).

✅ **Deu certo se:** apareceram as 4 linhas, precedidas de
`[ OK ] autoteste: a chave privada volta a ser lida...`. **Copie todas** (você vai
colar no Passo 2).

> Guarde a chave privada com cuidado — é o que autentica seus envios.

### Deu "Falha ao gerar a chave EC"?

Isso é **típico do Windows** e **não** quer dizer que falte o OpenSSL. O PHP no
Windows só consegue *gerar* chaves se achar o arquivo `openssl.cnf` — e ele não
vem configurado por padrão. (Para *ler* uma chave ele não precisa disso; por isso
o resto do sistema funciona normalmente.)

O script agora se vira sozinho: ele procura o `openssl.cnf` do WAMP e, se ainda
assim não conseguir, gera a chave chamando o `openssl.exe` que o próprio WAMP traz.

Se mesmo assim falhar, ele mostra o erro cru do OpenSSL e o caminho de tudo que
tentou — **me mande essa saída**. Como último recurso manual (ajuste a versão do
Apache para a sua):

```
C:\wamp64\bin\apache\apache2.4.62\bin\openssl.exe ecparam -genkey -name prime256v1 -out vapid.pem
```

---

## Passo 2 — colar as chaves no Nexus (.env)

1. Abra o **Bloco de Notas como administrador** (Menu Iniciar → digite "bloco de
   notas" → botão direito → **Executar como administrador**).
2. **Arquivo → Abrir**, em "Tipo" escolha **Todos os arquivos**, e abra:

```
C:\wamp64\www\api\.env
```

3. Vá ao **final** e **cole as 4 linhas** do Passo 1. Troque o e-mail da última por
   um seu:

```
PUSH_ENABLED=true
VAPID_PUBLIC_KEY=...(a que apareceu)...
VAPID_PRIVATE_KEY=...(a que apareceu)...
VAPID_SUBJECT=mailto:voce@seudominio.com
```

4. **Arquivo → Salvar**.

✅ **Deu certo se:** salvou sem erro. (Se deu "acesso negado", o Bloco de Notas não
foi aberto como administrador — feche e abra de novo do jeito certo.)

---

## Passo 3 — ativar no navegador (cada pessoa faz uma vez)

1. A pessoa entra no Nexus (logada), no **HTTPS**.
2. Vai aparecer um botão **"Ativar notificações"** no canto da tela. Clique.
3. O navegador pergunta se permite notificações → clique **Permitir**.

✅ **Deu certo se:** o botão some (ficou ativado). Daí em diante, aquele
celular/computador recebe as notificações do sistema.

> No **iPhone/iPad**: primeiro **adicione o site à Tela de Início** (botão compartilhar
> → "Adicionar à Tela de Início") e abra por esse ícone; só assim o iOS permite push.

---

## Passo 4 — testar

Com alguém já "ativado", dispare um alerta de teste (ou espere um alerta real
acontecer). Se preferir testar na hora, um administrador pode chamar o endpoint
`POST /push/test` (envia "Notificações ativadas neste dispositivo." para quem está
logado).

✅ **Deu certo se:** a notificação apareceu na tela/celular.

---

## Deu algum problema?

- **O botão "Ativar notificações" não aparece:** o site precisa estar em **HTTPS** e as
  **chaves** têm que estar no `.env` (Passos 1–2). Recarregue a página.
- **Ativei mas não chega nada:** confira o `VAPID_SUBJECT` (tem que ser um `mailto:` ou
  `https:` válido) e se as chaves foram coladas certas.
- **Quero desativar:** a pessoa pode revogar a permissão no próprio navegador (cadeado
  ao lado do endereço → Notificações → Bloquear).

---

## Detalhes (para curiosos / técnico)

- É um **canal do AlertService** (ao lado de Pushover/e-mail/WhatsApp) e um **PWA
  instalável**. A criptografia é self-contained (RFC 8291/8292, só `openssl`), validada
  contra o vetor oficial do RFC 8291.
- Peças: `public/sw.js` (service worker), `public/manifest.webmanifest`,
  `public/assets/js/push.js`, `App\Services\WebPushService`, tabela `push_subscription`.
- Endpoints (exigem login): `GET /push/key`, `POST /push/subscribe`,
  `/push/unsubscribe`, `/push/test`.
- Usar por regra: `dispatch(['webpush'], titulo, msg, prio, ['webpush'=>['pessoa'=>123]])`
  envia só às assinaturas daquela pessoa (senão, todas). (Expor `webpush` como
  caixinha no form de `/alerts` é um próximo passo pequeno.)
- **LGPD:** não coloque conteúdo sensível no corpo da notificação (ex.: "Nova
  ocorrência no seu apê", sem detalhes). Ativação é opt-in; remoção é imediata.