feat: automações com envio de e-mail

docs/AUTOMATIONS_EMAIL.md

@@ -0,0 +1,79 @@
+# Automações ▸ Envio de e-mails (guia de manutenção)
+
+## Visão geral
+O envio de e-mails via automações funciona como uma **ação** dentro do motor de automações de tickets.
+
+Por motivos de compatibilidade e segurança:
+- O HTML do e-mail é gerado com **tabelas + CSS inline** (compatível com Gmail/Outlook/Apple Mail).
+- O envio (SMTP) acontece em **Convex Action** (`"use node"`), porque mutações Convex não devem fazer I/O de rede.
+
+## Onde as automações disparam
+Os eventos de ticket chamam o motor de automações em `convex/tickets.ts`:
+- Criação do ticket (`TICKET_CREATED`)
+- Alteração de status (`STATUS_CHANGED`)
+- Alteração de prioridade (`PRIORITY_CHANGED`)
+- Alteração de fila (`QUEUE_CHANGED`)
+- Inclusão de comentário (`COMMENT_ADDED`)
+- Finalização/resolução (`TICKET_RESOLVED`)
+
+## Onde a ação é validada e aplicada
+Arquivo: `convex/automations.ts`
+
+Pontos principais:
+- **Validação/parse** da ação `SEND_EMAIL` em `parseAction(...)`.
+- **Execução** em `applyActions(...)`:
+  - Resolve destinatários (solicitante, responsável, usuário interno e e-mails livres).
+  - Faz interpolação de variáveis `{{...}}` em assunto/mensagem.
+  - Gera o HTML com `renderAutomationEmail(...)` (`convex/emailTemplates.ts`).
+  - Agenda o envio via `ctx.scheduler.runAfter(1, api.ticketNotifications.sendAutomationEmail, ...)`.
+
+## Onde o e-mail é enviado de fato (SMTP)
+Arquivo: `convex/ticketNotifications.ts`
+
+- A action `sendAutomationEmail` faz o envio via SMTP e aceita:
+  - `to`: lista de destinatários
+  - `subject`: assunto
+  - `html`: HTML já renderizado
+
+Observação: para não “vazar” destinatários entre si, o envio é feito **um-a-um** (um e-mail por destinatário).
+
+## Templates de e-mail
+Arquivo: `convex/emailTemplates.ts`
+
+Templates adicionados:
+- `renderAutomationEmail(...)`: usado pela ação `SEND_EMAIL` (inclui cartão com dados do ticket + CTA).
+- `renderSimpleNotificationEmail(...)`: utilitário reaproveitado por notificações simples (comentário público / encerramento).
+
+## Variáveis suportadas (interpolação)
+Você pode usar estas variáveis em **Assunto** e **Mensagem**:
+- `{{ticket.reference}}`
+- `{{ticket.subject}}`
+- `{{ticket.status}}`
+- `{{ticket.priority}}`
+- `{{company.name}}`
+- `{{requester.name}}`
+- `{{assignee.name}}`
+- `{{ticket.url.portal}}`
+- `{{ticket.url.staff}}`
+- `{{automation.name}}`
+
+## Link do botão (CTA)
+A UI permite escolher:
+- `Auto` (padrão): se houver destinatário interno (responsável/usuário) usa **Painel**; caso contrário usa **Portal**.
+- `Portal (cliente)`: `/portal/tickets/:id`
+- `Painel (agente)`: `/tickets/:id`
+
+Se você precisar enviar para cliente **e** agente no mesmo evento, prefira criar **duas ações SEND_EMAIL** (uma com link Portal e outra com link Painel).
+
+## Variáveis de ambiente (SMTP)
+O envio no Convex tenta usar:
+- `SMTP_ADDRESS` ou `SMTP_HOST`
+- `SMTP_USERNAME` ou `SMTP_USER`
+- `SMTP_PASSWORD` ou `SMTP_PASS`
+- `SMTP_PORT` (default `465`)
+- `MAILER_SENDER_EMAIL` (legacy) ou `SMTP_FROM_EMAIL` + `SMTP_FROM_NAME`
+
+## Testes de regressão
+Arquivo: `tests/automations-engine.test.ts`
+- Teste adiciona um cenário onde a ação `SEND_EMAIL` está presente e valida que o envio é agendado via `scheduler.runAfter`.
+