mercado.clube67.com/docs/plugin-inbox.md

Plugin Inbox — NewWhats como Motor Central

Data: 2026-04-16
Status: Conversa de alinhamento arquitetural — nenhum código escrito ainda

---

Contexto do Projeto

• Motor: /home/deploy/projetos/newwhats.local — Baileys, inbox, sessões, storage Wasabi, sistema de plugins, pair API com integration_key
• Satélites: múltiplos projetos em /home/deploy/projetos/ que consomem o motor via API (ex: Alemão Conveniências em /home/deploy/projetos/alemaoconveniencias.local)
• Já implementado: pair system (OTP e-mail), plugin newwhats no Alemão com x-nw-key auth, modal pareamento 3 passos
• Serviços: newwhats-backend.service (8008), alemaoconveniencias.service (4001)

---

Objetivo

Transformar o NewWhats em motor SaaS multi-tenant. Os satélites não instalam Baileys — consomem inbox, sessões, QR code e secretária virtual via API autenticada por integration_key.

Requisitos críticos:

• Não perde mensagem
• Não trava, não bloqueia
• Gera e replica QR code em tempo real
• Replica fielmente o comportamento do NewWhats
• Acessível via botão no sidebar de cada projeto satélite

---

Decisão Arquitetural Principal

Duas camadas obrigatórias:

┌─────────────────────────────────┐
│  IFRAME                         │  ← visualização / operação humana
│  (inbox, QR, sessions)          │     motor serve a UI completa
└─────────────────────────────────┘
         +
┌─────────────────────────────────┐
│  API + WEBHOOK                  │  ← integração de código
│  satélite age e reage a eventos │
└─────────────────────────────────┘

Por que iframe para a UI:

O motor expõe uma página autenticada:

https://newwhats.local/embed?key=<integration_key>&session=X

O plugin nw-client no satélite faz apenas:

1. Adiciona botão no sidebar
2. Abre painel lateral deslizante (slide-over) com <iframe> apontando para o motor

Vantagens:

• UI mantida em 1 lugar — correção de bug aplica a todos os satélites
• QR Code realtime nativo
• Mídia já autenticada
• Zero manutenção de UI no satélite

Por que API + Webhook também é obrigatório:

O iframe sozinho não resolve:

Necessidade	Problema com iframe
"msg recebida → marcar pedido como contactado"	impossível sem webhook
"botão Enviar WA na tela do pedido"	precisa de API call direto
"mostrar nome do cliente no chat"	iframe não acessa banco do satélite
Automações cruzadas	iframe não tem como reagir a eventos

Regra: iframe = 80% do uso humano. API+webhook = 100% das integrações de negócio.

---

Estrutura do Plugin nw-client (satélite)

/plugins/newwhats-client/
  manifest.json
  hooks/sidebar.php       ← injeta o botão no sidebar
  hooks/assets.php        ← carrega o JS do painel
  panel.js                ← abre o iframe autenticado
  config_schema.json      ← motor_url + integration_key

---

Estrutura dos Plugins no Motor

/plugins/ext-api/           ← expõe /api/ext/v1/*
/plugins/secretaria-virtual/ ← IA com contexto (roda 100% no motor)
/plugins/realtime-bridge/   ← WebSocket / SSE

---

API /api/ext/v1/* (a criar no motor)

• GET /api/ext/v1/sessions
• GET /api/ext/v1/inbox?session=X
• GET /api/ext/v1/inbox/:chatId/messages
• POST /api/ext/v1/inbox/:chatId/send
• POST /api/ext/v1/secretaria/ask
• WS /api/ext/v1/stream (eventos realtime)

Auth: header x-nw-key: <integration_key>

---

Decisões Técnicas a Tomar

Ponto	V1	V2
Eventos realtime	Polling 5s	WebSocket / SSE
Mídia	URL assinada Wasabi (TTL curto)	Proxy via motor
QR Code	SSE obrigatório desde V1	—
Fila de eventos	Bull + Redis	—

Nota QR Code: polling de 5s pode perder a janela do QR (muda a cada ~20s e expira). SSE ou WebSocket é quase obrigatório desde V1 para QR.

---

Pendências Herdadas

• aria-hidden warning no pairModal (Bootstrap 5 — usar inert ou Bootstrap 5.3+)
• SMTP não configurado no NewWhats (dev_code exposto na resposta da pair API)

---

Próximos Passos (a definir na próxima sessão)

1. Gerar TAREFAS.md com backlog fase-a-fase (motor → SDK → satélite → secretária)
2. Gerar RELATORIO.md com análise profissional, riscos e decisões arquiteturais
3. Esqueleto dos plugins (manifests + hooks declarados, sem lógica)
4. Decidir: (A) contrato detalhado da API primeiro, ou (B) PoC end-to-end de /api/ext/v1/inbox no Alemão para validar o fluxo

---

Referências Rápidas

• Sistema de plugins: backend/src/core/ (types, hook-bus, plugin-loader, plugin-registry)
• Pair system: backend/src/modules/pair/pair.routes.ts + pair.service.ts
• Plugin consumidor existente: /home/deploy/projetos/alemaoconveniencias.local/sistema-nuvem/plugins/newwhats/
• Build backend: npm run build em /home/deploy/projetos/newwhats.local/backend