# Secretária Virtual — Roadmap Completo (Opção 3 Híbrida)

## Arquitetura Alvo

```
Plugin Alemão (satélite)                      Motor NewWhats
┌──────────────────────────────┐              ┌──────────────────────────────┐
│  webhook-receiver.js         │   POST ask   │  ProtocolEngine (brain.ts)   │
│  └─ context-builder.js       │ ───────────► │  system prompt dinâmico      │
│     └─ DB local (clientes,   │              │  histórico + summarização     │
│        planos, promoções)    │ ◄─────────── │  fallback chain AI providers │
│                              │    reply     │  sec_conversations/messages   │
│  HandoffButton (UI)          │              │                              │
│  └─ per-chat mode:           │  PATCH mode  │  chat_handoff_mode           │
│     ia | humano | pausado    │ ───────────► │  (campo por conversa)        │
└──────────────────────────────┘              └──────────────────────────────┘
```

---

## LEGENDA DE STATUS
- ✅ Implementado e funcionando
- 🔲 Pendente — não iniciado
- 🚧 Parcialmente feito

---

## BLOCO 1 — Handoff Humano ↔ IA (Botão Flutuante)

> Botão flutuante acima do input bar no chat. Um clique pausa a IA e o humano
> assume. Outro clique devolve o controle à IA. Se o humano ficar 15 min sem
> responder (ou a conexão cair), a IA reassume automaticamente.

### 1.1 — Motor: campo de modo por conversa

- 🔲 Adicionar coluna `handoff_mode` ENUM(`ia`, `humano`, `pausado`) DEFAULT `ia` na tabela `sec_conversations` (migration Knex)
- 🔲 Adicionar coluna `handoff_human_at` TIMESTAMP NULL na tabela `sec_conversations` (registra quando humano assumiu)
- 🔲 Rodar migration no motor (`plugins/secretaria/migrate.ts`)

### 1.2 — Motor: rotas de handoff (ext-api)

- 🔲 Criar `PATCH /ext/v1/sec/conversations/:id/handoff` — body `{ mode: 'ia'|'humano' }` — atualiza `handoff_mode` e `handoff_human_at`
- 🔲 Em `POST /ext/v1/secretaria/ask` — verificar `handoff_mode` antes de chamar brain: se `humano`, retornar `{ skipped: true }` sem chamar IA

### 1.3 — Motor: timer de retomada automática (15 min)

- 🔲 Criar job BullMQ `handoff-timeout` no motor: ao mudar para modo `humano`, enfileirar job com delay de 15 min
- 🔲 Job verifica se `handoff_mode` ainda é `humano` E `handoff_human_at` há mais de 15 min → muda para `ia` → emite evento WebSocket `conversation.handoff` para o satélite
- 🔲 Ao receber mensagem humana (`PATCH /handoff mode=humano`), cancelar job anterior e enfileirar novo (reset do timer)
- 🔲 Se conexão WS do satélite cair (`disconnect`), mudar todas as conversas desse satélite em modo `humano` para `ia` automaticamente

### 1.4 — Frontend: NwService métodos

- 🔲 Adicionar `NwService.getHandoffMode(chatId)` → `GET /nw/v1/sec/conversations/:id/handoff` (ou campo incluso no chat)
- 🔲 Adicionar `NwService.setHandoffMode(chatId, mode)` → `PATCH /nw/v1/sec/conversations/:id/handoff`

### 1.5 — Frontend: HandoffButton component (WhatsAppInbox.tsx)

- 🔲 Criar componente `HandoffButton` — botão flutuante posicionado `absolute bottom-[72px] right-4 z-20`
- 🔲 Estado local `handoffMode: 'ia' | 'humano'` por chat — carrega ao abrir o chat
- 🔲 Visual quando modo `ia`: ícone `Bot` verde com tooltip "IA respondendo — clique para assumir"
- 🔲 Visual quando modo `humano`: ícone `UserCheck` laranja pulsando com tooltip "Você está respondendo — clique para devolver à IA" + contador regressivo de 15 min
- 🔲 Ao clicar: chama `NwService.setHandoffMode`, atualiza estado local otimisticamente
- 🔲 Mostrar o botão apenas se sessão CONNECTED e chat selecionado
- 🔲 Esconder o botão se auto-reply mode = `off` (secretária desligada globalmente)

### 1.6 — Frontend: exibição visual no chat

- 🔲 Injetar mensagem de sistema no fluxo de mensagens ao mudar de modo: "🤖 IA assumiu o atendimento" / "👤 Atendente humano assumiu"
- 🔲 Header do chat mostrar badge discreto: `IA` (verde) ou `Humano` (laranja)

