# Análise: Boilerplate Secretária Virtual × NewWhats v2.2

> Análise técnica real — comparando o boilerplate enviado com a arquitetura atual do motor NewWhats
> e identificando o que cada Frente v2.2 ganha (ou não) com esse padrão.

---

## TL;DR — Veredicto em 3 linhas

O boilerplate implementa **Tool Use** (IA chama funções em tempo real).
O motor atual implementa **Knowledge Node** (dados pré-carregados no system prompt).
**São complementares, não concorrentes — e o motor está faltando o Tool Use.**

---

## 1. O que o boilerplate faz certo

### ✅ Segurança: patientId vem da sessão, nunca da IA
```javascript
// patientId sempre da sessão — a IA nunca pode sobrescrever isso
async function executeTool(toolName, toolInput, patientId) { ... }

// No endpoint:
const patient = req.session.patient  // ← fonte da verdade
const { reply } = await runAgentLoop(messages, patient)
```
**Impacto:** A IA pode pedir "cancele o agendamento 999" de outro paciente, mas o
`WHERE patient_id = ?` garante que só o paciente da sessão é afetado.
Isso é o padrão correto de segurança com tool use.

### ✅ IA nunca toca o banco — executa via função intermediária
A IA solicita `{ name: 'cancel_appointment', input: { appointment_id: 42 } }`.
O servidor executa. A IA nunca tem credenciais, nunca faz queries diretas.

### ✅ Agent loop: multi-step tool chains
```javascript
while (true) {
  const response = await anthropic.messages.create({ tools: TOOLS, messages })
  if (response.stop_reason === 'end_turn') return reply
  if (response.stop_reason === 'tool_use') {
    // executa todas as tools solicitadas
    // devolve resultados e volta ao loop
    messages.push({ role: 'user', content: toolResults })
  }
}
```
Isso permite: `list_doctors` → apresenta ao usuário → `check_availability` → `create_appointment`
em uma única conversa, sem o usuário perceber que são 3 chamadas de API.

### ✅ Confirmação antes de ação destrutiva
O system prompt exige confirmação explícita antes de cancelar.
E o `cancel_appointment` re-verifica `WHERE patient_id = ?` como segunda camada de segurança.

### ✅ System prompt como "contrato" da IA
As regras absolutas são claras, específicas e mensuráveis:
- "NUNCA confirma agendamento sem check_availability" 
- "NUNCA discute temas fora do escopo"
- "NUNCA pede CPF ou dados bancários"

---

## 2. O que está faltando / gaps do boilerplate

### ❌ Zero prompt caching
Cada request reconstrói o system prompt + histórico do zero.
Com Claude, o system prompt idêntico entre requests ativa cache automático de prefix.
O boilerplate não usa `cache_control: { type: "ephemeral" }` nos blocos de sistema.

**Custo real:** Um system prompt de 800 tokens × 100 conversas/dia = 80.000 tokens de input pagos
inteiramente toda vez. Com cache, ~90% vira cache hit (5× mais barato).

### ❌ Histórico em RAM (express-session em memória)
```javascript
req.session.messages = updatedMessages.slice(-50)
```
- Reiniciar o servidor = perder todas as conversas ativas
- Não escala horizontalmente (sem Redis/banco)
- Slice(-50) é bruto — 50 mensagens podem ser 40.000 tokens se forem longas

**O motor faz certo:** persiste em `sec_conversations` + `sec_messages` no banco.

### ❌ Sem fallback de provider
Se a API key da Anthropic falhar → a secretária morre.
O motor tem a chain `openai → gemini → anthropic → ollama`.

### ❌ Sem limite de iterações no agent loop
```javascript
while (true) { ... }  // pode rodar para sempre
```
Se a IA entrar em loop (chama tool → recebe erro → chama tool de novo), nunca sai.
Falta: `if (iteration > MAX_ITER) throw new Error('Loop de ferramentas excedido')`

