sistema-de-chamados/docs/EMAIL-NOTIFICATIONS.md

# 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: '<html>...</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 `<style>`)
- Imagens com atributo `alt`
- Fallback para fontes do sistema
- Max-width com media queries

---

## Proximos Passos

### Funcionalidades Planejadas

- [ ] Resumos digest (diario/semanal)
- [ ] Preferencias por categoria
- [ ] Relatorios semanais para admins
- [ ] Notificacoes de backup
- [ ] Fila de envio com retry

### Melhorias

- [ ] Testes automatizados para templates
- [ ] Preview de e-mail na interface
- [ ] Metricas de entrega
- [ ] Integracao com servicos de e-mail marketing