VPS 4 Builder
36650397c9
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 <noreply@anthropic.com>
51 lines
2.9 KiB
Markdown
51 lines
2.9 KiB
Markdown
# 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.
|