### ❌ Sem multi-tenant
Uma instância, um banco de dados de clínica. Não serve para SaaS.
O motor tem `tenantId` em todas as queries e usa `ext_chat_id = {tenantId}:{chatId}`.

### ❌ Sem sumarização automática
Histórico só cresce (limitado por slice bruto).
O motor sumariza a cada 10 trocas e descarta mensagens antigas, mantendo o contexto leve.

### ❌ Sem webhook — só polling request/response
O boilerplate assume que o humano digita no browser.
Para WhatsApp, o fluxo é invertido: o motor recebe webhook e precisa
chamar o runAgentLoop de forma assíncrona, depois enviar a resposta proativamente.

---

## 3. A diferença arquitetural central

```
BOILERPLATE                          MOTOR ATUAL (newwhats)
─────────────────────────────        ──────────────────────────────
Pattern: Tool Use (runtime)          Pattern: Knowledge Node (RAG)

IA decide quando buscar dados  →     Dados pré-carregados no prompt
Queries em tempo real por conv →     sync-knowledge.js roda periodicamente
+1-3 chamadas API por mensagem →     Contexto maior, 0 chamadas extras
Dados sempre frescos          →     Dados podem ter até 1h de delay
Conhece dados do CLIENTE      →     Conhece catálogo GERAL da empresa
```

### O que cada abordagem responde bem

| Pergunta do cliente | Knowledge Node | Tool Use |
|---|---|---|
| "Quais planos do clube odonto?" | ✅ (sync-knowledge) | funciona, mas desnecessário |
| "Quais parceiros aceitam meu plano?" | ✅ (sync-knowledge) | funciona |
| "Tenho promoção ativa?" | ✅ (sync-knowledge) | funciona |
| **"Quais são meus números da rifa?"** | ❌ **não sabe** | ✅ lookup por telefone |
| **"Meu plano está ativo?"** | ❌ **não sabe** | ✅ lookup por CPF |
| **"Minha candidatura foi aprovada?"** | ❌ **não sabe** | ✅ lookup por CPF |
| **"Quando é meu próximo vencimento?"** | ❌ **não sabe** | ✅ lookup por CPF |

**Conclusão:** O motor conhece o catálogo do Alemão, mas é cego para dados individuais do cliente.
O boilerplate mostra exatamente o que falta.

---

## 4. Mapeamento por Frente v2.2

### Frente 1 — Gerenciamento de Números ← **não usa o boilerplate**
O boilerplate é para chat de clínica, não para gerenciar instâncias WhatsApp.
Porém o padrão de segurança (`phone from webhook, never from AI`) é o mesmo princípio
que usaremos na auto-resposta: o número de origem vem do evento, nunca da IA.

**Status:** em implementação (modais AddNumber/EditNumber já adicionados no WhatsAppInbox.tsx).

---

### Frente 2 — Auto-resposta ← **o boilerplate É o que falta**

O `runAgentLoop` + `executeTool` é exatamente o núcleo que o webhook-receiver precisa.

**Hoje:**
```javascript
// webhook-receiver.js — handleMessageNew
async function handleMessageNew(data) {
  await execute(`INSERT INTO nw_event_logs ...`)
  // FIM — nunca responde
}
```

**Com padrão do boilerplate:**
```javascript
async function handleMessageNew(data) {
  await execute(`INSERT INTO nw_event_logs ...`)

  const msg = data.message
  if (msg.fromMe) return  // nunca responder a si mesmo

  // 1. Verifica role do número (notificacoes = nunca auto-responde)
  const numInfo = await getNwNumber(data.instanceId)
  if (!numInfo || numInfo.role === 'notificacoes') return
  if (auto_reply_mode === 'off') return

  // 2. Identifica cliente pelo telefone
  const phone = data.chatId.replace('@s.whatsapp.net', '')
  const clientCtx = await fetch(`http://localhost:3000/nw/cliente?telefone=${phone}`)

  // 3. Busca/cria conversa no motor — usa ext_chat_id = chatId
  const conv = await motorFetch('POST', '/secretaria/ask', {
    chatId:      data.chatId,
    message:     msg.body,
    contactName: msg.pushName ?? phone,
  })
  // motor.brain.chat() já executa o agent loop internamente

  // 4. Envia resposta via motor
  await motorFetch('POST', `/inbox/${data.chatId}/send`, { text: conv.reply }, useIntegKey)
}
```

**Mas há um problema crítico detectado:**
O `/secretaria/ask` do motor chama `brain.chat()` que é **somente texto** —
não tem tool use. A IA não pode buscar dados do cliente em tempo real.

Quando o cliente perguntar "meus números da rifa" a Ana vai responder
"acesse o site" porque não tem como saber.

---

### Frente 3 — Sync Knowledge ← **complementar ao boilerplate**

O boilerplate usa o banco direto (tool `list_doctors`).
O sync-knowledge.js usa o banco para construir o system prompt.

São estratégias diferentes para o mesmo problema:

```
Boilerplate approach:           sync-knowledge approach:
list_doctors como tool    →     médicos/parceiros no knowledge node
resultado por request     →     resultado atualizado de hora em hora
+tokens de tool call      →     +tokens no system prompt
sempre atualizado         →     atraso de até 1h
```

**Para o Alemão, o melhor é:**
- `sync-knowledge` para catálogo (planos, parceiros, promoções, vagas) ← já feito
- tool use para dados do cliente (tickets, memberships, candidaturas) ← falta

**Status:** botão de sync no admin ainda não implementado (simples, próximo passo).

---

### Frente 4 — Escalação ← **o boilerplate mostra o anti-padrão**

O boilerplate usa system prompt para definir regras de escalação:
```
"NUNCA realize ações destrutivas sem confirmação"
```

O motor já tem o nó `escalation` com o mesmo conceito, porém mais estruturado.

O que falta no motor (e o boilerplate não resolve) é o **lado operacional**:
detectar `[ESCALAR]` na resposta da IA e notificar o humano no painel.

O boilerplate não implementa escalação porque assume atendimento 100% humano de qualquer forma
(login no browser = humano já presente). Para WhatsApp assíncrono, escalação é crítica.

---

### Frente 5 — Métricas ← **o boilerplate tem zero**

Apenas `console.log` dos tool calls. Sem persistência, sem dashboard.

O `nw_event_logs` já é a base certa para métricas.
Quando a auto-resposta for implementada, adicionar `nw_auto_replies` resolve as métricas.

---

## 5. O gap mais crítico identificado: Motor sem Tool Use

O motor atual em `brain.ts`:
```typescript
private async callAI(...): Promise<string> { ... }
// Retorna sempre string — sem suporte a tool_use
```

Todos os providers são chamados sem `tools: []`. O motor nunca vai receber
`stop_reason: 'tool_use'` porque nunca passa ferramentas para a IA.

**Para a Ana ser realmente útil individualmente, o motor precisa evoluir:**

```typescript
// Hoje: brain.chat() → string
const reply = await brain.chat(convId, message)

// Precisaria: brain.chat() com tool loop (como o boilerplate)
interface Tool { name: string; description: string; input_schema: object }
interface ToolExecutor { (name: string, input: any, context: ChatContext): Promise<any> }

