# 📋 Lógica Completa da Fila de Mensagens WhatsApp

Este documento descreve a lógica completa e corrigida do sistema de filas de mensagens do WhatsApp.

## 🎯 Regras de Negócio

### 1. Todas as Mensagens Passam pela Fila
- ✅ Mensagens individuais (página de usuários, servidores, configurações)
- ✅ Mensagens de marketing
- ✅ Mensagens de remarketing
- ✅ Avisos de vencimento
- ✅ Mensagens de texto, mídia e áudio

**Nenhuma mensagem é enviada diretamente** - todas passam pela fila.

### 2. Intervalo Aleatório entre Mensagens
- Intervalo configurado em `/settings` (aba Geral)
- Campos: `whatsapp_delay_min` e `whatsapp_delay_max` (em segundos)
- Cada mensagem tem um intervalo aleatório entre min e max
- Intervalo é calculado automaticamente ao criar jobs

### 3. Verificação de Conexão Antes de Enviar
- Antes de enviar cada mensagem, verifica se a instância está conectada
- Se **conectada**: envia a mensagem
- Se **desconectada**: 
  - Pausa a fila automaticamente
  - Cria notificação no sininho (sino próximo ao perfil)
  - Usuário precisa reconectar e clicar em "Retomar"

### 4. Retomada Automática
- Quando WhatsApp reconecta, a fila é retomada automaticamente
- Notificação é criada informando que a fila foi retomada
- Jobs são marcados como `pending` com `scheduled_at = now()`

## 🔄 Fluxo Completo

### Criação de Job
1. Usuário envia mensagem (qualquer origem)
2. Sistema cria `WhatsAppQueueJob` com status `pending`
3. `scheduled_at` é calculado:
   - Se não há jobs pendentes: `now()` (primeira mensagem)
   - Se há jobs pendentes: último `scheduled_at` + intervalo aleatório
4. Job é salvo no banco

### Processamento de Job
1. Scheduler ou dispatch manual executa `ProcessWhatsAppQueue`
2. Job é selecionado atomicamente (lock para evitar race conditions)
3. Status muda para `processing`
4. Verificações:
   - ✅ Fila habilitada para o usuário?
   - ✅ WhatsApp conectado?
5. Se tudo OK:
   - Formata número (adiciona `@s.whatsapp.net`)
   - Envia mensagem via EvolutionAPI
   - Marca como `sent`
   - Agenda próximo job com intervalo
6. Se desconectado:
   - Pausa job atual
   - Pausa todos os jobs pendentes do usuário
   - Cria notificação no sininho
   - Para processamento

### Retomada Manual
1. Usuário clica em "Retomar"
2. Sistema verifica se WhatsApp está conectado
3. Se conectado:
   - Jobs pausados → `pending`
   - `scheduled_at` → `now()` (processamento imediato)
   - `error_message` → limpo
   - Múltiplos processadores são disparados
4. Jobs começam a ser processados imediatamente

### Retomada Automática
1. `CheckWhatsAppConnections` roda a cada minuto
2. Detecta que WhatsApp reconectou (status mudou de `disconnected` → `open`)
3. Atualiza status da conexão para `connected`
4. Se `whatsapp_pause_on_disconnect = true`:
   - Retoma fila automaticamente
   - Cria notificação de reconexão
   - Jobs começam a ser processados

## 📊 Cálculo de Intervalo

### Ao Criar Job Individual
```php
// Se não há jobs pendentes
scheduled_at = now()

// Se há jobs pendentes
ultimo_scheduled_at = último job pendente.scheduled_at
delay = rand(delay_min, delay_max)
scheduled_at = ultimo_scheduled_at + delay segundos
```

### Ao Criar Múltiplos Jobs (Campanhas)
```php
// Calcula incrementalmente dentro do loop
current_scheduled = último job pendente.scheduled_at OU now()
foreach cliente:
    delay = rand(delay_min, delay_max)
    current_scheduled = current_scheduled + delay
    cria job com scheduled_at = current_scheduled
```

### Ao Processar Job
```php
// Após enviar mensagem com sucesso
delay = rand(delay_min, delay_max)
próximo_job.scheduled_at = now() + delay segundos
```

## 🔔 Notificações

### Tipos de Notificação
1. **whatsapp_disconnected**: WhatsApp desconectado, fila pausada
2. **whatsapp_reconnected**: WhatsApp reconectado, fila retomada

### Onde Aparecem
- Sininho no cabeçalho (próximo ao perfil)
- Página de notificações (`/notifications`)

### Quando São Criadas
- Ao detectar desconexão durante processamento
- Ao detectar reconexão (CheckWhatsAppConnections)
- Evita duplicatas (verifica últimas 5 minutos)

## ⚙️ Configurações do Usuário

### Campos em `/settings` (aba Geral)
- `whatsapp_delay_min`: Intervalo mínimo entre mensagens (segundos)
- `whatsapp_delay_max`: Intervalo máximo entre mensagens (segundos)
- `whatsapp_pause_on_disconnect`: Pausar fila quando desconectar? (boolean)
- `whatsapp_queue_enabled`: Fila habilitada? (boolean)

## 🔍 Endpoints da API

### Fila
- `GET /api/v1/whatsapp/queue` - Listar jobs
- `GET /api/v1/whatsapp/queue/stats` - Estatísticas
- `POST /api/v1/whatsapp/queue/pause` - Pausar fila
- `POST /api/v1/whatsapp/queue/resume` - Retomar fila
- `POST /api/v1/whatsapp/queue/clear` - Limpar fila
- `DELETE /api/v1/whatsapp/queue/{id}` - Deletar job

### Envio de Mensagens
- `POST /api/v1/whatsapp/send-message` - Enviar texto (usa fila)
- `POST /api/v1/whatsapp/send-media` - Enviar mídia (usa fila)
- `POST /api/v1/whatsapp/send-audio` - Enviar áudio (usa fila)

## 🛠️ Comandos Artisan

```bash
# Processar fila manualmente
php artisan whatsapp:process-queue --count=5

# Verificar scheduler
php artisan schedule:list
```

## 📝 Logs Importantes

- `Queue disabled for user` - Fila desabilitada
- `WhatsApp disconnected, pausing queue` - WhatsApp desconectado
- `WhatsApp message sent successfully` - Mensagem enviada
- `Next WhatsApp job delay set` - Intervalo calculado
- `User queue resumed automatically after reconnection` - Retomada automática

## ✅ Checklist de Funcionamento

- [x] Todas as mensagens passam pela fila
- [x] Intervalo aleatório entre mensagens
- [x] Verificação de conexão antes de enviar
- [x] Pausa automática quando desconecta
- [x] Notificação no sininho quando desconecta
- [x] Retomada automática quando reconecta
- [x] Retomada manual funciona corretamente
- [x] Cálculo correto de intervalo em campanhas
- [x] Scheduler processa fila a cada 30 segundos

---

**Data de Implementação**: 06/01/2025  
**Versão**: 3.0.0