📄 Documento de Execução — Card 31: [M6] E-mail Workflows

Campo	Valor
Card Trello	[31] [M6] Automações de E-mail (Workflows)
URL Trello	https://trello.com/c/QQMtY4gd
Marco	M6 (IA + WhatsApp + CRM)
Data execução	09/08/2026
Responsável	Wellington Santiago (via ZCode)
Doc anterior	Card 30: CRM Kanban
Próximo card	Card 32: Testes UAT (M7)
Commits	`1eb4da2`, `134a394`

🎯 1. O que foi implementado

Motor de automação de e-mail com 7 workflows + gatilhos push M2 (6 notificações). Provider: Resend (transacional), com modo mock (console) quando RESEND_API_KEY ausente — útil em DEV.

7 Workflows (criados via seed)

BIRTHDAY — aniversário (diário 08:00)
PAYMENT_REMINDER — lembrete vencimento (3d+1d+dia)
GRADE_PUBLISHED — nota publicada (event-driven)
ENROLLMENT_WELCOME — boas-vindas matrícula
LEAD_LOST_REENGAGE — lead perdido reengajamento (default OFF)
ABSENCE_NOTICE — aviso de falta (lote 20:00)
SCHEDULED_REPORT — relatório agendado

6 Gatilhos push M2 (herdados, realocados)

Helper central notifyUser() (in-app + push) plugado em:

Nova nota publicada → GRADE_PUBLISHED aos responsáveis
Nova falta (ABSENT) → ATTENDANCE_ALERT aos responsáveis
Nova mensagem chat → NEW_MESSAGE ao destinatário
Novo comunicado → NEW_ANNOUNCEMENT à turma
Mensalidade vencida → PAYMENT_REMINDER ao responsável
Justificativa revisada → ENROLLMENT_UPDATE ao responsável

✅ Critérios de aceite validados

#	Critério	Status
1	7 workflows com gatilhos configuráveis	✅
2	Templates editáveis com variáveis {{nome}}, {{filial}}	✅
3	Ativação/desativação por workflow (toggle)	✅
4	Logs registram envio, abertura e cliques	✅
5	Canal preferido do destinatário (NotificationConfig)	✅ (estrutura)
6	6 gatilhos push M2 plugados (notifyUser)	✅
7	Helper central sendEmail (Resend + mock)	✅
8	Build passa + lint OK	✅

📁 2. Arquivos criados/modificados

Criados

Arquivo	Função
`src/lib/email.ts`	Helper central: sendEmail (Resend), renderTemplate, sendWorkflowEmail, logEmail
`src/lib/notify.ts`	Helper central: notifyUser (in-app + push), notifyUsers, getGuardianUserIds
`src/app/(dashboard)/master/email/workflows/page.tsx`	Painel: 7 workflows + toggle + logs + teste + métricas
`src/styles/email-workflows.module.css`	Estilos do painel
`scripts/seed-email-workflows.js`	Seed: 7 templates + 7 workflows (PrismaPg adapter)

Modificados

Arquivo	Mudança
`src/server/trpc/routers/master.ts`	+sub-router email (overview/logs/toggle/templateUpsert/test)
`src/server/trpc/routers/professor.ts`	+notifyUser em notas.publish, attendance.mark, announcement.create
`src/server/trpc/routers/parent.ts`	+notifyUser em chat.send
`src/server/trpc/routers/local.ts`	+notifyUser em justificativas.review
`src/server/queues/workers/payment.ts`	+notifyUser em mark-overdue (lembrete mensalidade)
`prisma/schema.prisma`	+EmailWorkflow, EmailTemplate, EmailLog + enum EmailTrigger (7 valores)
`src/components/layout/nav-config.ts`	+item "E-mail" no menu Master

🗄️ 3. Schema do banco (mudanças)

Novas tabelas: email_templates, email_workflows, email_logs
Novo enum: EmailTrigger (BIRTHDAY, PAYMENT_REMINDER, GRADE_PUBLISHED, ENROLLMENT_WELCOME, LEAD_LOST_REENGAGE, ABSENCE_NOTICE, SCHEDULED_REPORT)
email_workflows.trigger é @unique (1 workflow por gatilho)
Migration via prisma db push + seed executado (7 templates + 7 workflows no banco)

🔌 4. Handoff para o próximo card (32 — UAT)

Variáveis de ambiente

RESEND_API_KEY= (vazio → modo mock/log; inserir para envio real)
RESEND_FROM_EMAIL=GENIOON <no-reply@genioon.com.br>
VAPID_PUBLIC_KEY / VAPID_PRIVATE_KEY (push — gerar com npx web-push generate-vapid-keys)

Helpers disponíveis

sendEmail({ to, subject, html, workflowId?, trigger? }) → { ok, error? }
renderTemplate(html, vars) — substitui {{variavel}}
sendWorkflowEmail({ workflowId, trigger, to, vars }) → busca template + envia
notifyUser({ userId, type, title, message, url?, data? }) — in-app + push
getGuardianUserIds(studentId) → string[] (responsáveis)

Workflows seed (já no banco)

Todos os 7 workflows criados com templates padrão PT-BR. 6 ativos, 1 inativo (LEAD_LOST_REENGAGE — ativar quando quiser).

📋 5. Deploy DEV

Migration: ✅ prisma db push (3 novas tabelas + enum)
Seed: ✅ 7 templates + 7 workflows criados
Build VPS: ✅
pm2 reload: ✅
Smoke test: /master/email/workflows → 307 (login)
URL: https://sistemaescolar.wellka.com.br/master/email/workflows

🧠 6. Contexto gerado para próximas etapas

Card 32 (UAT): testar gatilhos push (publicar nota → receber notificação).
Card 27 (Relatórios): email.logs + stats.openRate alimentam métricas.
Provider ativação: quando inserir RESEND_API_KEY, e-mails saem reais (sem mudança de código).
Push: precisa de VAPID keys no .env + sw.js com push event (parcialmente pronto — ver Card M5.5-D).

🎯 7. Próximo card

Card 32 [M7] Testes de Aceitação (UAT). Início do marco M7 (Go-Live).