VPS 4 Builder
149 lines
5.1 KiB
Markdown
149 lines
5.1 KiB
Markdown
# 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`
|