VPS 4 Builder
353 lines
13 KiB
Markdown
353 lines
13 KiB
Markdown
# NewWhats v2.2 — Plano Real (pós-análise do cérebro)
|
||
|
||
> Documento gerado em 2026-04-18 após análise completa do motor, satélite, proxy e ProtocolEngine.
|
||
> Base: código real de `newwhats.local` + `alemaoconveniencias.local/sistema-nuvem/plugins/newwhats/`.
|
||
|
||
---
|
||
|
||
## 1. Estado atual — O que já existe (v2.1)
|
||
|
||
### Motor (`newwhats.local:8008`)
|
||
| Componente | Rota interna | Status |
|
||
|---|---|---|
|
||
| Agents CRUD | `GET/POST/PUT/DELETE /api/secretaria/agents` | ✅ operacional |
|
||
| Brain Nodes | `GET/POST/PUT/DELETE /api/secretaria/nodes` | ✅ operacional |
|
||
| Conversations | `GET/POST/PATCH /api/secretaria/conversations` | ✅ operacional |
|
||
| Chat (brain) | `POST /api/secretaria/conversations/:id/chat` | ✅ operacional |
|
||
| Finalizar protocolo | `POST /api/secretaria/conversations/:id/finalize` | ✅ operacional |
|
||
| Calendar | `GET/POST /api/secretaria/calendar` | ✅ operacional |
|
||
| sec_numbers | `GET/POST/PUT/DELETE /api/secretaria/numbers` | ✅ tabela + rotas ok |
|
||
| WebSocket stream | `UPGRADE /api/ext/v1/stream` | ✅ operacional |
|
||
| Sessions QR | `GET /api/ext/v1/sessions/:id/qr` | ✅ operacional |
|
||
|
||
### ProtocolEngine (cérebro) — arquitetura real
|
||
```
|
||
Sistema prompt = persona + knowledge + rules + calendar + escalation
|
||
(nós ativos, ordenados por sort_order)
|
||
|
||
Economia de tokens:
|
||
context_window = 8 → carrega apenas últimas 8 mensagens
|
||
summarize a cada 10 trocas → atualiza conversation.summary
|
||
system prompt nunca cresce — sempre reconstruído do zero
|
||
|
||
Fallback chain de providers:
|
||
1. openai (gpt-4o-mini) — se openai_key configurado
|
||
2. gemini (gemini-2.0-flash) — se gemini_key configurado
|
||
3. anthropic (claude-3-5-haiku) — se anthropic_key configurado
|
||
4. ollama (llama3) — sempre disponível (local)
|
||
|
||
Persona pode override o model via node_model (por nó)
|
||
```
|
||
|
||
### Satélite (`sistema-nuvem`) — o que existe hoje
|
||
```
|
||
/api/nw/v1/* → proxy REST para /api/ext/v1/* ✅
|
||
/api/nw/v1/stream → proxy WS ✅
|
||
/api/webhook/newwhats → webhook-receiver.js ✅ (só loga)
|
||
/api/admin/nw/sync-knowledge → syncKnowledge() ✅ (corrigido)
|
||
/api/admin/nw/sync-knowledge/preview → buildKnowledgeText() ✅
|
||
|
||
Rotas Alemão expostas ao motor (/nw/*):
|
||
GET /nw/cliente?telefone= → user + tickets + clubes + candidaturas ✅
|
||
GET /nw/clube?cpf= → memberships + dependentes + parceiros ✅
|
||
GET /nw/candidaturas?cpf= → candidaturas com status PT ✅
|
||
GET /nw/parceiros?clube=slug → parceiros de um clube ✅
|
||
GET /nw/vagas → vagas abertas formatadas ✅
|
||
GET /nw/sorteio → sorteio ativo + contagem ✅
|
||
GET /nw/sorteio/tickets?tel= → tickets do cliente ✅
|
||
GET /nw/promocoes → promoções ativas ✅
|
||
```
|
||
|
||
### Knowledge Node — situação atual
|
||
```
|
||
Agente: Ana — Atendente Virtual
|
||
Node ID: ed968e6c-a031-44d2-8f5b-1ab4e6f55075
|
||
Chars: 1895
|
||
Última sync: 2026-04-18T23:28:46Z
|
||
|
||
Conteúdo real (dados do banco):
|
||
- Clube Odonto (planos + parceiros)
|
||
- Clube Médico (planos + parceiros)
|
||
- Sorteio ativo (preço + disponíveis)
|
||
- Promoções ativas
|
||
- Vagas abertas
|
||
- Atendimento geral
|
||
```
|
||
|
||
### O que NÃO existe ainda
|
||
- ❌ Auto-resposta (webhook só loga, nunca envia)
|
||
- ❌ Lookup automático de dados do cliente ao receber mensagem
|
||
- ❌ UI de gerenciamento de números no admin (Frente 1 em progresso)
|
||
- ❌ Botão "Sincronizar Knowledge" no painel
|
||
- ❌ Escalação para humano com notificação
|
||
- ❌ Métricas de atendimento IA
|
||
- ❌ Modo semi-auto (IA sugere, humano confirma)
|
||
|
||
---
|
||
|
||
## 2. Frentes v2.2
|
||
|
||
### Frente 1 — Gerenciamento de Números no Admin UI
|
||
**Onde:** `admin-app/src/pages/WhatsAppInbox.tsx`
|
||
|
||
**O que fazer:**
|
||
- [x] Constantes ROLE_LABELS, ROLE_COLORS, PRIORITY_LABELS
|
||
- [x] Componente `NumberBadge` (role + prioridade visual)
|
||
- [x] Modal `AddNumberModal` — 2 etapas:
|
||
- Step 1: preenche label, role, área, prioridade, notas
|
||
- Step 2: chama `NwService.createSession(label)` → `NwService.saveNumber(...)` → poll QR a cada 2s
|
||
- [x] Modal `EditNumberModal` — edita metadados + toggle ativo/inativo
|
||
- [ ] Estado + `fetchNumbers()` no componente principal
|
||
- [ ] Botão "+ Novo Número" no header da aba Sessões
|
||
- [ ] Session cards: badges de categoria/prioridade (cruzar sessions × numbers por instance_id)
|
||
- [ ] Ações por sessão: botão Editar (abre EditModal) + Excluir (confirm → deleteSession + deleteNumber)
|
||
|
||
**Fluxo de dados:**
|
||
```
|
||
NwService.getNumbers() → /api/nw/v1/secretaria/numbers
|
||
→ proxy → /api/ext/v1/secretaria/numbers
|
||
→ motor → SELECT sec_numbers ORDER BY priority, label
|
||
|
||
Cruzamento visual: session.id === number.instance_id
|
||
```
|
||
|
||
**Lógica de fallback (display):**
|
||
```
|
||
Ao mostrar sessões ordená-las por: priority ASC (números sem metadado = priority 99)
|
||
Badge role: azul=notificacoes | laranja=entregas | roxo=suporte | rosa=marketing | cinza=geral
|
||
Badge prioridade: verde=Principal | amarelo=Fallback | cinza=Terciário+
|
||
```
|
||
|
||
---
|
||
|
||
### Frente 2 — Auto-resposta Inteligente
|
||
**Onde:** `sistema-nuvem/plugins/newwhats/webhook-receiver.js`
|
||
**Depende de:** Frente 1 concluída (sec_numbers deve ter roles configurados)
|
||
|
||
**Princípio de funcionamento:**
|
||
```
|
||
Motor dispara webhook → POST /api/webhook/newwhats
|
||
evento: message.new, fromMe: false
|
||
|
||
Satélite:
|
||
1. Verifica HMAC (já existe)
|
||
2. Lookup sec_numbers pelo instanceId → obtém role
|
||
3. Se role == 'notificacoes' → NUNCA responder (só logar)
|
||
4. Se role == 'suporte' | 'geral' | 'marketing' | 'entregas':
|
||
a. Lookup ou cria conversa no motor: POST /api/secretaria/conversations
|
||
b. Chama brain: POST /api/secretaria/conversations/:id/chat { message }
|
||
c. Envia resposta: POST /api/ext/v1/inbox/:chatId/send { text: reply }
|
||
d. Atualiza nw_event_logs com status='replied'
|
||
```
|
||
|
||
**Modos de operação (configurável por plugin_config):**
|
||
```
|
||
auto_reply_mode:
|
||
off → nunca responde (comportamento atual)
|
||
assistido → IA sugere na inbox, humano confirma antes de enviar
|
||
automatico → IA responde direto, sem intervenção humana
|
||
```
|
||
|
||
**Throttle / anti-loop:**
|
||
```
|
||
- Nunca responder se fromMe = true
|
||
- Cooldown: não responder ao mesmo chatId por 30s após última resposta automática
|
||
- Máximo: 5 respostas automáticas por conversa antes de escalar
|
||
- Horário: respeitar horário de atendimento (plugin_config: auto_reply_hours)
|
||
```
|
||
|
||
**Tabela nova: `nw_auto_replies`**
|
||
```sql
|
||
CREATE TABLE nw_auto_replies (
|
||
id SERIAL PRIMARY KEY,
|
||
instance_id VARCHAR(128) NOT NULL,
|
||
chat_id VARCHAR(128) NOT NULL,
|
||
conv_id UUID, -- sec_conversations.id no motor
|
||
reply TEXT,
|
||
status VARCHAR(20) DEFAULT 'sent',-- sent | failed | pending_confirm
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### Frente 3 — Botão "Sincronizar Knowledge" no Painel
|
||
**Onde:** `admin-app/src/pages/WhatsAppInbox.tsx` (aba Sessões) + `admin-app/src/services/api.ts`
|
||
|
||
**O que fazer:**
|
||
```typescript
|
||
// api.ts — adicionar ao NwService:
|
||
syncKnowledge: () =>
|
||
api.post('/admin/nw/sync-knowledge').then(r => r.data),
|
||
previewKnowledge: () =>
|
||
api.get('/admin/nw/sync-knowledge/preview').then(r => r.data),
|
||
```
|
||
|
||
**UI:**
|
||
- Botão `Sincronizar IA` com ícone `Brain/Zap` no header da aba Sessões (ao lado do `+Novo Número`)
|
||
- Estado: idle → syncing (spinner) → ok (checkmark verde 2s) → idle
|
||
- Toast: "✅ Base sincronizada — 1895 chars — Ana atualizada"
|
||
- Botão `Preview` (expandable) mostra o texto que será enviado ao motor
|
||
|
||
**Quando disparar automaticamente (futuro):**
|
||
Webhook interno: quando admin salva promoção, clube, vaga → dispara `syncKnowledge()` em background.
|
||
|
||
---
|
||
|
||
### Frente 4 — Escalação para Humano
|
||
**Onde:** `webhook-receiver.js` + novo endpoint no admin
|
||
|
||
**Gatilhos de escalação (detectados pelo brain):**
|
||
- Palavra-chave na resposta da IA: `[ESCALAR]`, `[HUMANO]`, `transferir para atendente`
|
||
- Mais de 5 trocas sem resolução (contador na conversa)
|
||
- Cliente digita: "falar com atendente", "humano", "responsável"
|
||
|
||
**Fluxo:**
|
||
```
|
||
Brain retorna resposta com [ESCALAR] → satélite detecta
|
||
→ marca conversa: status='escalated'
|
||
→ INSERT nw_escalations (chat_id, conv_id, reason, created_at)
|
||
→ badge vermelho na inbox do admin (unread count especial)
|
||
→ IA para de responder automaticamente para esse chatId
|
||
→ Humano assume via inbox normal
|
||
```
|
||
|
||
**Tabela nova: `nw_escalations`**
|
||
```sql
|
||
CREATE TABLE nw_escalations (
|
||
id SERIAL PRIMARY KEY,
|
||
instance_id VARCHAR(128) NOT NULL,
|
||
chat_id VARCHAR(128) NOT NULL,
|
||
conv_id UUID,
|
||
reason TEXT,
|
||
resolved BOOLEAN DEFAULT FALSE,
|
||
resolved_by VARCHAR(128),
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
resolved_at TIMESTAMPTZ
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
### Frente 5 — Métricas de Atendimento IA
|
||
**Onde:** `sistema-nuvem/server.js` + novo card no Dashboard admin
|
||
|
||
**KPIs:**
|
||
```
|
||
- Total de mensagens recebidas (nw_event_logs)
|
||
- Total respondidas pela IA (nw_auto_replies)
|
||
- Taxa de auto-atendimento: respondidas / recebidas
|
||
- Escalações hoje / semana
|
||
- Tempo médio de resposta (created_at do webhook → created_at do reply)
|
||
- Distribuição por role (suporte X entregas X geral)
|
||
- Top 5 sessões por volume
|
||
```
|
||
|
||
**Endpoint:**
|
||
```
|
||
GET /api/admin/nw/metrics?period=7d
|
||
→ { total_in, total_replied, escalations, avg_response_ms, by_role[], top_sessions[] }
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Sequência de implementação recomendada
|
||
|
||
```
|
||
Semana 1:
|
||
[ ] Frente 1 — concluir WhatsAppInbox.tsx (estado + UI badges + botões)
|
||
[ ] Frente 3 — botão SyncKnowledge no painel (rápido, alto impacto)
|
||
|
||
Semana 2:
|
||
[ ] Frente 2 — webhook auto-resposta (modo 'automatico')
|
||
→ criar nw_auto_replies
|
||
→ integrar brain via fetch interno
|
||
→ throttle + anti-loop
|
||
|
||
Semana 3:
|
||
[ ] Frente 4 — escalação (detectar [ESCALAR] na resposta + tabela + badge)
|
||
[ ] Frente 5 — métricas básicas (endpoint + card dashboard)
|
||
```
|
||
|
||
---
|
||
|
||
## 4. Dependências técnicas críticas
|
||
|
||
### 4.1 O motor precisa de webhook configurado para auto-resposta funcionar
|
||
```
|
||
Motor → POST /api/webhook/newwhats (satélite)
|
||
Configurar via: POST /api/ext/v1/webhooks {
|
||
url: 'https://alemaoconveniencias.com.br/api/webhook/newwhats',
|
||
events: ['message.new', 'session.status'],
|
||
secret: '<webhook_secret do plugin_configs>'
|
||
}
|
||
```
|
||
|
||
### 4.2 Rotas do motor que o satélite usa internamente (sem auth)
|
||
```
|
||
/api/secretaria/conversations → busca/cria conversa por chatId
|
||
/api/secretaria/conversations/:id/chat → chama brain
|
||
/api/secretaria/agents → lista agentes ativos
|
||
```
|
||
|
||
### 4.3 Rota que satélite usa com auth (api key) para enviar resposta
|
||
```
|
||
POST /api/ext/v1/inbox/:chatId/send { text }
|
||
Header: x-nw-key: <integration_key>
|
||
```
|
||
|
||
### 4.4 Lookup chatId → conversa existente
|
||
O motor hoje não tem endpoint `GET /api/secretaria/conversations?chatId=`.
|
||
Precisará ser adicionado no motor ou o satélite usa `sec_conversations` via lookup próprio.
|
||
**Solução recomendada:** adicionar no motor:
|
||
```
|
||
GET /api/secretaria/conversations?chat_id=<chatId>&create=true
|
||
→ retorna conversa existente ou cria nova automaticamente
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Arquivos impactados
|
||
|
||
| Arquivo | Frente | Mudança |
|
||
|---|---|---|
|
||
| `plugins/newwhats/webhook-receiver.js` | F2 | auto-resposta + throttle |
|
||
| `plugins/newwhats/sync-knowledge.js` | F3 | sem mudança (já funcional) |
|
||
| `database/database.js` | F2+F4 | CREATE TABLE nw_auto_replies, nw_escalations |
|
||
| `sistema-nuvem/server.js` | F3+F5 | /admin/nw/metrics |
|
||
| `admin-app/src/pages/WhatsAppInbox.tsx` | F1+F3 | estado numbers + modais + badges + sync btn |
|
||
| `admin-app/src/services/api.ts` | F3 | NwService.syncKnowledge + previewKnowledge |
|
||
| `newwhats.local/plugins/secretaria/routes.ts` | F4 | GET /conversations?chat_id= |
|
||
|
||
---
|
||
|
||
## 6. Riscos e mitigações
|
||
|
||
| Risco | Impacto | Mitigação |
|
||
|---|---|---|
|
||
| IA responde cliente errado (loop) | Alto | `fromMe=true` nunca dispara; cooldown 30s; max 5 auto/conversa |
|
||
| Knowledge desatualizado | Médio | Sync automático ao salvar promoção/vaga; preview antes do sync |
|
||
| Motor fora do ar | Alto | Fallback chain (openai→gemini→anthropic→ollama); modo `off` por padrão |
|
||
| Webhook sem HMAC | Médio | Em dev aceita sem secret + aviso; em prod bloqueia |
|
||
| chatId não mapeado para conversa | Médio | Criar conversa automaticamente no primeiro contato |
|
||
| QR code expirado no modal | Baixo | Poll a cada 2s, aviso "QR expira em 60s" |
|
||
| Escalação ignorada | Alto | Badge vermelho persistente + email de alerta (futuro) |
|
||
|
||
---
|
||
|
||
## 7. Glossário técnico deste projeto
|
||
|
||
| Termo | Significado |
|
||
|---|---|
|
||
| Motor | `newwhats.local:8008` — instância independente do NewWhats |
|
||
| Satélite | `sistema-nuvem` do alemão — proxy + regras de negócio |
|
||
| ProtocolEngine | Classe `brain.ts` — core de IA stateful com nós |
|
||
| Brain Node | Registro em `sec_brain_nodes` (persona/knowledge/rules/calendar/escalation) |
|
||
| sec_numbers | Tabela do motor com metadados dos números (role, priority, area) |
|
||
| nw_event_logs | Tabela do satélite com todos os eventos recebidos via webhook |
|
||
| integration_key | Chave usada no header `x-nw-key` para rotas `/api/ext/v1/*` |
|
||
| motorUrl | URL do motor, lida de `plugin_configs WHERE key='newwhats_url'` |
|
||
| sync-knowledge | Script que lê BD alemão e atualiza o nó knowledge da Ana |
|
||
| context_window | Número de mensagens recentes passadas ao LLM (padrão: 8) |
|
||
| protocol_number | Identificador único da conversa formato `DDMMAAHHmmss` |
|