From 36650397c9e7c2ad9762632bf3f815cbcc1b7a55 Mon Sep 17 00:00:00 2001 From: VPS 4 Builder Date: Sun, 28 Jun 2026 08:28:22 +0200 Subject: [PATCH] =?UTF-8?q?docs(newwhats):=20contrato=20de=20integra=C3=A7?= =?UTF-8?q?=C3=A3o=20Motor=20=E2=86=94=20Sat=C3=A9lite=20(auditoria=20+=20?= =?UTF-8?q?plano)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documenta o contrato bidirecional (ext-api A: satélite→motor; webhook + /nw/* B: motor→satélite), config, recursos do satélite (transcrição/sync-knowledge) e o estado faseado da sincronização (contrato + alias numbers feitos; config, sync-knowledge e2e e mover-recursos pendentes). Co-Authored-By: Claude Opus 4.8 --- .../integracao-satelites.md | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 projetos/newwhats.clube67.com/integracao-satelites.md diff --git a/projetos/newwhats.clube67.com/integracao-satelites.md b/projetos/newwhats.clube67.com/integracao-satelites.md new file mode 100644 index 0000000..0e28c5d --- /dev/null +++ b/projetos/newwhats.clube67.com/integracao-satelites.md @@ -0,0 +1,50 @@ +# newwhats.clube67.com — Contrato de integração Motor ↔ Satélite + +> O **motor** (newwhats) expõe a plataforma WhatsApp + Secretária IA; cada +> **satélite** (ex.: mercado.clube67.com / "Alemão Conveniências", plugin +> `newwhats` v2.1.0) consome o motor e fornece dados do seu negócio. +> Fonte da verdade do contrato (auditado em 28/jun/2026). + +## Config do satélite (plugin_configs, manifest `newwhats`) +`newwhats_url` (URL do motor) · `integration_key` (x-nw-key, rotas `/nw/*`) · +`api_token` (Bearer, envio de mensagens) · `webhook_secret` (HMAC do webhook). + +## Contrato A — Satélite → Motor (ext-api `/api/ext/v1/*`) +| Satélite chama | Motor (ext-api) | Status | +|---|---|---| +| `inbox`, `inbox/:chatId/messages`, `inbox/:chatId/send` | idem | ✅ | +| `media/:messageId` | `media/:messageId` | ✅ | +| `stream` (WS) | `stream` | ✅ | +| `secretaria/ask` | `secretaria/ask` (routes.ts) | ✅ | +| `secretaria/numbers` | **alias adicionado** → `sec_numbers` | ✅ (corrigido) | +| `secretaria/*` interno (`sync-knowledge`) | `/api/secretaria/*` (plugin) | ✅ | + +> Demais dados da Secretária no ext-api ficam sob `/sec/*` (`sec/agent`, +> `sec/nodes`, `sec/slots`, `sec/conversations`, `sec/keys`, `sec/handoff`). + +## Contrato B — Motor → Satélite +| Mecanismo | Satélite | Auth | +|---|---|---| +| Webhook `POST /api/webhook/newwhats` (`message.new`, `session.status`) | `webhook-receiver.js` | HMAC `webhook_secret` | +| Secretária consulta `/nw/*` (`/cliente`, `/clube`, `/parceiros`, `/promocoes`, `/sorteio`, `/vagas`, `/ping`) | `routes.js` | `integration_key` (timingSafeEqual) | + +## O que o satélite já faz (e poderia migrar ao motor) +- `media-transcribe.js`: transcrição de áudio + descrição de imagem via Gemini + (cache Redis, fallback Whisper). **Hoje só no satélite** → candidato a ir ao motor. +- `sync-knowledge.js`: monta o nó de conhecimento com dados reais e envia ao motor. +- `smart-router.js` (roteamento sem LLM), `personas.js`, `follow-up-detector.js`, + `context-builder.js` (contexto local do negócio). + +## Estado da sincronização (faseado) +1. ✅ **Contrato documentado** (este arquivo). +2. ✅ **Compatibilidade de API**: alias `GET /secretaria/numbers` no ext-api do + motor (retrocompatível) — fecha o gap do `webhook-receiver`. (commit motor) +3. ⏳ **Config/conexão**: validar `newwhats_url`/keys do satélite apontando para o + motor correto (dev/prod) e o HMAC do webhook. *(requer credenciais reais.)* +4. ⏳ **Conhecimento**: rodar `sync-knowledge` end-to-end (satélite → motor). +5. ⏳ **Mover recursos**: transcrição/memória para o motor (genéricos a todos os + satélites); satélite passa a só enviar contexto. Ver `secretaria-ia-evolucao.md`. + +## Inconsistência anotada +A transcrição no satélite usa `process.env.GEMINI_API_KEY`; o RAG/memória do motor +usa `cfg.gemini_key` (config do plugin). Unificar a fonte da chave ao migrar.