# Guia rapido - Comunicados e push para clientes

## 1. Ajustes obrigatorios de banco

1. Execute as migrations mais recentes que criam a coluna `audience` na tabela `internal_wall_posts`. Voce pode aplicar o `20260320_alter_internal_wall_posts_add_audience.php` (ou o SQL `20260322_add_audience_column_to_internal_wall_posts.sql` caso prefira rodar direto no MySQL).  
2. Em instalacoes novas, basta rodar `20260301_create_internal_wall_tables.sql` novamente (ja embute a coluna) antes de aplicar os alters.  
3. Garanta tambem que o seed `20260320_seed_client_push_tag.php` rode para criar a tag de push `clients`, usada como alvo dos avisos para portal/cliente.

> Sem essa coluna o filtro `p.audience` explode com `SQLSTATE[42S22]`, impedindo que a rota `/comunicados` carregue.

## 2. Enviando comunicados no mural

1. Entre em **Comunicacoes > Mural interno** autenticado com um perfil Admin/Corretor (unicos com permissao de gerenciamento).  
2. Clique em **Novo comunicado**.  
3. Preencha titulo, categoria, resumo e conteudo normalmente, defina *Status = Publicado* para torna-lo visivel.  
4. Use o seletor **Publico**:
   - `Somente equipe interna` -> visibilidade so para usuarios logados.  
   - `Clientes (portal)` -> fica disponivel no Portal do Cliente e dispara push.  
   - `Equipe e clientes` -> mostra nos dois lugares e tambem envia push.  
5. Opcionalmente configure agenda (Disponivel a partir / Expira em) e anexe arquivos.  
6. Salve. O mural ja lista o comunicado respeitando as datas e o pin.

## 3. Push automatico para clientes

- Quando um comunicado publicado tiver `Publico = Clientes` ou `Equipe e clientes`, o `InternalWallController` chama `notifyClientAudience()`, que:
  1. Cria um registro em `push_notifications` com titulo/resumo do comunicado.  
  2. Vincula automaticamente a tag `clients`.  
  3. Consulta as assinaturas Web Push (`push_subscriptions`) desse grupo e dispara a notificacao via `PushNotificationService`.
- Nao existe acao manual adicional: basta publicar o comunicado direcionado ao publico correto que o push sai e tambem fica visivel no portal do cliente.

Assim, o mesmo fluxo "Criar comunicado" resolve tanto avisos internos quanto mensagens para clientes, inclusive com envio de push integrado. Verifique apenas se o navegador ja aceitou notificacoes (assuntos em **Configuracoes > Portal do Cliente**).

## 4. Monitoramento de engajamento dos clientes

1. Cada comunicado direcionado ao portal passa, automaticamente, a registrar eventos no endpoint `POST /cliente/comunicados/eventos`.  
   - Ao abrir o modal no portal é gravado um evento `view`.  
   - Conforme o cliente rola o conteúdo são enviados eventos `scroll` com a profundidade lida.  
   - Botões rápidos ("Recebi", "Tenho dúvidas", "Enviar mensagem") disparam eventos `cta`/`interaction`.  
   - Quando o cliente envia uma mensagem texto anexamos o conteúdo ao evento `message`.
2. O service worker também notifica o backend via `POST /api/push/events` sempre que o push é clicado, vinculando o `notification_id` ao `lead_id`.  
3. Os eventos brutos alimentam as tabelas `internal_wall_post_events` e os agregados `internal_wall_engagement_summaries`, permitindo classificar cada lead em níveis (`no_notifications`, `silent`, `viewer`, `reader`, `engaged`, `advocate`) e calcular o `engagement_score`.
4. No painel **Comunicações > Mural interno** há um cartão “Engajamento dos clientes” com:  
   - Totais por cada nível (quem recebe e não clica, lê tudo, envia mensagens etc.).  
   - Ranking dos clientes com colunas de entregas, cliques, leituras e dias desde a última interação.  
   - Timeline dos feedbacks mais recentes enviados pelo portal.

> Caso nada apareça nos cards, verifique se as migrations `20260325_create_internal_wall_engagement_tables.sql` foram aplicadas e se o portal está servindo o `sw.js` atualizado.