### 1.7 — Frontend: retomada automática via WebSocket

- 🔲 Escutar evento WS `conversation.handoff` → atualizar `handoffMode` local sem recarregar a página
- 🔲 Exibir toast "Secretária retomou o atendimento automaticamente (15 min sem resposta)"

### 1.8 — Motor: emitir evento WS ao retomar

- 🔲 Após job BullMQ retomar modo `ia`, emitir via WS `{ event: 'conversation.handoff', data: { chatId, mode: 'ia', reason: 'timeout' } }` para o satélite correto

### 1.9 — Webhook receiver: respeitar handoff

- 🔲 Em `webhook-receiver.js`, antes de chamar `/secretaria/ask`, consultar modo da conversa
- 🔲 Se modo `humano` → não chamar IA, apenas registrar mensagem recebida
- 🔲 Resetar timer de 15 min ao detectar mensagem do atendente humano (mensagem `fromMe: true`)

---

## BLOCO 2 — Injeção de Contexto Local (Opção 3 Híbrida)

> Hoje a secretária fica cega ao DB do projeto. O plugin precisa enriquecer
> cada chamada ao motor com dados reais do cliente.

### 2.1 — Motor: ampliar brain.chat() para aceitar contexto

- 🔲 Modificar `brain.ts` → `chat(convId, message, opts?: { contextData?: object; systemExtra?: string })`
- 🔲 Serializar `contextData` como bloco de texto e appendar ao system prompt antes da chamada à IA
- 🔲 Modificar `POST /ext/v1/secretaria/ask` → extrair `context` e `system_prompt_extra` do body e repassar ao brain

### 2.2 — Plugin: criar context-builder.js

- 🔲 Criar `sistema-nuvem/plugins/newwhats/context-builder.js`
- 🔲 Implementar `buildContext(phone)`:
  - Buscar cliente pelo telefone no DB alemão (tabela `users` ou `clients`)
  - Buscar status de assinatura do clube
  - Buscar último pedido / histórico recente (últimos 3)
  - Buscar promoções ativas do dia
  - Buscar vagas abertas (caso relevante)
- 🔲 Retornar objeto `{ cliente, plano, ultimos_pedidos, promocoes_ativas }`

### 2.3 — Plugin: webhook-receiver usa context-builder

- 🔲 Modificar `webhook-receiver.js`: extrair número do remetente de `data.from`
- 🔲 Chamar `context-builder.js` com o número antes de chamar `/secretaria/ask`
- 🔲 Enviar `context` e `system_prompt_extra` no payload do `ask`

---

## BLOCO 3 — Tool Calling (IA que age, não só fala)

> Sem tools, a IA só gera texto. Com tools ela pode agendar, buscar e escalar.

### 3.1 — Motor: suporte a tools no ProtocolEngine

- ✅ Criado `plugins/secretaria/tools.ts` com interface `ToolDef { name, description, parameters, execute() }`
- ✅ Tools implementadas: `listar_horarios`, `agendar_horario`, `escalar_humano`, `encerrar_protocolo`
- ✅ `brain.chat()` aceita `tools?: string[]` — resolve via `resolveTools()` e habilita tool calling
- ✅ Loop de tool calling por provider: OpenAI (tool_calls), Anthropic (tool_use), Gemini (functionCall) — máx 5 iterações
- ✅ Fallback gracioso: se nenhum provider com tools disponível, usa modo texto normal
- ✅ `POST /ext/v1/secretaria/ask` aceita `tools: string[]` e repassa ao brain com hooks + tenantId

### 3.2 — Plugin: integração com tools do motor

- ✅ `webhook-receiver.js` inclui `tools: ['listar_horarios', 'agendar_horario', 'escalar_humano', 'encerrar_protocolo']` no payload do ask
- ✅ `escalar_humano` aciona handoff_mode=humano + emite `ext:handoff` via HookBus → chega ao frontend via WS
- ℹ️ `buscar_cliente` / `verificar_plano` resolvidos via `context-builder.js` (Bloco 2) — contexto pré-computado injetado no system prompt, não como tool call (mais simples e confiável)

---

## BLOCO 4 — Painel Admin: Melhorias

### 4.1 — Visualização de conversa

- ✅ Sub-tab Conversas: clicar em protocolo abre drawer lateral com todas as mensagens
- ✅ Botão "Finalizar protocolo" no drawer → `POST /sec/conversations/:id/finalize`
- ✅ Badge visual em conversas com `handoff_mode = humano` (ícone laranja)
- ✅ Badge visual em conversas escaladas (`status = escalated`)

### 4.2 — Chat de teste inline

- ✅ Sub-tab "Testar" no painel Secretária: campo de texto + botão enviar
- ✅ Chama `/secretaria/ask` com um chatId de teste fictício e exibe resposta
- ✅ Útil para testar prompts sem precisar de celular conectado

### 4.3 — Segurança das API Keys

- ✅ `GET /ext/v1/sec/keys` mascarar valores: `sk-...****` (mostrar só prefixo + últimos 4 chars)
- ✅ Campo de senha no painel com placeholder `••••••••` quando já salvo

---

## BLOCO 5 — Escalação Real

### 5.1 — Detecção e notificação

- ✅ Motor: `escalar_humano` tool emite `ext:escalated` com protocolNumber + motivo
- ✅ Motor: ws-bridge encaminha `ext:escalated` → `conversation.escalated` ao satélite
- ✅ Motor: listener em `buildExtRoutes` envia WA ao `admin_notify_phone` configurado
- ✅ Motor: `GET/PUT /sec/keys` inclui `admin_notify_phone` (em claro, não mascarado)
- ✅ Painel: toast laranja `⚠️ Escalação` ao receber `conversation.escalated` via WS
- ✅ Painel: badge "Escalada" vermelho nas conversas (implementado no Bloco 4)
- ✅ Painel: campo "WhatsApp do administrador" na aba Config

---

## RESUMO PRIORIZADO

| # | Bloco | Tarefa | Impacto | Esforço |
|---|---|---|---|---|
| 1 | Handoff | Migration: `handoff_mode` + `handoff_human_at` | 🔴 Crítico | Trivial |
| 2 | Handoff | `PATCH /sec/conversations/:id/handoff` + skip no ask | 🔴 Crítico | Pequeno |
| 3 | Handoff | `HandoffButton` React component | 🔴 Crítico | Pequeno |
| 4 | Handoff | Timer 15 min via BullMQ + retomada automática | 🔴 Crítico | Médio |
| 5 | Handoff | Evento WS `conversation.handoff` | 🟠 Alto | Pequeno |
| 6 | Handoff | Webhook-receiver respeitar modo humano | 🟠 Alto | Pequeno |
| 7 | Contexto | `context-builder.js` no plugin | 🔴 Crítico | Médio |
| 8 | Contexto | Motor aceitar `context` no brain.chat() | 🔴 Crítico | Pequeno |
| 9 | Contexto | Webhook receiver enviar contexto no ask | 🟠 Alto | Pequeno |
| 10 | Painel | Visualizar mensagens do protocolo + finalizar | 🟡 Médio | Pequeno |
| 11 | Painel | Mascarar API keys | 🟡 Médio | Trivial |
| 12 | Tools | Tool calling no ProtocolEngine | 🟠 Alto | Grande |
| 13 | Tools | Tools locais no plugin (buscar_cliente, etc.) | 🟠 Alto | Médio |
| 14 | Escalação | Notificação real ao admin + handoff automático | 🟡 Médio | Médio |
| 15 | Painel | Chat de teste inline | 🟢 Baixo | Pequeno |

---

## FLUXO ALVO COMPLETO

```
Mensagem recebida no WA
  │
  ▼
webhook-receiver.js
  ├─ extrai phone do remetente
  ├─ context-builder.js → { cliente, plano, pedidos, promoções }
  ├─ verifica handoff_mode da conversa
  │    ├─ modo "humano" → não chama IA, reseta timer 15min, fim
  │    └─ modo "ia" → continua
  └─ POST /secretaria/ask { chatId, message, context, tools: [...] }
       │
       ▼
  Motor ProtocolEngine.chat()
       ├─ monta system prompt = persona + knowledge + rules + calendar + context_local
       ├─ chama IA com tool definitions
       │    ├─ IA chama tool → executa → retorna resultado → IA gera resposta
       │    └─ IA responde diretamente
       └─ retorna { reply, conversationId, protocolNumber }
            │
            ▼
       webhook-receiver.js envia reply via WA ao cliente

Humano clica HandoffButton
  ├─ PATCH /sec/conversations/:id/handoff { mode: "humano" }
  ├─ BullMQ enfileira job com delay 15min
  ├─ UI exibe badge laranja + contador regressivo
  └─ próximas mensagens WA → webhook ignora IA

15 min sem resposta humana (ou WS cai)
  ├─ BullMQ job dispara → mode = "ia"
  ├─ Motor emite WS conversation.handoff
  └─ UI atualiza badge → toast "Secretária retomou"
```