pipeline-de-notificacoes-em-tempo-real
Sistema de notificações push em tempo real via WebSockets para colaboração, menções (@usuario), alertas de mudanças em textos compartilhados e eventos do sistema. Ativar ao implementar colaboração em
SKILL.md.agents/skills/pipeline-de-notificacoes-em-tempo-real/SKILL.md
GitHubpipeline-de-notificacoes-em-tempo-real
Descrição
A skill pipeline-de-notificacoes-em-tempo-real especifica a arquitetura de entrega de notificações push para usuários da plataforma via WebSocket (Socket.io) para eventos que exigem reação imediata (colaborador editando o mesmo documento, @menção em comentário) e via Server-Sent Events (SSE) para notificações menos urgentes (exportação pronta, lembrete de meta de escrita).
Quando usar
Gatilhos concretos e observáveis:
- Implementação da colaboração em tempo real (UC-132, UC-133, UC-204).
- Implementação do sistema de notificações de usuário (UC-134, UC-229, UC-230).
- Implementação da entrega de resultados de jobs assíncronos (exportações, análise NLP).
Quando NÃO usar:
- Para o mecanismo de sincronização CRDT dos documentos compartilhados (ver
concorrencia-editor-texto-rico-crdt). - Para emails transacionais (usar serviço SMTP como SendGrid/SES).
Pré-requisitos
socket.io(servidor) +socket.io-client(cliente).- Redis Pub/Sub para sincronização de mensagens entre múltiplas instâncias do servidor (horizontal scaling).
- Tabela
notificationsno banco:(id, user_id, type, payload_json, read_at, created_at).
Processo (passo a passo executável)
Servidor WebSocket com Rooms por Documento:
- Ao conectar, o cliente autentica via Access Token JWT no handshake.
- O servidor verifica o token e associa o socket ao
user_id. - Ao abrir um documento, o cliente emite
join_document(doc_id)→ servidor adiciona o socket à roomdoc:${doc_id}.
Eventos de Colaboração em Tempo Real:
- Cursor de colaborador: ao mover o cursor, emitir
cursor_move { user_id, position }para a room do documento. - Ao outros clientes receber o evento, renderizar o cursor do colaborador com cor identificadora e tooltip com nome.
- Cursor de colaborador: ao mover o cursor, emitir
Notificações de Menção (@usuario):
- Ao detectar
@usernameno texto de um comentário (eventocomment_created):- Resolver
@usernameparauser_idno banco. - Emitir evento
notificationdiretamente para o socket do usuário mencionado na roomuser:${user_id}. - Persistir a notificação na tabela
notificationspara recuperação em sessões futuras.
- Resolver
- Ao detectar
Fanout via Redis Pub/Sub (Multi-instância):
- Configurar
socket.io-redisadapter para que eventos emitidos em um servidor sejam retransmitidos para todos os servidores do cluster via Redis. - Garantir que uma notificação gerada no servidor A seja entregue ao usuário conectado no servidor B.
- Configurar
Notificações Não-Urgentes via SSE:
- Para eventos como "exportação pronta" ou "análise NLP concluída": usar SSE (
text/event-stream) no endpointGET /api/notifications/stream. - Manter a conexão SSE aberta e enviar
data: { type, payload }ao completar o job.
- Para eventos como "exportação pronta" ou "análise NLP concluída": usar SSE (
Parâmetros e configuração
| Parâmetro | Descrição | Padrão |
|---|---|---|
WS_AUTH_TIMEOUT_MS |
Tempo máximo para autenticar o handshake WebSocket | 5000 |
CURSOR_THROTTLE_MS |
Frequência mínima de envio de eventos de cursor | 100 |
NOTIFICATION_RETENTION_DAYS |
Dias para manter notificações lidas no banco | 30 |
SSE_HEARTBEAT_MS |
Intervalo de heartbeat SSE para manter conexão aberta | 30000 |
Armadilhas e como evitá-las
- Armadilha: Escalar horizontalmente o servidor WebSocket sem um adapter Redis. Usuário A está conectado ao servidor 1 e usuário B ao servidor 2. A notificação gerada no servidor 1 nunca chega ao servidor 2, e o usuário B não recebe a menção.
Mitigação: Configurar o
socket.io-redisadapter desde o início, mesmo em desenvolvimento. O Redis pub/sub garante a entrega cruzada entre instâncias sem mudanças na lógica de emissão de eventos.
Critérios de validação (Definition of Done)
- Uma @menção em um comentário é entregue ao usuário mencionado em menos de 500ms via WebSocket quando ele está online.
- Notificações geradas num servidor chegam a clientes conectados em outros servidores do cluster via Redis adapter.
- Notificações não lidas são recuperadas corretamente ao abrir a plataforma após período offline.
Exemplos
@menção em comentário:
Maria comenta: "@joao Verificar esta cena" → servidor resolve @joao → emite socket.to('user:joao-uuid').emit('notification', { type: 'mention', from: 'Maria', text: '...' }) → João vê badge de notificação no ícone de sino em tempo real.
Cursor de colaborador:
Maria e João editam o mesmo documento → João move cursor para parágrafo 5 → evento cursor_move emitido → Maria vê cursor azul "João" aparecer no parágrafo 5 do seu editor.