# 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`