# Sistema de Notificacoes por E-mail Este documento descreve o sistema completo de notificacoes por e-mail implementado na plataforma Raven. ## Visao Geral O sistema de notificacoes por e-mail permite que usuarios sejam informados sobre eventos importantes relacionados aos seus chamados, alem de notificacoes de seguranca e autenticacao. ### Principais Funcionalidades - Notificacoes de ciclo de vida do chamado (abertura, resolucao, atribuicao) - Notificacoes de comunicacao (comentarios publicos, respostas) - Sistema de avaliacao de chamados (estrelas 1-5) - Acesso direto ao chamado via protocolo `raven://` - Templates HTML responsivos - Sistema de preferencias configuravel - Alertas de SLA para staff - Notificacoes de seguranca (reset de senha, novo login) --- ## Tipos de Notificacoes ### Ciclo de Vida do Chamado | Tipo | Codigo | Destinatario | Pode Desativar? | |------|--------|-------------|-----------------| | Abertura de chamado | `ticket_created` | Solicitante | Nao (obrigatorio) | | Atribuicao de chamado | `ticket_assigned` | Solicitante + Agente | Sim | | Resolucao de chamado | `ticket_resolved` | Solicitante | Nao (obrigatorio) | | Reabertura de chamado | `ticket_reopened` | Solicitante + Agente | Sim | | Mudanca de status | `ticket_status_changed` | Solicitante | Sim | | Mudanca de prioridade | `ticket_priority_changed` | Agente atribuido | Sim | **Descricoes detalhadas:** - **Abertura de chamado**: Enviado ao solicitante quando um novo chamado e criado, confirmando o numero de referencia e detalhes do chamado. - **Atribuicao de chamado**: Notifica tanto o solicitante quanto o agente atribuido quando um chamado e designado para atendimento. - **Resolucao de chamado**: Enviado ao solicitante quando o chamado e marcado como resolvido. Inclui link para avaliacao com estrelas (1-5). - **Reabertura de chamado**: Notifica todas as partes quando um chamado fechado e reaberto. - **Mudanca de status**: Informa o solicitante sobre alteracoes de status (Em andamento, Pausado, etc). - **Mudanca de prioridade**: Notifica o agente atribuido quando a prioridade do chamado e alterada. ### Comunicacao | Tipo | Codigo | Destinatario | Pode Desativar? | |------|--------|-------------|-----------------| | Comentario publico | `comment_public` | Solicitante | Sim (apenas solicitante) | | Resposta do solicitante | `comment_response` | Agente atribuido | Sim | | Mencao em comentario | `comment_mention` | Usuario mencionado | Sim | **Descricoes detalhadas:** - **Comentario publico**: Enviado ao solicitante quando um agente adiciona um comentario publico ao chamado. - **Resposta do solicitante**: Notifica o agente atribuido quando o solicitante responde ao chamado. - **Mencao em comentario**: Notifica um usuario quando ele e mencionado (@usuario) em um comentario. ### SLA e Alertas (Apenas Staff) | Tipo | Codigo | Destinatario | Pode Desativar? | |------|--------|-------------|-----------------| | SLA em risco | `sla_at_risk` | Agente + Supervisor | Sim | | SLA violado | `sla_breached` | Agente + Admin | Sim | | Resumo diario de SLA | `sla_daily_digest` | Admin | Sim | **Descricoes detalhadas:** - **SLA em risco**: Enviado quando o chamado atinge 80% do tempo limite de resposta/resolucao. - **SLA violado**: Notificacao urgente quando o SLA e excedido. - **Resumo diario de SLA**: Relatorio enviado diariamente com metricas de SLA do dia anterior. ### Seguranca e Autenticacao | Tipo | Codigo | Destinatario | Pode Desativar? | |------|--------|-------------|-----------------| | Reset de senha | `security_password_reset` | Usuario | Nao (obrigatorio) | | Verificacao de e-mail | `security_email_verify` | Usuario | Nao (obrigatorio) | | Alteracao de e-mail | `security_email_change` | E-mail antigo | Nao (obrigatorio) | | Novo login detectado | `security_new_login` | Usuario | Sim | | Convite de usuario | `security_invite` | Novo usuario | Nao (obrigatorio) | **Descricoes detalhadas:** - **Reset de senha**: Link para redefinicao de senha. Expira em 1 hora. - **Verificacao de e-mail**: Link para confirmar novo endereco de e-mail. - **Alteracao de e-mail**: Notifica o e-mail antigo quando o endereco e alterado. - **Novo login detectado**: Alerta quando um login e realizado de um novo dispositivo ou localizacao. - **Convite de usuario**: Convite para novos usuarios criarem conta na plataforma. --- ## Sistema de Avaliacao de Chamados Quando um chamado e resolvido, o solicitante recebe um e-mail com opcao de avaliar o atendimento usando estrelas de 1 a 5. ### Fluxo de Avaliacao 1. Chamado e marcado como resolvido 2. Solicitante recebe e-mail com 5 estrelas clicaveis 3. Ao clicar em uma estrela, usuario e redirecionado para pagina de avaliacao 4. Na pagina, pode adicionar um comentario opcional 5. Avaliacao e registrada e associada ao chamado ### Endpoints - `GET /api/tickets/rate?token={token}&rating={1-5}` - Registra avaliacao via link do e-mail - `POST /api/tickets/rate` - Registra avaliacao com comentario ### Modelo de Dados ```prisma model TicketRating { id String @id @default(cuid()) tenantId String ticketId String @unique userId String rating Int // 1-5 estrelas comment String? // Feedback opcional createdAt DateTime @default(now()) } ``` --- ## Acesso Direto ao Chamado (Deep Linking) ### Protocolo raven:// O sistema suporta o protocolo `raven://` para abrir chamados diretamente no aplicativo desktop Raven. **Formatos suportados:** ``` raven://ticket/{ticketId}?token={accessToken} raven://chat/{ticketId}?token={accessToken} raven://rate/{ticketId}?rating={1-5}&token={accessToken} ``` ### Fluxo de Acesso 1. Usuario clica no link do e-mail (ex: `/ticket-view/{token}`) 2. Pagina web tenta abrir o protocolo `raven://` 3. Se o Raven estiver instalado, abre diretamente no app 4. Se nao estiver instalado (timeout de 3s), exibe o chamado na web ### Tokens de Acesso Tokens sao gerados para permitir acesso seguro sem necessidade de login. ```typescript interface TicketAccessToken { token: string // Token unico ticketId: string // Chamado associado userId: string // Usuario autorizado machineId?: string // Maquina esperada (opcional) scope: string // 'view', 'interact', 'rate' expiresAt: Date // Expira em 7 dias } ``` ### Endpoints - `GET /api/ticket-access/{token}` - Valida token e retorna informacoes - `POST /api/ticket-access/{token}` - Marca token como usado --- ## Preferencias de Notificacao ### Para Staff (Admin, Manager, Agent) Staff tem controle total sobre suas preferencias: - Ativar/desativar e-mails globalmente - Configurar horario de silencio - Escolher frequencia de resumo (imediato, diario, semanal) - Ativar/desativar cada tipo de notificacao individualmente - Configurar preferencias por categoria **Acesso:** `/settings/notifications` ### Para Solicitantes (Collaborators) Solicitantes tem opcoes limitadas: **Podem desativar:** - Comentarios publicos - Mudancas de status - Mudancas de prioridade - Novo login detectado **NAO podem desativar (obrigatorios):** - Abertura de chamado - Resolucao de chamado - Reset de senha - Verificacao/alteracao de e-mail - Convites **Acesso:** `/portal/profile/notifications` ### Modelo de Dados ```prisma model NotificationPreferences { id String @id @default(cuid()) userId String @unique tenantId String emailEnabled Boolean @default(true) quietHoursStart String? // "22:00" quietHoursEnd String? // "08:00" timezone String @default("America/Sao_Paulo") digestFrequency String @default("immediate") typePreferences Json @default("{}") categoryPreferences Json @default("{}") } ``` ### API de Preferencias - `GET /api/notifications/preferences` - Retorna preferencias do usuario - `PUT /api/notifications/preferences` - Atualiza preferencias --- ## Templates de E-mail Todos os e-mails utilizam templates HTML responsivos com design consistente com a plataforma. ### Templates Disponiveis | Template | Arquivo | Descricao | |----------|---------|-----------| | Teste | `test` | Template para testes de envio | | Abertura | `ticket_created` | Confirmacao de abertura de chamado | | Resolucao | `ticket_resolved` | Notificacao de resolucao com avaliacao | | Atribuicao | `ticket_assigned` | Notificacao de atribuicao | | Status | `ticket_status` | Mudanca de status | | Comentario | `ticket_comment` | Novo comentario publico | | Reset de senha | `password_reset` | Link para redefinir senha | | Verificar e-mail | `email_verify` | Confirmacao de e-mail | | Convite | `invite` | Convite para nova conta | | Novo login | `new_login` | Alerta de novo dispositivo | | SLA em risco | `sla_warning` | Alerta de SLA proximo do limite | | SLA violado | `sla_breached` | Alerta de SLA excedido | ### Tokens de Design Os templates utilizam os mesmos tokens de design da plataforma: ```css /* Cores principais */ --primary: #00e8ff --primary-dark: #00c4d6 --background: #f7f8fb /* Status */ --status-pending: #64748b --status-progress: #0ea5e9 --status-paused: #f59e0b --status-resolved: #10b981 /* Prioridade */ --priority-low: #64748b --priority-medium: #0ea5e9 --priority-high: #f97316 --priority-urgent: #ef4444 ``` --- ## Arquitetura ### Estrutura de Arquivos ``` src/ ├── server/ │ ├── email/ │ │ ├── email-service.ts # Servico principal de envio │ │ ├── email-templates.ts # Renderizacao de templates │ │ └── index.ts # Exports │ └── notification/ │ ├── notification-service.ts # Orquestrador de notificacoes │ └── token-service.ts # Gerenciamento de tokens ├── app/ │ ├── api/ │ │ ├── notifications/ │ │ │ └── preferences/ │ │ │ └── route.ts # API de preferencias │ │ ├── ticket-access/ │ │ │ └── [token]/ │ │ │ └── route.ts # API de tokens de acesso │ │ └── tickets/ │ │ └── rate/ │ │ └── route.ts # API de avaliacao │ ├── ticket-view/ │ │ └── [token]/ │ │ └── page.tsx # Pagina de visualizacao │ ├── rate/ │ │ └── [token]/ │ │ └── page.tsx # Pagina de avaliacao │ ├── settings/ │ │ └── notifications/ │ │ └── page.tsx # Preferencias (staff) │ └── portal/ │ └── profile/ │ └── notifications/ │ └── page.tsx # Preferencias (colaboradores) └── components/ └── settings/ └── notification-preferences-form.tsx ``` ### Servicos Principais #### EmailService (`email-service.ts`) Responsavel pelo envio de e-mails: ```typescript await sendEmail({ to: 'usuario@email.com', subject: 'Assunto do e-mail', html: '...', text: 'Versao texto', }) ``` #### NotificationService (`notification-service.ts`) Orquestra o envio de notificacoes: ```typescript // Notifica abertura de chamado await notifyTicketCreated(ticket) // Notifica resolucao await notifyTicketResolved(ticket, resolutionSummary) // Notifica comentario await notifyPublicComment(ticket, comment) ``` #### TokenService (`token-service.ts`) Gerencia tokens de acesso: ```typescript // Gera token const token = await generateAccessToken({ ticketId: 'xxx', userId: 'xxx', scope: 'view', expiresInDays: 7, }) // Valida token const validated = await validateAccessToken(token) ``` --- ## Configuracao SMTP O sistema utiliza SMTP para envio de e-mails. Consulte `docs/SMTP.md` para configuracao detalhada. ### Variaveis de Ambiente ```env SMTP_HOST=smtp.exemplo.com SMTP_PORT=587 SMTP_USER=usuario SMTP_PASS=senha SMTP_FROM=noreply@exemplo.com SMTP_FROM_NAME=Raven ``` --- ## Seguranca ### Protecoes Implementadas 1. **Tokens expiraveis**: Tokens de acesso expiram em 7 dias 2. **Uso unico para acoes**: Tokens de avaliacao sao invalidados apos uso 3. **Rate limiting**: Limite de envios por usuario/minuto 4. **Sanitizacao HTML**: Todo conteudo dinamico e escapado 5. **Links HTTPS**: Todos os links utilizam HTTPS 6. **Preferencias obrigatorias**: Notificacoes de seguranca nao podem ser desativadas ### Validacao de Tokens ```typescript // Verifica escopo do token if (!hasScope(token.scope, 'rate')) { return { error: 'Permissao insuficiente' } } // Verifica expiracao if (new Date() > token.expiresAt) { return { error: 'Token expirado' } } ``` --- ## Testes ### E-mail de Teste Para testar o sistema, utilize o endpoint de teste: ```typescript POST /api/email/test { "to": "email@teste.com" } ``` ### Variaveis de Teste ```env TEST_EMAIL_RECIPIENT=monkeyesdras@gmail.com ``` --- ## Compatibilidade ### Clientes de E-mail Suportados - Gmail (web + app) - Outlook (web + desktop + app) - Apple Mail (macOS + iOS) - Yahoo Mail - Thunderbird ### Tecnicas de Compatibilidade - Layout com tabelas (nao flexbox/grid) - CSS inline (nao blocos `