NameNotification ServiceTypeWORKERCategorySHAREDVersion1.0.0DescriptionWorker responsável por orquestrar e entregar notificações multicanal (in-app, push via FCM, email via SendGrid, SMS via Twilio) a partir de eventos e jobs do ecossistema INNK.
Escopo (bem delimitado)
- Consumir jobs de filas (BullMQ/Redis) gerados por outros serviços e/ou por crons.
- Resolver destinatários, aplicar preferências/canais habilitados e quiet hours, renderizar templates, e registrar o status de entrega.
- Operações auxiliares: monitoramento de filas e tratamento/reprocessamento via Dead Letter Queue (DLQ).
Fora de escopo
- Mensageria e conversas em tempo real: Messaging Service (113).
- Regras de negócio de booking/pagamentos/reviews e geração de eventos: serviços de domínio correspondentes.
- Autenticação/gestão de identidade: INNK Auth Service (105).
Confiabilidade (regras obrigatórias)
- Idempotência (obrigatória): todas as mensagens de envio/atualização devem conter idempotencyKey. O worker aplica deduplicação antes de qualquer efeito colateral:
- sendNotification: chave composta (idempotencyKey + recipientId + channel)
- sendBulkNotification: dedup por item (idempotencyKey + recipientId + channel)
- updateNotificationPreferences: (userId + idempotencyKey)
Persistência recomendada: Redis SETNX com TTL (ex: 7-30 dias) e/ou tabela de deliveries.
- Retries (obrigatório): cada operação job define maxAttempts e backoff exponencial com jitter. Apenas erros transitórios (providerError/transientError) são retryable.
- DLQ (obrigatório): ao exceder maxAttempts ou em falhas permanentes, a mensagem deve ser enviada para a fila notification.dlq com payload original + lastError + attempts.
- Logs e rastreabilidade: logs estruturados e métricas devem incluir correlationId (sempre) e causationId (quando houver), além de idempotencyKey.
Operação / graceful shutdown
- SIGTERM/SIGINT: parar de consumir novos jobs, aguardar jobs em execução até um shutdownTimeout (ex: 30s), finalizar ACK/NACK corretamente, drenar conexões (Redis/HTTP) e encerrar o processo com código apropriado.
- Em shutdown forçado, jobs em andamento devem ser reentregues pela fila (sem duplicar efeitos devido à idempotência).