Plano do Módulo packages/communications

Objetivo

Construir um broker de notificações multicanal (e-mail, SMS, WhatsApp) baseado em eventos e templates padronizados, mantendo histórico e observabilidade. O design replica a abordagem de drivers do packages/invoices, permitindo integrar diversos gateways por canal sem acoplamento.

Estrutura Inicial

packages/communications/
├─ src/
│  ├─ Channels/
│  │  ├─ SMTPChannel.php
│  │  ├─ WhatsAppChannel.php
│  │  └─ SMSChannel.php
│  │      └─ Drivers/
│  │          ├─ TwilioDriver.php
│  │          └─ VonageDriver.php
│  ├─ Templates/
│  ├─ Jobs/
│  ├─ Listeners/
│  └─ DTOs/
├─ resources/views/templates/
├─ database/
│  ├─ migrations/
│  └─ seeders/
├─ tests/
│  ├─ Feature/
│  └─ Unit/
└─ composer.json

Pontos-Chave

• Channels: cada canal implementa NotificationChannelInterface definido em packages/contracts, com subdiretórios Drivers/ para provedores específicos.
• Template Engine: suportar variáveis (\{\{invoice.number\}\}, \{\{person.name\}\}) e fallback por idioma.
• Dispatcher: listeners transformam eventos (InvoiceCreated, PaymentCompleted, PersonCreated) em jobs assíncronos.
• Auditoria: registrar envios em tabela dedicada com status, payload e metadados.

Integrações

• Consumir DTOs de fatura e pessoa para preencher templates.
• Expor Webhooks para parceiros externos reagirem a eventos de envio (entregue, falha, reprocessar).
• Permitir configuração de provedores externos por environment (config/communications.php) e priorização/rota.

Roadmap Técnico

1. Implementar canal SMTP como referência e cobrir com testes funcionais.
2. Entregar UI mínima (Filament) para visualizar filas, histórico e reenvio manual.
3. Documentar novos canais em docs/communications/integrations.md com exemplos de payload.

Referências

• Guia Communications
• Roadmap Técnico
• Diagrama Monorepo