Skip to content

artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-notificacoes-multicanal

tpl-dominio-notificacoes-multicanal

Verified

Template do pack (dominio/08-notificacoes-multicanal.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.

DOMAIN: Sistema de Notificações (Email + Push + SMS + In-App)

Skill gerado a partir do pack templates-claude-code. Arquivo de origem: dominio/08-notificacoes-multicanal.md. Use como baseline e adapte ao projeto antes de mudancas grandes.

Conteudo do template

CONTEXT

Notificações mal implementadas destroem a experiência: duplicatas, spam de retry, sem opção de opt-out, notificação de sistema em produção às 3h por mensagem errada. O desafio técnico é a entrega confiável com at-least-once sem duplicatas percebidas, e o desafio de produto é respeitar as preferências do usuário em todos os canais.

STACK ASSUMPTIONS

  • Email: AWS SES, SendGrid, Resend ou Postmark
  • Push: Firebase Cloud Messaging (web + Android) + APNs (iOS)
  • SMS: Twilio, AWS SNS ou Vonage
  • In-App: WebSocket (Socket.io) ou SSE + banco de dados
  • Queue: BullMQ / SQS com dead letter queue
  • Templates: Handlebars / MJML para email, i18n via i18next ou similar

CORE CONCEPTS

  • Notification Event: o que aconteceu no sistema (order.confirmed, payment.failed)
  • Channel: meio de entrega (email, push, sms, in_app)
  • Template: conteúdo parametrizado por canal e idioma
  • Preference: configuração do usuário por tipo de notificação e canal
  • Delivery: tentativa de entrega de uma notificação para um canal específico
  • Digest: agrupamento de notificações similares em período (ex: "5 novos comentários")
  • Dead Letter: fila de notificações que falharam após N retentativas
  • Provider Failover: trocar de provider automaticamente se taxa de erro > threshold

ARCHITECTURE RULES

Event-Driven Pipeline

Business Event → NotificationService.dispatch(event)
                        ↓
               Resolver: quais users notificar?
                        ↓
               Check preferences per user per channel
                        ↓
               Enqueue delivery jobs per channel
                        ↓
         [EmailWorker] [PushWorker] [SMSWorker] [InAppWorker]
                        ↓
               Track delivery + update UI

Template System

  • Templates armazenados em banco de dados (editáveis sem deploy)
  • Fallback: template de banco → template de arquivo → template default hardcoded
  • Variables validadas antes de render (não permitir undefined em template)
  • Email: MJML para componentes, compilar para HTML na geração (não no envio)
  • i18n: template por locale, fallback para en se locale não existe
  • Preview em admin: render template com variáveis de exemplo

Delivery Tracking

Delivery states: queued → sending → sent → delivered | failed | bounced | unsubscribed
  • Tracking por webhook do provider (bounce, open, click, unsubscribe)
  • Hard bounce: marcar email como inválido, não enviar novamente
  • Soft bounce (3x): marcar como temporariamente inválido, tentar depois
  • Unsubscribe via webhook do provider: honrar imediatamente

Retry Strategy

  • Attempt 1: imediato
  • Attempt 2: 1 min
  • Attempt 3: 5 min
  • Attempt 4: 30 min
  • Attempt 5: 2h
  • Após 5 falhas → Dead Letter Queue + alert para ops
  • Idempotency: verificar se já foi enviado antes de entregar (evitar duplicatas em retry)

User Preferences

  • Granularidade: por tipo de evento (order.confirmed) e por canal (email, push)
  • Opt-out global: desabilitar todas as notificações (exceto transacionais obrigatórias)
  • Opt-out por tipo: desabilitar tipo específico em todos os canais
  • Horário silencioso: não enviar push/SMS entre 22h-8h (respeitar timezone do usuário)
  • Frequency cap: máximo N notificações por canal por dia

ROUTING TABLE

TriggerAction
Business event emitteddispatch() → resolver recipients → check prefs → enqueue per channel
Queue job: send_emailRender template → send via provider → track delivery
Queue job: send_pushBuild FCM/APNs payload → send → handle token invalidation
Queue job: send_smsBuild message → send via Twilio → track delivery
Queue job: send_in_appPersist to DB → emit via WebSocket if connected
Provider webhook: bounceMarcar email como hard/soft bounce → suspender se hard
Provider webhook: unsubscribeAtualizar preferências → honrar imediatamente
POST /notifications/preferencesAtualizar preferências do usuário
GET /notificationsListar notificações in-app (com paginação cursor-based)
PATCH /notifications/:id/readMarcar como lida
PATCH /notifications/read-allMarcar todas como lidas
GET /notifications/unread-countCount para badge (cacheável por 30s)
POST /admin/notifications/testEnviar notificação de teste para email/phone específico
GET /admin/notifications/:id/statusStatus atual de entrega com histórico de tentativas

CRITICAL RULES

  1. Opt-out global sempre respeitado — nunca enviar para usuário que optou por sair
  2. Notificações transacionais (reset de senha, confirmação de compra) ignoram opt-out de marketing
  3. Hard bounce: nunca mais enviar email para aquele endereço sem ação manual do usuário
  4. Idempotency key por delivery — não enviar duplicatas em retry
  5. Timezone do usuário para cálculo de horário silencioso
  6. FCM token inválido: remover da base de dados imediatamente (token rotacionado pelo device)
  7. Dead letter: alertar ops com conteúdo da mensagem e erro específico
  8. Templates com variáveis undefined devem falhar com erro claro (não enviar template quebrado)
  9. Frequência cap: contar notificações por tipo por usuário por dia antes de entregar
  10. Provider failover: testar fallback em staging regularmente

COMMON PITFALLS

❌ Retry sem idempotency — usuário recebe email duplicado

// ERRADO: cada falha + retry envia novo email
async function sendEmailJob(data) {
  await emailProvider.send(data); // sem verificar se já enviou
}

// CORRETO: verificar antes de enviar
async function sendEmailJob(data) {
  const delivery = await db.deliveries.findOne({ id: data.deliveryId });
  if (delivery.status === 'sent') return; // já foi, pular
  await emailProvider.send(data);
  await delivery.update({ status: 'sent', sentAt: new Date() });
}

❌ Ignorar opt-out

// ERRADO: enviar para todos sem verificar preferências
const users = await db.users.findAll();
for (const user of users) {
  await sendEmail(user.email, template);
}

// CORRETO: filtrar por preferências antes de enfileirar
const users = await db.users.findAll({
  where: { 
    emailNotificationsEnabled: true,
    emailVerified: true,
    emailBounced: false
  }
});

❌ Push token inválido não removido

// ERRADO: continua tentando enviar para token expirado
await fcm.send({ token: user.pushToken, ... });
// se 404/InvalidRegistration, ignora

// CORRETO: limpar token inválido
try {
  await fcm.send({ token: user.pushToken, ... });
} catch (err) {
  if (err.code === 'messaging/invalid-registration-token') {
    await db.users.update({ id: user.id, pushToken: null });
  }
}

QUALITY GATES

  • Opt-out global e por tipo respeitado em 100% dos canais
  • Idempotency verificada antes de cada tentativa de envio
  • Hard bounce marca email como inválido imediatamente
  • Templates validam variáveis antes de render
  • Retry com backoff exponencial, máx 5 tentativas antes de DLQ
  • FCM token inválido removido ao receber erro de token
  • Horário silencioso respeita timezone do usuário
  • Dead letter queue com alertas configurados
  • Notificações transacionais não afetadas por opt-out de marketing
  • Provider failover testado em staging

FORBIDDEN

  • Enviar notificações sem verificar preferências do usuário
  • Retry ilimitado — máximo N attempts antes de dead letter
  • Armazenar FCM/APNs tokens inválidos sem limpeza
  • Templates que aceitam variáveis undefined silenciosamente
  • Notificações não-transacionais para usuários que optaram por sair
  • Envio em horário silencioso sem verificar timezone do receptor
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall