# Continuar — NewWhats como Motor Central (SaaS multi-tenant)

## Instrução inicial para a próxima sessão

> Faça uma **análise profissional** da ideia descrita abaixo. Antes de escrever qualquer código:
> 1. Gere uma **lista de tarefas detalhada** (fases, dependências, critérios de aceite) e salve em `TAREFAS.md`.
> 2. Mantenha um **relatório vivo** de todas as implementações em `RELATORIO.md` (o que foi feito, decisões técnicas, pontos de atenção, próximos passos).
> 3. **Regra-ouro:** toda funcionalidade nova deve ser pensada e entregue **como plugin** (em `/plugins/<nome>/` com `manifest.json`, hooks, config_schema). Nada vai direto ao core se couber como plugin.

---

## Contexto do projeto

- **Projeto motor:** `/home/deploy/projetos/newwhats.local` — já possui Baileys (WhatsApp), inbox, sessões, storage (Wasabi), sistema de plugins estilo WordPress, e API de pareamento OTP (`/api/pair/*`) com `integration_key`.
- **Projetos satélites:** múltiplos sistemas (ex.: Alemão Conveniências em `/home/deploy/projetos/alemaoconveniencias.local`) que **não devem instalar Baileys**. Devem consumir o motor via API autenticada por `integration_key`.
- **Já implementado:** pair system (OTP por e-mail), plugin `newwhats` no Alemão com `x-nw-key` auth, modal de pareamento em 3 passos no dashboard.
- **Falta:** expor inbox, sessões e secretária virtual como serviço consumível pelos satélites.

## Ideia a analisar

Transformar o NewWhats em **motor SaaS multi-tenant**, onde cada projeto satélite é um cliente leve que consome:
- **Inbox** (chats, mensagens, envio, mídias)
- **Sessões** (status WA, QR, pareamento de números)
- **Secretária virtual** (IA com contexto — roda 100% no motor, satélite só consome output)

## Arquitetura-alvo

```
NewWhats (motor)
 ├─ Baileys + Inbox + Storage + Secretária (IA)
 └─ API /api/ext/*  (auth: x-nw-key)
           │
           ▼ HTTPS + WebSocket
   ┌───────┴────────┬──────────┐
   Alemão        Projeto B    Projeto C
   (plugin       (plugin      (plugin
   nw-client)    nw-client)   nw-client)
```

## Decisões propostas (validar antes de implementar)

1. **Plugin `nw-client` portável** em `/plugins-sdk/newwhats-client/` — reutilizável em todos os satélites, zero dependência de Baileys.
2. **API `/api/ext/*` nova** (além de `/api/pair/*` já existente), autenticada por `x-nw-key`:
   - `GET /api/ext/sessions`
   - `GET /api/ext/inbox?session=X`
   - `GET /api/ext/inbox/:chatId/messages`
   - `POST /api/ext/inbox/:chatId/send`
   - `POST /api/ext/secretaria/ask`
   - `WS /api/ext/stream` (eventos realtime — fallback polling 5s)
3. **Secretária virtual sempre no motor** — centraliza custo LLM e contexto.
4. **Isolamento multi-tenant** — `integration_key` resolve para `user_id` + `allowed_sessions[]`. Satélite nunca vê dados de outro tenant.
5. **Distribuição do client plugin** — opções:
   - (a) `npm publish @newwhats/client` (registry privado/público)
   - (b) git submodule
   - (c) **CLI `nw plugin install`** que baixa tarball assinado do motor ← recomendado
6. **Tudo como plugin:**
   - Motor: `plugins/ext-api/` (expõe `/api/ext/*`), `plugins/secretaria-virtual/` (IA), `plugins/realtime-bridge/` (WS).
   - Satélite: `plugins/newwhats-client/` (consumidor único, com UI de inbox embutida).

## Tradeoffs a documentar no relatório

- **WS vs polling** — WS é melhor para UX, mas adiciona complexidade de reconexão/auth. V1 polling 5s, V2 WS.
- **Proxy de mídias** — satélite baixa mídia via motor (`/api/ext/media/:id`) ou recebe URL assinada Wasabi? URL assinada é mais leve mas expõe storage.
- **Rate limit por integration_key** — necessário desde o v1 para proteger motor.
- **Versionamento da API** — `/api/ext/v1/*` desde o início.

## Pendências herdadas (do `project_alemao_plugin_session.md`)

- `aria-hidden` warning no pairModal (Bootstrap 5 — usar `inert` ou Bootstrap 5.3+).
- Inbox no Alemão via plugin — **esta é a primeira entrega desta nova fase**.
- SMTP não configurado no NewWhats — dev_code exposto na resposta até configurar.

## Entregáveis esperados da próxima sessão

1. `TAREFAS.md` — backlog fase-a-fase (motor → SDK → satélite → secretária).
2. `RELATORIO.md` — iniciado com análise profissional da ideia, riscos, e decisões arquiteturais.
3. Esqueleto dos plugins (manifests + hooks declarados, sem lógica ainda) para validar a forma antes de implementar.
4. Pergunta ao usuário: **(A)** contrato detalhado da API primeiro, ou **(B)** PoC end-to-end de `/api/ext/inbox` no Alemão para validar 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`
- Serviços: `newwhats-backend.service` (8008), `alemaoconveniencias.service` (4001)