async chat(convId: string, message: string, tools?: Tool[], executor?: ToolExecutor): Promise<string>
```

As ferramentas que a Ana precisaria para o Alemão:
```javascript
const ALEMAO_TOOLS = [
  {
    name: 'buscar_cliente',
    description: 'Busca dados do cliente pelo telefone. Retorna tickets da rifa, clubes ativos e candidaturas.',
    input_schema: { type: 'object', properties: { telefone: { type: 'string' } }, required: ['telefone'] }
  },
  {
    name: 'buscar_clube',
    description: 'Retorna plano ativo do cliente, dependentes e parceiros credenciados.',
    input_schema: { type: 'object', properties: { cpf: { type: 'string' } }, required: ['cpf'] }
  },
  {
    name: 'buscar_candidaturas',
    description: 'Retorna candidaturas do cliente com status atual.',
    input_schema: { type: 'object', properties: { cpf: { type: 'string' } }, required: ['cpf'] }
  },
]
// Executor: chama as rotas /nw/* já existentes no satélite
```

Essas rotas `/nw/*` **já existem** no satélite. O problema é que a Ana não consegue chamá-las.

---

## 6. Resumo executivo — O que fazer com isso

### Aproveitar do boilerplate para v2.2

| O quê | Onde aplicar | Prioridade |
|---|---|---|
| Agent loop (while + tool_use) | webhook-receiver.js (Frente 2) | 🔴 Alta |
| Security pattern (phone from webhook only) | webhook-receiver.js (Frente 2) | 🔴 Alta |
| Max iterations guard | webhook-receiver.js anti-loop | 🔴 Alta |
| Tool definitions ALEMAO_TOOLS | motor brain.ts (evolução futura) | 🟡 Média |
| Confirmação antes de ação destrutiva | já no nó escalation do motor | ✅ Já existe |

### NÃO aproveitar do boilerplate

| O quê | Motivo |
|---|---|
| express-session em memória | motor já usa banco (correto) |
| Histórico slice(-50) | motor já sumariza (correto) |
| Single provider | motor já tem fallback chain (correto) |
| MySQL | projeto usa PostgreSQL |
| Sem multi-tenant | motor já tem tenantId (correto) |

### Sequência correta para Frente 2

```
1. webhook-receiver.js: verificar role do número (notificacoes = skip)
2. webhook-receiver.js: chamar POST /api/secretaria/ask (motor)
   → motor já faz: lookup/cria conversa, chama brain.chat()
   → brain.chat() responde com texto (sem tool use por ora)
3. webhook-receiver.js: enviar reply via POST /api/ext/v1/inbox/:chatId/send
4. Resultado: Ana responde perguntas gerais (catálogo) mas não dados individuais

5. (Evolução): adicionar tool use no brain.ts
   → Ana passa a responder "seus tickets são 003, 047, 112"
   → Usando as rotas /nw/* já existentes como tool executors
```

A Frente 2 básica (sem tool use) já resolve 70% dos casos de uso.
A evolução com tool use resolve os 30% restantes (dados pessoais do cliente).

---

## 7. Arquitetura alvo — Sistema completo

```
                    ┌─────────────────────────────────────┐
                    │         WhatsApp (cliente)           │
                    └──────────────┬──────────────────────┘
                                   │ mensagem
                                   ▼
                    ┌─────────────────────────────────────┐
                    │      Motor NewWhats (webhook)        │
                    │  POST /api/webhook/newwhats          │
                    └──────────────┬──────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────┐
                    │      webhook-receiver.js             │
                    │  1. verifica role do número          │
                    │  2. verifica auto_reply_mode         │
                    │  3. cooldown / anti-loop             │
                    └──────────────┬──────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────┐
                    │   POST /api/secretaria/ask           │
                    │   Motor: cria/retoma conversa        │
                    │   brain.chat(convId, message)        │
                    └──────────────┬──────────────────────┘
                                   │ [futuro: tool use]
          ┌───────────────────────►│◄───────────────────────┐
          │                        │                        │
┌─────────▼──────────┐   ┌────────▼──────────┐   ┌────────▼──────────┐
│  Knowledge Nodes   │   │  /nw/cliente       │   │  /nw/clube        │
│  (sync-knowledge)  │   │  /nw/candidaturas  │   │  /nw/sorteio      │
│  planos, parceiros │   │  /nw/vagas         │   │  /nw/promocoes    │
│  promoções, vagas  │   │  (dados pessoais)  │   │  (dados pessoais) │
└────────────────────┘   └───────────────────┘   └───────────────────┘
         (RAG)                    (Tool Use)              (Tool Use)
     dados estáticos           dados individuais        dados individuais
```

O boilerplate mostra como construir a metade direita do diagrama.
O motor já tem a metade esquerda funcionando.
**Frente 2 une as duas.**