Arquitetura e Integracao do Modulo WhatsApp (Omnichannel)

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.

Diagrama de Fluxo e Integracao

O fluxo de comunicacao entre os diferentes componentes do ecossistema e estruturado conforme o diagrama a seguir:

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]

    %% 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

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.

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).

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.

Casos de Uso Principais

A. Assumir Chat Automaticamente ao Enviar Mensagem

O operador envia uma mensagem em uma conversa livre.
O frontend verifica se o chat esta sem dono e faz um POST para /whatsapp/assign.
O backend insere na tabela whatsapp_chat_atribuicoes o ID do atendente e o ID numerico de sua respectiva area de trabalho.
A transacao e confirmada. O frontend atualiza a UI marcando o operador como dono e libera o canal de conversacao.

B. Envio e Recebimento de Midias

O cliente envia uma imagem pelo WhatsApp.
O Puppeteer no backend detecta a mensagem com midia e baixa seus bytes em tempo real.
O backend emite via socket os metadados e os bytes brutos (mimetype, data em base64, filename).
O frontend identifica a presenca da midia e renderiza o player de audio, imagem ou link de download de forma nativa e estetica.

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.