# newwhats.clube67.com — Ativação do WhatsApp (trajeto inteligente)

> Estado atual + desenho do "trajeto" desejado. Meta: cada ativação de um WhatsApp
> **cria e configura uma conta no motor de forma inteligente**, com o plugin
> satélite atuando como **braço inteligente do motor**. Última revisão: 28/jun/2026.

## Como funciona hoje (mínimo)
1. `POST /api/instances/` `{ name }` → cria a instância (`repo.create(tenantId, name)`).
2. `POST /api/instances/:id/connect` → `manager.connect` emite **QR via Socket.IO**.
3. `GET /api/instances/:id/qr` → QR em base64 (Dragonfly `instance:{id}:qr`).
4. Pareamento de plugin (separado): `PairService` (OTP por email → `PluginPair`
   com `integration_key`), valida o satélite via `verify(integration_key)`.

**Limitação:** a instância nasce "crua" (só `name`). Setor, secretária, webhook,
engine e detecção Business são passos manuais/dispersos.

## Trajeto desejado (provisionamento guiado e idempotente)
Ao ativar um WhatsApp, o motor (orquestrado pelo satélite) deve executar, em ordem
e **idempotente** (re-rodar não duplica):

1. **Conta/tenant** — garantir tenant + `PluginPair` (se ativação vem de satélite,
   usa `integration_key`; senão cria pelo admin).
2. **Instância** — criar com `name`, `engine` default (baileys7 = "API estável") e
   flags (`isBusiness` será detectada no connect).
3. **Conexão** — `connect` → QR; ao conectar, **detectar Conta Business** e gravar
   `isBusiness`; avisar que trocar de API exige re-escanear QR.
4. **Setor + Secretária default** — criar setor padrão e um agente de Secretária
   base (persona/regras mínimas) já ligado à instância.
5. **Webhook** — registrar o webhook do satélite (`webhook_secret`/HMAC) p/
   `message.new` e `session.status`.
6. **Conhecimento inicial** — disparar `sync-knowledge` do satélite (Fase 4) para o
   RAG nascer populado.
7. **Resumo** — devolver ao operador o estado final (conectado, Business?, setor,
   secretária, webhook ok) — "trajeto" visível, não caixa-preta.

## Papel do satélite (braço inteligente)
- O satélite **não duplica** o motor: ele dispara o trajeto, fornece dados do
  negócio (`/nw/*`, `sync-knowledge`) e consome inbox/secretária via proxy.
- Toda configuração persiste **no motor** (fonte da verdade). O satélite guarda só
  as chaves de conexão (`plugin_configs`).
- Qualquer passo novo do trajeto deve ser refletido nos dois lados (ver regra de
  registro bidirecional em [integracao-satelites.md](integracao-satelites.md)).

## Implementado (28/jun/2026)
`POST /api/instances/provision` (auth, escopo tenant). Body:
`{ name, engine?, webhookUrl?, sector?, connect? }`. **Idempotente** (re-rodar não
duplica). Devolve `{ instance, trajeto[] }` com cada passo visível:
- `instancia` (criada/existente) — upsert por unique `[tenantId, name]`.
- `engine` (definida/mantida) — **`baileys7` (API estável) por padrão** ao criar.
- `setor` (criado/existente) — `ensureSector`, default "Atendimento".
- `webhook` (configurado/inalterado/omitido).
- `conexao` (iniciada/pulada) — se `connect:true`, emite QR via Socket.IO.
- `business` (pendente) — detectada ao conectar.
- `secretaria` / `conhecimento` (pendentes) — passos de plugin/satélite.

> Validado em dev: 1ª chamada → 201 (cria, engine baileys7, setor); 2ª → 200
> ("existente", sem duplicar). Artefatos de teste removidos.

## Pendência restante
- [x] **Detecção Business no `connect`** (28/jun/2026) — no evento `open`,
      `getBusinessProfile(selfJid)` (fire-and-forget) define `Instance.isBusiness`
      (true se o perfil tiver descrição/categoria/horário/etc.) e emite
      `instance:business`. SettingsPanel já exibe. _Verificação ao vivo no próximo
      connect real (logs `[Business] detecção concluída`)._
- [ ] Secretária default automática (via plugin `secretaria`).
- [ ] Registro de webhook automatizado a partir do pair (preencher `webhookUrl`).
- [ ] Gatilho de `sync-knowledge` no fim do trajeto (satélite).
- [ ] UI de onboarding consumindo `/provision` + exibindo o trajeto.
</content>