From 3d035678ca259a2bfcbf4fd695314df17ccfe7da Mon Sep 17 00:00:00 2001
From: Rafael Alves Lopes <rafael.lopes@sothis.com.br>
Date: Wed, 27 May 2026 16:44:28 -0300
Subject: [PATCH] Adicionar Chat Whatsapp

---
 Chat-Whatsapp.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 Chat-Whatsapp.md

diff --git a/Chat-Whatsapp.md b/Chat-Whatsapp.md
new file mode 100644
index 0000000..bcbe19d
--- /dev/null
+++ b/Chat-Whatsapp.md
@@ -0,0 +1,132 @@
+# Modulo de Chat WhatsApp (Backend)
+
+## Visao geral
+
+O modulo de WhatsApp do backend e desenvolvido em **NestJS** e utiliza a biblioteca **whatsapp-web.js** (que roda uma instancia headless do Chromium via **Puppeteer**) para integrar a aplicacao diretamente com o WhatsApp Web em tempo real.
+
+A arquitetura e constituida por quatro pilares:
+1. **Puppeteer Client**: Controla o WhatsApp Web, gera o QR Code para autenticacao e escuta eventos de novas mensagens.
+2. **WebSocket Gateway**: Transmite eventos em tempo real (novas mensagens, atualizacao de status) para o frontend usando Socket.io.
+3. **Persistencia Hibrida**: Mantem conversas indexadas localmente via JSON para performance e o status de atribuicao de atendimento gravado no banco relacional (PostgreSQL).
+4. **Servico de Atribuicao**: Gerencia o vinculo dos chats com os atendentes (`usuarios`) e suas respectivas `areas` operacionais.
+
+---
+
+## Fluxo de Eventos e Mensagens
+
+### 1. Inicializacao e Conexao
+* O backend inicia o cliente do `whatsapp-web.js` na porta configurada.
+* Se nenhuma sessao ativa for encontrada na pasta `/whatsapp-session`, o cliente gera um QR Code em formato Base64.
+* Esse QR Code e enviado via WebSocket (`qr`) para o frontend configurar o dispositivo.
+* Uma vez conectado, o status muda para `CONNECTED` e a pasta de sessao e gravada localmente.
+
+### 2. Captura de Mensagens (`message_create`)
+Utilizamos o evento global `message_create` para capturar tanto mensagens recebidas do cliente quanto mensagens enviadas pelo proprio atendente (seja pela tela ou por outro dispositivo sincronizado):
+
+```text
+Puppeteer (Message)
+  -> Trata de-duplicacao ou broadcast
+  -> Se possuir midia, baixa os buffers em tempo real
+  -> Transmite via WebSocket 'message' para o frontend
+  -> Salva ou atualiza a conversa na persistencia local JSON
+```
+
+---
+
+## Persistencia e Banco de Dados
+
+### 1. Cache Local JSON (`whatsapp-chats-persist.json`)
+Para evitar sobrecarregar o banco relacional e garantir latencias imperceptiveis de scroll, os chats e seus metadados de visualizacao sao armazenados de forma persistente em um arquivo JSON local na raiz do backend.
+
+### 2. Tabela de Atribuicao de Chat (`whatsapp_chat_atribuicoes`)
+O controle de quem esta atendendo qual chat e estritamente transacional e reside no banco PostgreSQL.
+
+A estrutura da tabela e criada pela migration `004_whatsapp.sql`:
+
+```sql
+CREATE TABLE IF NOT EXISTS whatsapp_chat_atribuicoes (
+  id SERIAL PRIMARY KEY,
+  chat_id VARCHAR(255) NOT NULL,
+  user_id SERIAL REFERENCES usuarios(id) ON DELETE CASCADE,
+  area_id SERIAL REFERENCES areas(id) ON DELETE SET NULL,
+  assigned_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE(chat_id)
+);
+```
+
+#### Regras de Atribuicao:
+* `chat_id`: Identificador unico da conversa no WhatsApp (ex: `5511999999999@c.us` ou `...@lid`).
+* `user_id`: ID inteiro (`usuarios.id`) do atendente que assumiu.
+* `area_id`: ID inteiro (`areas.id`) do setor sob o qual o atendimento esta sendo prestado (ex: `1` para Suporte).
+
+---
+
+## Endpoints do Modulo
+
+Base path: `/whatsapp`
+
+### 1. Enviar Mensagem
+```http
+POST /whatsapp/send
+Content-Type: application/json
+```
+**Payload**:
+```json
+{
+  "to": "5511999999999@c.us",
+  "message": "Ola, tudo bem?",
+  "media": {
+    "data": "base64String...",
+    "mimetype": "image/png",
+    "filename": "comprovante.png"
+  }
+}
+```
+
+### 2. Atribuir Chat
+```http
+POST /whatsapp/assign
+Content-Type: application/json
+```
+**Payload**:
+```json
+{
+  "chatId": "5511999999999@c.us",
+  "userId": 4,
+  "areaId": 1
+}
+```
+
+### 3. Liberar Chat
+```http
+DELETE /whatsapp/release/:chatId
+```
+
+---
+
+## Limitacoes e Solucoes de Bugs
+
+### 1. Payload Too Large (Upload de Midia)
+Para permitir o envio de imagens, videos e audios pesados codificados em Base64, o limite padrao de payload do NestJS foi estendido para **50MB** no `main.ts` tanto para formato JSON quanto para `urlencoded`.
+
+### 2. Nomes Numericos do WhatsApp (Smart Name Resolution)
+Devido a latencias do WhatsApp Web, as mensagens recebidas as vezes reportam apenas o telefone/JID como nome do contato. O servico de WhatsApp contem uma camada reativa de reparacao automatica:
+* Checa se o nome e puramente numerico.
+* Se for, faz uma chamada em background para o Puppeteer (`client.getContactById`) para obter o `notifyName` real do cliente e atualizar o cache local.
+
+---
+
+## Como Rodar e Testar
+
+### Requisitos locais
+* Node.js v18+
+* PostgreSQL ativo com as migrations executadas
+* Google Chrome ou Chromium instalado (o Puppeteer tentara usar o bundle local se omitido)
+
+### Executando em desenvolvimento
+```bash
+cd backend
+npm run dev
+```
+
+Os logs do NestJS no terminal indicarao as fases de inicializacao do Puppeteer, geracao de QR Code ou recuperacao de sessao ativa.