Arquitetura e Integracao do Modulo WhatsApp (Omnichannel)

Visao Geral do Sistema

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

graph TD
    FE[Frontend - React/Vite]
    BE[Backend - NestJS]
    DB[(PostgreSQL)]
    DISK[(Disco - /uploads/media/)]
    META[Meta Cloud API]
    WPP[WhatsApp do Cliente]

    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

Divisao de Responsabilidades

1. Frontend (Interface Operacional)

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)

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.

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. Recebimento de midia do cliente

Cliente envia imagem/audio/video/documento pelo WhatsApp.
Meta entrega o evento no webhook com media_id.
Backend busca URL temporaria da Meta e baixa o binario.
MediaStorageService salva o arquivo em disco; banco registra media_path e media_mime_type.
Socket.IO emite para o frontend com a URL publica.
Frontend renderiza via MediaRenderer conforme o tipo.

B. Envio de midia pelo operador

Operador seleciona arquivo no chat (clipe).
Preview aparece instantaneamente (blob URL local).
Frontend envia POST /whatsapp/send-media com FormData (file, to, senderName, caption).
Backend faz upload para a Meta, recebe media_id, envia mensagem.
Salva no banco e emite via Socket.IO com URL definitiva.

C. Assumir e liberar atendimento

Operador assume chat livre via POST /whatsapp/assign.
Backend registra em whatsapp_chat_atribuicoes.
Frontend desbloqueia o input de mensagem.

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.