Criar email com link de acesso ao efomento para upload de arquivos

[Junior-Shyko]

Contexto

• O repositório Service de Email é um microsserviço dedicado exclusivamente ao disparo de emails no ecossistema Efomento
• O projeto já possui estrutura base com Events, Listeners, Views e Jobs configurados em Laravel 12
• Este serviço será consumido pelo sistema Efomento via mensageria (filas) para envio do TERMO DE ASSINATURA do Mapa Cultural
• É crítico garantir que todos os disparos sejam registrados, testados e monitorados para garantir entregabilidade e rastreabilidade
• Os emails devem conter link tokenizado com validade determinada e template padronizado

Objetivo

Como desenvolvedor do Service de Email
Quero implementar e testar o fluxo de disparo de email do TERMO DE ASSINATURA com eventos, listeners e jobs
Para garantir que os emails sejam enviados com confiabilidade, registrando todos os eventos e possuindo cobertura de testes unitários com PHPUnit

Escopo

• Criar Event SignatureTermEmailRequested para disparo do email de termo de assinatura
• Criar Listener SendSignatureTermEmail que processa o evento e dispara o email
• Criar Mailable SignatureTermMailable com template Blade (view) contendo link tokenizado
• Implementar Job ProcessSignatureEmail para processamento assíncrono via fila
• Configurar queue connection para recebimento de mensagens da mensageria
• Implementar registro de log/auditoria após envio bem-sucedido (data, hora, status)
• Criar testes unitários com PHPUnit para Event, Listener, Mailable e Job
• Implementar tratamento de falhas com retry automático (Laravel Queue retry)
• Configurar variáveis de ambiente para SMTP e credenciais de envio
• Documentar endpoint/console command para consumo via mensageria

Fora de Escopo

• Interface gráfica ou painel administrativo (serviço headless/API)
• Leitura de emails via IMAP (este serviço é apenas para envio)
• Validação de token ou lógica de negócio do Efomento (apenas disparo)
• Armazenamento de arquivos ou uploads
• Gestão de múltiplos templates de email (apenas template do TERMO DE ASSINATURA inicialmente)
• Integração direta com banco de dados do Efomento (comunicação apenas via mensageria)

Critérios de Aceitação

• Evento de Solicitação de Email
  Dado que o sistema Efomento envia uma mensagem para a fila
  Quando o Service de Email recebe a mensagem
  Então o Event SignatureTermEmailRequested deve ser disparado com os dados do proponente

• Processamento do Listener
  Dado que o evento foi disparado
  Quando o Listener SendSignatureTermEmail é executado
  Então o Mailable deve ser instanciado e enviado via queue job

• Template de Email Renderizado
  Dado que o Mailable foi instanciado
  Quando o email é renderizado
  Então a view Blade deve conter: nome do proponente, NUP do projeto, link tokenizado e instruções claras

• Disparo via Fila
  Dado que o Job ProcessSignatureEmail está na fila
  Quando o worker processa a fila
  Então o email deve ser enviado e o status registrado no log

• Registro de Envio
  Dado que o email foi enviado com sucesso
  Quando o Job é concluído
  Então um registro deve ser criado contendo: recipient, sent_at, status, message_id

• Tratamento de Falhas
  Dado que ocorre erro no SMTP ou na conexão
  Quando o Job falha
  Então o Laravel deve fazer retry automático conforme configuração e logar o erro

• Teste Unitário do Event
  Dado que o teste PHPUnit é executado
  Quando testa a classe SignatureTermEmailRequested
  Então deve validar que os dados (nome, NUP, email, token) são armazenados corretamente no evento

• Teste Unitário do Listener
  Dado que o teste PHPUnit é executado
  Quando testa a classe SendSignatureTermEmail
  Então deve validar que o Mailable é disparado e o job é criado na fila

• Teste Unitário do Mailable
  Dado que o teste PHPUnit é executado
  Quando testa a classe SignatureTermMailable
  Então deve validar que a view é renderizada e contém o link tokenizado

• Teste Unitário do Job
  Dado que o teste PHPUnit é executado
  Quando testa a classe ProcessSignatureEmail
  Então deve validar que o email é enviado e o registro de log é criado

Observações

• Laravel 12: Utilizar sintaxe e features nativas do Laravel 12 (typed properties, match expressions, etc.)
• PHPUnit: Cobertura mínima de 80% para as classes de email (Event, Listener, Mailable, Job)
• Estrutura de Testes Sugerida: