diff --git a/Whatsapp.md b/Whatsapp.md index bf19e56..020437a 100644 --- a/Whatsapp.md +++ b/Whatsapp.md @@ -2,35 +2,28 @@ ## Visao Geral do Sistema -Este documento descreve a arquitetura de alto nivel do modulo de **WhatsApp** integrado ao ecossistema **Sothis Omnichannel**. A solucao une uma interface web moderna de atendimento, uma API NestJS robusta e o controle nativo do WhatsApp Web via automacao e WebSockets em tempo real. +O modulo WhatsApp integra o ecossistema Sothis Omnichannel com a **API oficial da Meta (Cloud API)**. A solucao une uma interface web de atendimento (React/Vite), uma API NestJS e comunicacao bidirecional via webhook (Meta → backend) e Socket.IO (backend → frontend). --- ## Diagrama de Fluxo e Integracao -O fluxo de comunicacao entre os diferentes componentes do ecossistema e estruturado conforme o diagrama a seguir: - ```mermaid graph TD - %% Componentes FE[Frontend - React/Vite] BE[Backend - NestJS] - DB[(Banco PostgreSQL)] - PERSIST[(Persistencia JSON Local)] - PUPP[Puppeteer Client - WhatsApp Web] - WPP[Servidores do WhatsApp] + DB[(PostgreSQL)] + DISK[(Disco - /uploads/media/)] + META[Meta Cloud API] + WPP[WhatsApp do Cliente] - %% Relacionamentos do Frontend - FE <-->|WebSockets: Socket.io| BE - FE -->|HTTP: Enviar Mensagem / Atribuir / Liberar| BE - - %% Relacionamentos do Backend - BE <-->|Transacoes SQL| DB - BE <-->|Leitura/Escrita Cache| PERSIST - BE <-->|Automacao de Headless Chrome| PUPP - - %% WhatsApp Web - PUPP <-->|Sincronizacao Nativa| WPP + FE <-->|Socket.IO: mensagens em tempo real| BE + FE -->|HTTP: enviar texto, midia, atribuir, liberar| BE + BE <-->|SQL| DB + BE -->|Salva arquivos de midia| DISK + DISK -->|ServeStaticModule /uploads| FE + BE <-->|Webhook + REST| META + META <-->|Mensagens| WPP ``` --- @@ -38,41 +31,64 @@ graph TD ## Divisao de Responsabilidades ### 1. Frontend (Interface Operacional) -* **Visualizacao**: Renderiza o historico de bolhas de mensagens e arquivos de midia (imagens, audios, anexos). -* **Posse de Chat (Ownership)**: Permite ao operador assumir chats livres (`takeChat`) ou libera-los (`releaseChat`), aplicando travas visuais se a conversa estiver sob a posse de outro colaborador. -* **UX Ininterrupta**: Aplica de-duplicação temporal em milissegundos e cria bolhas locais com ID temporario antes do disparo de rede para garantir experiencia livre de lag. + +- Renderiza historico de mensagens de texto e midia (imagem, audio, video, documento). +- Permite ao operador assumir, liberar, transferir e encerrar atendimentos. +- Insercao instantanea de bolhas locais (UX zero-latencia) antes do retorno da API. +- Envio de midia via `POST /whatsapp/send-media` com `multipart/form-data`. +- Preview local da midia via blob URL enquanto o upload ocorre. ### 2. Backend (Orquestracao e Integracao) -* **Automacao (whatsapp-web.js)**: Carrega o headless Chrome (via Puppeteer), autentica a sessao por QR Code, inicializa o cliente e gerencia reconexoes. -* **Transmissao em Tempo Real**: Escuta eventos de mensagem (`message_create`) do Puppeteer, formata o payload (com suporte a midias baixadas e resolucao inteligente de nomes) e distribui via Socket.io Gateway para a interface do atendente. -* **Processamento Pesado**: Aceita payloads de midia em Base64 de ate 50MB no canal de entrada para evitar falhas de upload. -### 3. Banco de Dados PostgreSQL (Persistencia Transacional) -* **Controle de Atribuicoes**: A tabela `whatsapp_chat_atribuicoes` atua como fonte unica da verdade (*Single Source of Truth*) para posse de atendimento. -* **Chaves Estrangeiras**: Vincula transacionalmente o ID do chat (`chat_id`) com chaves numericas de usuarios (`user_id`) e setores operacionais (`area_id`). +- Recebe eventos da Meta via webhook (`POST /whatsapp/webhook`). +- Ao receber midia: baixa o binario da URL temporaria da Meta, salva em disco via `MediaStorageService`, persiste no banco e emite via Socket.IO com URL publica. +- Ao enviar midia: faz upload para `/{phone_number_id}/media`, obtem `media_id` e envia a mensagem. +- Configuracao do canal (token, phone_number_id, api_version, webhook_token) gerenciada na tabela `whatsapp_config` via painel admin. -### 4. Cache JSON Local (whatsapp-chats-persist.json) -* **Performance de Listagem**: Evita multiplas consultas a servidores de rede locais ou API do WhatsApp na listagem inicial de chats operacionais. -* **Historico e previews**: Armazena carimbos de tempo (timestamps), contadores de nao lidas e previews de midia de forma otimizada. +### 3. PostgreSQL (Persistencia Transacional) + +- `whatsapp_chat_atribuicoes`: fonte da verdade para posse de atendimento. +- `mensagens`: historico de mensagens com colunas `media_path` e `media_mime_type`. +- `whatsapp_config`: configuracao do canal (singleton). +- `whatsapp_templates`: templates HSM. + +### 4. Disco Local — Storage de Midia + +- Arquivos salvos em `./uploads/media/` com nome UUID. +- Servidos publicamente em `/uploads` via `ServeStaticModule`. +- Adapter trocavel por SharePoint/S3 sem alterar o restante do codigo. --- ## Casos de Uso Principais -### A. Assumir Chat Automaticamente ao Enviar Mensagem -1. O operador envia uma mensagem em uma conversa livre. -2. O frontend verifica se o chat esta sem dono e faz um POST para `/whatsapp/assign`. -3. O backend insere na tabela `whatsapp_chat_atribuicoes` o ID do atendente e o ID numerico de sua respectiva area de trabalho. -4. A transacao e confirmada. O frontend atualiza a UI marcando o operador como dono e libera o canal de conversacao. +### A. Recebimento de midia do cliente -### B. Envio e Recebimento de Midias -1. O cliente envia uma imagem pelo WhatsApp. -2. O Puppeteer no backend detecta a mensagem com midia e baixa seus bytes em tempo real. -3. O backend emite via socket os metadados e os bytes brutos (`mimetype`, `data` em base64, `filename`). -4. O frontend identifica a presenca da midia e renderiza o player de audio, imagem ou link de download de forma nativa e estetica. +1. Cliente envia imagem/audio/video/documento pelo WhatsApp. +2. Meta entrega o evento no webhook com `media_id`. +3. Backend busca URL temporaria da Meta e baixa o binario. +4. `MediaStorageService` salva o arquivo em disco; banco registra `media_path` e `media_mime_type`. +5. Socket.IO emite para o frontend com a URL publica. +6. Frontend renderiza via `MediaRenderer` conforme o tipo. + +### B. Envio de midia pelo operador + +1. Operador seleciona arquivo no chat (clipe). +2. Preview aparece instantaneamente (blob URL local). +3. Frontend envia `POST /whatsapp/send-media` com FormData (`file`, `to`, `senderName`, `caption`). +4. Backend faz upload para a Meta, recebe `media_id`, envia mensagem. +5. Salva no banco e emite via Socket.IO com URL definitiva. + +### C. Assumir e liberar atendimento + +1. Operador assume chat livre via `POST /whatsapp/assign`. +2. Backend registra em `whatsapp_chat_atribuicoes`. +3. Frontend desbloqueia o input de mensagem. --- -## Politicas de Segurança e Versionamento -* As pastas de sessoes (`/whatsapp-session`), arquivos locais de persistencia JSON e logs de desenvolvimento estao estritamente declarados nos arquivos `.gitignore` para nao serem expostos nos repositorios Git. -* Credenciais de banco residem exclusivamente em arquivos `.env.*` mantidos fora do controle de versao. +## Politicas de Seguranca e Versionamento + +- Credenciais de banco residem em `.env.*` fora do controle de versao. +- Token e configuracao da Meta ficam no banco (`whatsapp_config`), nao em variaveis de ambiente. +- O diretorio `./uploads` e persistido via volume Docker entre rebuilds.