# 🔧 Correções do Sistema de Fila WhatsApp

Este documento detalha todas as correções e melhorias implementadas no sistema de filas de mensagens do WhatsApp.

## 📋 Problemas Identificados e Corrigidos

### 1. Campo `client_id` Ausente
**Problema**: O controller tentava salvar `client_id` mas a tabela não tinha esse campo.

**Solução**:
- ✅ Migration criada: `2025_01_06_000001_add_client_id_to_whatsapp_queue_jobs.php`
- ✅ Campo adicionado ao model `WhatsAppQueueJob`
- ✅ Relacionamento `client()` adicionado

### 2. Jobs Ficando em Estado "Processing" Indefinidamente
**Problema**: Quando a fila estava desabilitada ou o WhatsApp desconectado, os jobs ficavam travados em "processing".

**Solução**:
- ✅ Jobs são marcados como `paused` quando fila desabilitada
- ✅ Jobs são marcados como `paused` quando WhatsApp desconectado (se configurado)
- ✅ Notificação criada para o usuário quando desconectado

### 3. Formato de Número de Telefone Incorreto
**Problema**: A EvolutionAPI requer formato `553198296801@s.whatsapp.net`, mas o sistema enviava apenas o número.

**Solução**:
- ✅ Método `formatPhoneNumber()` adicionado no `ProcessWhatsAppQueue`
- ✅ Formatação automática antes de enviar para API
- ✅ Validação de números no `WhatsAppQueueService`

### 4. Validação Insuficiente de Respostas da API
**Problema**: O sistema não validava adequadamente as respostas da EvolutionAPI, podendo marcar mensagens como enviadas quando falhavam.

**Solução**:
- ✅ Validação de estrutura de resposta antes de marcar como enviado
- ✅ Verificação de campo `success` na resposta
- ✅ Tratamento específico de timeouts de conexão
- ✅ Logs detalhados para debugging

### 5. Lógica de Retry com Problemas
**Problema**: Retry não funcionava corretamente e não havia backoff exponencial.

**Solução**:
- ✅ Retry com backoff exponencial (5, 10, 15 minutos)
- ✅ Contador de tentativas incrementado corretamente
- ✅ Jobs falhados permanentemente após 3 tentativas

### 6. Agendamento de Próximo Job
**Problema**: Lógica de agendamento podia causar conflitos e não garantia processamento contínuo.

**Solução**:
- ✅ Agendamento melhorado para evitar conflitos
- ✅ Exclusão do job atual ao buscar próximo
- ✅ Dispatch automático do processador após cada job

### 7. Validação de Dados Insuficiente
**Problema**: Não havia validação adequada de números de telefone e tipos de mensagem.

**Solução**:
- ✅ Validação de formato de número (10-15 dígitos)
- ✅ Validação de tipo de mensagem (text, media, audio)
- ✅ Validação de campos obrigatórios por tipo
- ✅ Validação de URLs de mídia

## 🚀 Melhorias Adicionais

### Scheduler Automático
- ✅ Processador de fila executado automaticamente a cada 30 segundos
- ✅ Garante processamento mesmo se dispatches manuais falharem
- ✅ Configurado em `app/Console/Kernel.php`

### Comando Artisan
- ✅ Comando `whatsapp:process-queue` criado para processar fila manualmente
- ✅ Opção `--count` para processar múltiplos jobs
- ✅ Útil para debugging e processamento sob demanda

### Link com WhatsAppMessage
- ✅ Jobs agora linkam com registros de `WhatsAppMessage`
- ✅ Status de mensagem atualizado quando job é enviado
- ✅ Rastreamento completo de mensagens

### Timeouts Configurados
- ✅ Timeout de 30 segundos para mensagens de texto
- ✅ Timeout de 60 segundos para mídia/áudio
- ✅ Tratamento adequado de timeouts

## 📝 Como Usar

### Processar Fila Manualmente
```bash
# Processar 1 job
php artisan whatsapp:process-queue

# Processar 5 jobs
php artisan whatsapp:process-queue --count=5
```

### Verificar Status da Fila
```bash
# Via API
GET /api/v1/whatsapp/queue/stats
```

### Pausar/Retomar Fila
```bash
# Pausar
POST /api/v1/whatsapp/queue/pause

# Retomar
POST /api/v1/whatsapp/queue/resume
```

## 🔍 Monitoramento

### Logs Importantes
- `Queue disabled for user` - Fila desabilitada para usuário
- `WhatsApp disconnected, pausing queue` - WhatsApp desconectado
- `WhatsApp message sent successfully` - Mensagem enviada com sucesso
- `Error processing WhatsApp queue job` - Erro ao processar job
- `Job rescheduled for retry` - Job reagendado para retry
- `Job failed permanently after max attempts` - Job falhou permanentemente

### Verificar Jobs Presos
```sql
-- Jobs em processing há mais de 10 minutos
SELECT * FROM whatsapp_queue_jobs 
WHERE status = 'processing' 
AND updated_at < NOW() - INTERVAL 10 MINUTE;

-- Jobs falhados
SELECT * FROM whatsapp_queue_jobs 
WHERE status = 'failed' 
ORDER BY updated_at DESC;
```

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

Os usuários podem configurar:
- `whatsapp_queue_enabled` - Habilitar/desabilitar fila
- `whatsapp_delay_min` - Delay mínimo entre mensagens (segundos)
- `whatsapp_delay_max` - Delay máximo entre mensagens (segundos)
- `whatsapp_pause_on_disconnect` - Pausar fila quando desconectar

## 🐛 Troubleshooting

### Jobs não estão sendo processados
1. Verificar se scheduler está rodando: `php artisan schedule:list`
2. Verificar se há jobs pendentes: `SELECT COUNT(*) FROM whatsapp_queue_jobs WHERE status = 'pending'`
3. Processar manualmente: `php artisan whatsapp:process-queue`

### Mensagens não estão sendo enviadas
1. Verificar status da conexão WhatsApp
2. Verificar logs de erro
3. Verificar se número está no formato correto
4. Verificar se API da Evolution está respondendo

### Jobs ficando em "processing"
1. Verificar se há jobs presos (query acima)
2. Resetar manualmente: `UPDATE whatsapp_queue_jobs SET status = 'pending' WHERE status = 'processing' AND updated_at < NOW() - INTERVAL 10 MINUTE`

## 📊 Estatísticas

O endpoint `/api/v1/whatsapp/queue/stats` retorna:
- Total de jobs
- Jobs pendentes
- Jobs em processamento
- Jobs enviados
- Jobs falhados
- Jobs pausados
- Próximo agendamento

---

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