Documentos-Unicos/projetos/newwhats.clube67.com/ativacao-whatsapp.md

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).

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

• 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.