From 8d4ae73786d381dfa8e6399879f757ff2f1489f9 Mon Sep 17 00:00:00 2001
From: VPS 4 Builder <deploy@clube67.com>
Date: Sun, 28 Jun 2026 14:44:05 +0200
Subject: [PATCH] =?UTF-8?q?docs(plugin=20newwhats):=20integra=C3=A7=C3=A3o?=
 =?UTF-8?q?=20com=20o=20motor=20+=20regra=20de=20registro=20bidirecional?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Plugin único deste projeto. Documenta config, mapa de arquivos↔motor, contrato
resumido e pendências (fases 3-5, ativação inteligente). Espelha o contrato
central em documentos-unicos/projetos/newwhats.clube67.com.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 backend/plugins/newwhats/INTEGRACAO-MOTOR.md | 57 ++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 backend/plugins/newwhats/INTEGRACAO-MOTOR.md

diff --git a/backend/plugins/newwhats/INTEGRACAO-MOTOR.md b/backend/plugins/newwhats/INTEGRACAO-MOTOR.md
new file mode 100644
index 0000000..3c15b73
--- /dev/null
+++ b/backend/plugins/newwhats/INTEGRACAO-MOTOR.md
@@ -0,0 +1,57 @@
+# Plugin `newwhats` (mercado.clube67.com) ↔ Motor NewWhats
+
+> **Este plugin é ÚNICO deste projeto** (`mercado.clube67.com` / "Alemão
+> Conveniências"). Outro projeto tem o seu próprio `newwhats`, possivelmente
+> divergente. Não copie cego entre projetos. v2.1.0 — rev. 28/jun/2026.
+
+## ⚠️ Regra de registro bidirecional (obrigatória)
+- **Toda mudança neste plugin** que toque o contrato (rotas, payloads, auth,
+  webhook, dados enviados) **deve ser registrada no motor** e na doc central
+  `documentos-unicos/projetos/newwhats.clube67.com/integracao-satelites.md`.
+- **Toda mudança no motor** que afete o contrato **deve ser refletida aqui**
+  (este arquivo) e validada contra este plugin.
+- O plugin é um **braço inteligente do motor**: consome, alimenta e configura o
+  motor — **não duplica** lógica que pertence ao motor.
+
+## Configuração (plugin_configs, manifest `newwhats`)
+| Chave | Uso |
+|---|---|
+| `newwhats_url` | URL do motor (ex.: `http://newwhats.local:8008`) |
+| `integration_key` | `x-nw-key` — rotas `/nw/*` e proxy REST/WS (timingSafeEqual) |
+| `api_token` | Bearer — envio de mensagens ao motor |
+| `webhook_secret` | HMAC `x-nw-signature` — valida webhooks recebidos do motor |
+
+## Arquivos deste plugin e o que falam com o motor
+| Arquivo | Papel | Lado do motor |
+|---|---|---|
+| `index.js` | registro/boot do plugin | — |
+| `auth.js` | valida `integration_key` / token | pair/api-keys |
+| `proxy.js` | proxy REST + WS autenticado p/ inbox | ext-api `/api/ext/v1/*`, `stream` |
+| `routes.js` | expõe `/nw/*` (cliente, clube, parceiros, promoções, sorteio, vagas, ping) | Secretária consulta via `integration_key` |
+| `webhook-receiver.js` | recebe `message.new` / `session.status` (HMAC) | motor → satélite |
+| `sync-knowledge.js` | monta e envia nó de conhecimento (RAG) | `/api/secretaria/*` (sync-knowledge) |
+| `context-builder.js` | contexto local do negócio p/ Secretária | alimenta `secretaria/ask` |
+| `smart-router.js` | roteamento sem LLM | local |
+| `personas.js` | personas do atendimento | local |
+| `follow-up-detector.js` | detecção de follow-up | local |
+| `media-transcribe.js` | **REDUNDANTE** — transcrição já existe no motor (`messages.transcription`) | ⏳ remover (Fase 5) |
+
+## Contrato resumido (detalhes na doc central)
+- **Satélite → Motor** (ext-api): `inbox`, `inbox/:chatId/messages`,
+  `inbox/:chatId/send`, `media/:messageId`, `stream` (WS), `secretaria/ask`,
+  `secretaria/numbers` (alias), `secretaria/*` interno (`sync-knowledge`).
+- **Motor → Satélite**: webhook `POST /api/webhook/newwhats` (HMAC) e a Secretária
+  consultando `/nw/*` (`integration_key`).
+
+## Pendências que tocam este plugin
+- **Fase 3** — validar `newwhats_url`/keys (dev/prod) + HMAC do webhook.
+- **Fase 4** — `sync-knowledge` end-to-end.
+- **Fase 5** — consumir `messages.transcription` do motor e **remover
+  `media-transcribe.js`**; unificar fonte da chave Gemini.
+- **Ativação inteligente** — este plugin deve orquestrar o trajeto de
+  provisionamento (ver `ativacao-whatsapp.md` na doc central).
+
+> Fonte da verdade do contrato e checklist:
+> `documentos-unicos/projetos/newwhats.clube67.com/` →
+> `integracao-satelites.md`, `tarefas.md`, `wasabi-midias.md`, `ativacao-whatsapp.md`.
+</content>