VPS 4 Builder
8d4ae73786
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>
58 lines
3.2 KiB
Markdown
58 lines
3.2 KiB
Markdown
# 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>
|