# Evolution Middleware

Middleware em Laravel entre os sistemas internos (acadeLotear, cereusLote, ...) e a
[Evolution API v2](https://doc.evolution-api.com) para envio de WhatsApp.

- Cada sistema tem o seu **token**; o middleware guarda só o hash (sha256).
- Cada sistema gerencia as suas **instâncias** (números de WhatsApp). Na Evolution o nome
  vira `{slug-do-sistema}_{nome}`, então dois sistemas podem usar o mesmo nome.
- O envio é **assíncrono** e **enfileirado por instância** (uma mensagem por vez por número),
  com o status "digitando..." proporcional ao tamanho do texto (ver [Anti-bot](#anti-bot)).
- Toda ação fica registrada em `action_logs`; mensagens em `messages`; eventos da Evolution
  em `webhook_events`.

## Instalação

```bash
composer install
cp .env.example .env && php artisan key:generate
# preencher DB_*, EVOLUTION_API_KEY, MIDDLEWARE_ADMIN_TOKEN e APP_URL
php artisan migrate
php artisan cliente:criar "Acade Lotear" --slug=acadelotear   # mostra o token uma única vez
```

O document root do servidor web deve apontar para `public/`.

### Painel web

Em `/painel` (login por e-mail e senha) ficam a gestão dos clientes/tokens e os logs de ações.
Crie o usuário com:

```bash
php artisan usuario:criar voce@empresa.com.br "Seu Nome"   # pede a senha; rodar de novo redefine
```

### Worker da fila (obrigatório)

Os envios rodam na fila `whatsapp`. Deixe um worker sempre ativo. Neste servidor ele roda pela
cron do usuário (`crontab -e`):

```cron
* * * * * cd /home/gabriel/public_html/evolutionAPI && /usr/bin/flock -n storage/framework/queue-worker.lock /usr/bin/php artisan queue:work --queue=whatsapp,default --timeout=180 --tries=0 --max-time=3600 --sleep=1 >> storage/logs/queue-worker.log 2>&1
```

- O `flock` impede dois workers ao mesmo tempo: enquanto um roda, as execuções seguintes saem
  na hora. Se o worker cair, a cron sobe outro em até 1 minuto.
- `--max-time=3600` faz o worker se renovar a cada hora (libera memória e carrega código novo).
- `--sleep=1`: com a fila vazia o worker consulta o banco a cada 1 s, então a mensagem vai para
  a Evolution em até ~1 s após chegar (mais o tempo de "digitando...", que é proposital).
- Após deploy de código, rode `php artisan queue:restart`: o worker termina o job atual e a
  cron sobe um novo com o código atualizado em até 1 minuto.
- Saída do worker em `storage/logs/queue-worker.log`.

Também funciona com supervisor, systemd ou pm2, rodando o mesmo `queue:work` sem o `flock`.

Vários workers podem rodar em paralelo: instâncias diferentes enviam ao mesmo tempo, mas
cada instância continua enviando uma mensagem por vez.

### Variáveis principais

| Variável | Descrição |
| --- | --- |
| `EVOLUTION_URL` | URL da Evolution (`http://server.gabrielbandeira.net:8080`) |
| `EVOLUTION_API_KEY` | `AUTHENTICATION_API_KEY` (global) da Evolution |
| `EVOLUTION_WEBHOOK_BASE_URL` | URL pública deste middleware, acessível pelo servidor da Evolution |
| `MIDDLEWARE_ADMIN_TOKEN` | Token das rotas `/api/admin` |
| `TYPING_*` | Parâmetros da simulação de digitação |
| `DB_QUEUE_RETRY_AFTER` | Deve ser maior que 180 (timeout do job de envio) |

## Autenticação

Todas as rotas de `/api` (exceto webhook e admin) exigem o token do sistema em **um** destes:

- `Authorization: Bearer evm_...`
- `X-Api-Token: evm_...`
- campo `token` no corpo/query

Envie também `usuario` (corpo) ou o header `X-Usuario` com o usuário do sistema de origem —
ele vai para o log de auditoria. Em `POST /api/mensagens` é obrigatório.

## Endpoints dos sistemas

| Método | Rota | Ação |
| --- | --- | --- |
| GET | `/api/instancias` | Lista as instâncias do sistema |
| POST | `/api/instancias` | Cria instância (`nome`, `numero?`, `webhook_url?`) e devolve o QR code |
| GET | `/api/instancias/{nome}` | Dados + status atualizado |
| GET | `/api/instancias/{nome}/qrcode` | QR code para vincular (`?formato=imagem` devolve PNG; `numero` gera pairing code) |
| GET | `/api/instancias/{nome}/status` | Status da conexão (`open`, `connecting`, `close`) |
| POST | `/api/instancias/{nome}/reiniciar` | Reinicia a instância |
| POST | `/api/instancias/{nome}/desvincular` | Logout do WhatsApp (pode vincular de novo) |
| DELETE | `/api/instancias/{nome}` | Remove a instância da Evolution |
| GET | `/api/instancias/{nome}/webhook` | Configuração de webhook |
| POST | `/api/instancias/{nome}/webhook` | Define a URL do sistema que recebe os eventos (`url`, `eventos?`) |
| POST | `/api/instancias/{nome}/numeros` | Verifica se os `numeros` têm WhatsApp |
| POST | `/api/mensagens` | Enfileira uma mensagem |
| GET | `/api/mensagens/{id}` | Status da mensagem |
| GET | `/api/mensagens` | Lista (`status`, `usuario`, `destinatario`, `instancia`, `external_id`, `por_pagina`) |

### Enviar mensagem

```bash
curl -X POST https://SEU_HOST/api/mensagens \
  -H "Authorization: Bearer evm_..." -H "Content-Type: application/json" \
  -d '{
    "usuario": "joao.silva",
    "destinatario": "(11) 98765-4321",
    "mensagem": "Olá! Seu boleto foi gerado.",
    "instancia": "vendas",
    "external_id": "boleto-123"
  }'
```

Resposta `202`:

```json
{
  "mensagem": {
    "id": "9b1d...", "instancia": "vendas", "usuario": "joao.silva",
    "destinatario": "5511987654321", "caracteres": 27, "delay_ms": 12840,
    "status": "queued", "erro": null, "external_id": "boleto-123", ...
  }
}
```

- `instancia` é obrigatória: cada instância é uma conta de WhatsApp diferente, então o middleware
  nunca escolhe o número sozinho. Sem ela retorna `422`; nome inexistente no sistema retorna `404`.
- Números com 10/11 dígitos recebem o DDI 55. JIDs (`...@g.us`) passam sem alteração.
- Status: `queued` → `sending` → `sent` → `delivered` → `read`, ou `failed` (com `erro`).
- Retorna `409` se a instância não estiver conectada.

Exemplo em PHP:

```php
$ch = curl_init('https://SEU_HOST/api/mensagens');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.TOKEN_WHATSAPP, 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'usuario' => $usuario, 'instancia' => $instancia, 'destinatario' => $telefone, 'mensagem' => $texto,
    ]),
]);
$resposta = json_decode(curl_exec($ch), true);
```

### Vincular um número

1. `POST /api/instancias` com `{"nome": "vendas", "usuario": "admin"}` → devolve `qrcode.base64`.
2. Mostre o QR na tela do sistema (`<img src="{base64}">`). Com `?formato=imagem` a rota devolve
   o PNG direto, útil para o backend do sistema repassar ao navegador — não exponha o token no HTML.
   O QR expira em alguns segundos; chame `/qrcode` de novo para renovar.
3. Acompanhe por `GET /api/instancias/vendas/status` até `open` (ou pelo webhook).

### Eventos para o sistema (webhook)

Se a instância (ou o cliente) tiver `webhook_url`, cada evento da Evolution é repassado via
`POST` com:

```json
{ "evento": "connection.update", "instancia": "vendas", "recebido_em": "...", "data": { ... } }
```

Eventos: `qrcode.updated`, `connection.update`, `messages.upsert` (mensagens recebidas),
`messages.update` (entregue/lido), `send.message`, `logout.instance`, `remove.instance`.
Use `eventos` em `POST /api/instancias/{nome}/webhook` para filtrar. Para autenticar o repasse,
inclua um segredo na própria URL (ex.: `https://sistema/webhook-whatsapp?chave=...`).

## Endpoints de administração

Header `X-Admin-Token: <MIDDLEWARE_ADMIN_TOKEN>`.

| Método | Rota | Ação |
| --- | --- | --- |
| GET | `/api/admin/clientes` | Lista os sistemas |
| POST | `/api/admin/clientes` | Cadastra (`nome`, `slug?`, `webhook_url?`) e devolve o token |
| PATCH | `/api/admin/clientes/{id}` | Altera `nome`, `webhook_url`, `ativo` |
| POST | `/api/admin/clientes/{id}/token` | Gera novo token (o anterior para de funcionar) |
| GET | `/api/admin/logs` | Auditoria (`cliente`, `acao`, `usuario`, `sucesso`, `de`, `ate`) |

Também via artisan: `cliente:criar`, `cliente:token {slug}`, `cliente:listar`.

## Anti-bot

Para cada mensagem o middleware calcula um `delay` que é enviado para a Evolution, que mantém
o "digitando..." durante esse tempo antes de enviar:

```
delay = tempo_pensando (0,8–2,5s) + caracteres × 60000 / velocidade
velocidade sorteada entre 125 cpm (pessoa lenta, ~25 palavras/min)
                     e 200 cpm (pessoa mediana, ~40 palavras/min)
limitado entre 1,5s e 45s
```

| Caracteres | Delay aproximado |
| --- | --- |
| 10 | 4–7 s |
| 50 | 16–26 s |
| 140+ | 45 s (teto) |

Depois de cada envio a instância espera mais 1–4s antes da próxima mensagem. Isso significa
que cada número envia na ordem de **70 a 150 mensagens por hora**. Ajuste com `TYPING_*`
(se aumentar `TYPING_MAX_MS` acima de ~100s, aumente também o `$timeout` do job
`SendWhatsappMessage` e o `DB_QUEUE_RETRY_AFTER`).

## Ações registradas (`action_logs.action`)

`instance.create`, `instance.qrcode`, `instance.restart`, `instance.logout`, `instance.delete`,
`instance.webhook`, `instance.check_numbers`, `instance.connected`, `instance.disconnected`,
`message.queue`, `message.send`, `message.failed`.

Tokens, hashes e apikeys são mascarados e textos longos (QR code) são truncados no log.

## Testes

Os testes de feature usam o banco MySQL `evolution_middleware_test` (credenciais do `.env`):

```bash
php artisan test
```
