Pular para o conteúdo principal

Feature: Notificações via Novu

Introdução ao documento​

Documenta o mecanismo de notificações push/e-mail via API Novu integrado ao ciclo de vida das submissões.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Visão geral​

O sistema envia notificações em momentos-chave do ciclo de vida da submissão usando a API do Novu. Quatro workflows distintos são utilizados, cada um mapeado na tabela novu_keys com um app_key identificador.

Atores​

  • Participante (aluno) — recebe notificações de confirmação e solicitação de reenvio
  • Facilitador (professor) — recebe notificação de nova submissão
  • Sistema (Novu API) — processa e envia notificações

Pré-condições​

  1. NOVU_URL configurado no ambiente — Evidência: app/Services/NotificationService.php:19
  2. NOVU_SECRET_KEY configurado no ambiente — Evidência: app/Services/NotificationService.php:20
  3. Workflows registrados na tabela novu_keys com app_key correspondente — Evidência: app/Models/NovuKey.php:13

Fluxo principal​

  1. Ação ocorre no controller (store, update, destroy)
  2. Controller chama NotificationService::sendNotification() com app_key do workflow
    • Evidência: app/Services/NotificationService.php:23
  3. Service busca novu_key na tabela novu_keys pelo app_key fornecido
  4. Service faz HTTP POST para NOVU_URL com novu_key como name e dados do subscriber
  5. Novu API processa e envia notificação (e-mail/push)

Workflows (4 identificados)​

app_keyMomentoDestinatárioTrigger
send-submissionApós submissão pelo participanteParticipanteSubmissionController::store:187
submission-receivedApós submissão pelo participanteFacilitadorSubmissionController::store:187
submission-evaluatedApós avaliação pelo facilitadorParticipanteSubmissionController::update:340
request-resubmissionApós solicitação de reenvioParticipanteSubmissionController::destroy:413
  • Evidência: app/Services/NotificationService.php:23, app/Http/Controllers/Api/SubmissionController.php:187,340,413

Fluxos alternativos​

  • Workflow não cadastrado: Se app_key não existe na tabela novu_keys, notificação não é enviada. Erro registrado em logs.
  • Novu API indisponível: Request falha, erro registrado. Operação principal (submissão/avaliação) não é afetada.
  • Credenciais inválidas: HTTP 401 do Novu, operação principal prossegue.

Regras de negócio​

  1. Fire-and-forget: Falha na notificação NÃO interrompe a operação principal.
    • Evidência: app/Http/Controllers/Api/SubmissionController.php:187 (try/catch implícito)
  2. Configuração via banco: Workflows são dinâmicos, gerenciados na tabela novu_keys via Backpack.
    • Evidência: routes/backpack/custom.php:31, app/Http/Controllers/Admin/NovuKeyCrudController.php
  3. Provider singleton: NotificationService é registrado como singleton via NovuServiceProvider.
    • Evidência: app/Providers/NovuServiceProvider.php:14

Estados possíveis​

  • Não aplicável (notificação é evento, não tem estado persistido)

Endpoints envolvidos​

  • Disparadas internamente pelos endpoints de submissão (openapi.yaml)
  • CRUD de workflows: /admin/novu-key (Backpack)
    • Evidência: routes/backpack/custom.php:31

Dados impactados​

  • novu_keys — configuração de workflows (model.md)

Pendências​

  • ⚠️ PENDÊNCIA: NOVU_URL e NOVU_SECRET_KEY não constam no .env.example. Devem ser adicionados.
  • ⚠️ PENDÊNCIA: Implementar retry/queue para notificações falhas.
  • ⚠️ PENDÊNCIA: Documentar payload exato enviado ao Novu (subscriber fields).