artubss/SKILLS-CLAUDE-CODE / favorites/tpl-dominio-notificacoes-multicanal
tpl-dominio-notificacoes-multicanal
VerifiedTemplate do pack (dominio/08-notificacoes-multicanal.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
SKILL.md
View on GitHub---
name: tpl-dominio-notificacoes-multicanal
description: Template do pack (dominio/08-notificacoes-multicanal.md). Orienta o agente em regras de negocio e requisitos de produto alinhado a esse contexto.
metadata:
version: 1.0.0
source_template: dominio/08-notificacoes-multicanal.md
generated_by: install_pack_templates_as_claude_skills
---
# 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
| Trigger | Action |
|---------|--------|
| Business event emitted | dispatch() → resolver recipients → check prefs → enqueue per channel |
| Queue job: send_email | Render template → send via provider → track delivery |
| Queue job: send_push | Build FCM/APNs payload → send → handle token invalidation |
| Queue job: send_sms | Build message → send via Twilio → track delivery |
| Queue job: send_in_app | Persist to DB → emit via WebSocket if connected |
| Provider webhook: bounce | Marcar email como hard/soft bounce → suspender se hard |
| Provider webhook: unsubscribe | Atualizar preferências → honrar imediatamente |
| POST /notifications/preferences | Atualizar preferências do usuário |
| GET /notifications | Listar notificações in-app (com paginação cursor-based) |
| PATCH /notifications/:id/read | Marcar como lida |
| PATCH /notifications/read-all | Marcar todas como lidas |
| GET /notifications/unread-count | Count para badge (cacheável por 30s) |
| POST /admin/notifications/test | Enviar notificação de teste para email/phone específico |
| GET /admin/notifications/:id/status | Status 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |