VPS 4 Deploy Agent
2f8c04a0a7
continuous-integration/webhook Falha no deploy de clube67_newwhats.local (VPS 4)
241 lines
8.2 KiB
Markdown
241 lines
8.2 KiB
Markdown
# Plugin Empresa — Arquitetura de Integração
|
|
|
|
## Visão Geral
|
|
|
|
O sistema NewWhats roda em servidor próprio e nunca acessa diretamente o banco da empresa cliente.
|
|
A comunicação acontece por dois plugins que se reconhecem via chave compartilhada:
|
|
|
|
```
|
|
[ Servidor NewWhats ] [ Servidor da Empresa ]
|
|
Plugin: secretaria ←→ Plugin: newwhats-client
|
|
- Secretária IA - CRUD nos bancos
|
|
- WhatsApp / Baileys - Agente de consulta
|
|
- Inbox / Sessions - Frontend embarcado
|
|
```
|
|
|
|
---
|
|
|
|
## Plugin da Empresa (`newwhats-client`)
|
|
|
|
### Responsabilidades
|
|
|
|
- Conecta ao banco de dados interno da empresa (leitura e escrita)
|
|
- Expõe endpoints controlados para o NewWhats consumir
|
|
- Recebe webhooks do NewWhats (eventos, notificações)
|
|
- Serve o frontend embarcado (inbox, sessions, secretária)
|
|
- Gerencia a chave de integração e autenticação cruzada
|
|
|
|
### Instalação
|
|
|
|
O plugin é distribuído como pacote independente.
|
|
A empresa instala no próprio servidor — Node.js, PHP, Python ou via Docker.
|
|
Após instalação, gera-se uma `integration_key` que é inserida nos dois lados.
|
|
|
|
```
|
|
1. Empresa instala o plugin
|
|
2. Plugin gera integration_key + registra URL do servidor NewWhats
|
|
3. Admin copia a key e cola nas configurações do NewWhats
|
|
4. Os dois sistemas se reconhecem e começam a conversar
|
|
```
|
|
|
|
---
|
|
|
|
## Comunicação entre os Plugins
|
|
|
|
### Direções
|
|
|
|
| Direção | Quando | Exemplo |
|
|
|---|---|---|
|
|
| NewWhats → Empresa (pull) | Secretária precisa de dados em tempo real | Consultar agenda do Dr. |
|
|
| Empresa → NewWhats (push) | Evento proativo no sistema da empresa | Dr. cancelou consulta, avisar paciente |
|
|
|
|
### Autenticação
|
|
|
|
- Chave JWT gerada no NewWhats, compartilhada com o plugin da empresa
|
|
- Rotacionável pelo admin a qualquer momento
|
|
- Cada requisição carrega o JWT no header `Authorization: Bearer <key>`
|
|
- Expiração configurável (padrão: 90 dias)
|
|
|
|
---
|
|
|
|
## Contrato de API (Endpoints Mínimos)
|
|
|
|
O plugin da empresa **obrigatoriamente** expõe estes endpoints para a secretária funcionar:
|
|
|
|
### Agenda
|
|
```
|
|
GET /nw/agenda?data=YYYY-MM-DD&profissional_id= → horários disponíveis
|
|
POST /nw/agenda/agendar → confirmar agendamento
|
|
PUT /nw/agenda/:id/cancelar → cancelar agendamento
|
|
GET /nw/agenda/:id → detalhes de um agendamento
|
|
```
|
|
|
|
### Profissionais / Responsáveis
|
|
```
|
|
GET /nw/profissionais → lista com nome, área, número WhatsApp
|
|
GET /nw/profissionais/:id → dados de um profissional
|
|
```
|
|
|
|
### Clientes / Pacientes / Contatos
|
|
```
|
|
GET /nw/cliente?telefone=5511999999999 → dados pelo número de WhatsApp
|
|
GET /nw/cliente/:id → dados por ID
|
|
POST /nw/cliente → cadastrar novo cliente
|
|
```
|
|
|
|
### Webhook
|
|
```
|
|
POST /nw/webhook/registrar → registrar URL de callback no NewWhats
|
|
```
|
|
|
|
### Endpoints opcionais (dependem do ramo)
|
|
```
|
|
GET /nw/produtos → catálogo
|
|
GET /nw/pedidos?cliente_id= → histórico de pedidos
|
|
GET /nw/financeiro?cliente_id= → situação financeira
|
|
GET /nw/historico?cliente_id= → histórico de atendimentos
|
|
```
|
|
|
|
---
|
|
|
|
## Agente de Consulta (dentro do plugin da empresa)
|
|
|
|
O plugin não expõe o banco diretamente — ele tem um **agente interno** que:
|
|
|
|
1. Recebe a query da secretária (ex: `agenda?data=2026-04-15&profissional=Dr. Carlos`)
|
|
2. Traduz para uma query SQL ou chamada interna do sistema da empresa
|
|
3. Filtra apenas os campos permitidos (sem dados sensíveis)
|
|
4. Devolve JSON padronizado
|
|
|
|
```
|
|
Secretária IA (NewWhats)
|
|
↓ GET /nw/agenda?data=15/04
|
|
Plugin da Empresa
|
|
↓ SELECT * FROM agenda WHERE data = '2026-04-15' AND ativo = true
|
|
Banco da Empresa
|
|
↓ rows
|
|
Plugin filtra e formata
|
|
↓ JSON limpo
|
|
Secretária injeta no contexto e responde o cliente
|
|
```
|
|
|
|
### Permissões por endpoint
|
|
|
|
Cada endpoint tem uma flag de permissão configurável pelo admin da empresa:
|
|
|
|
```
|
|
agenda.read = true ✓
|
|
agenda.write = true ✓
|
|
cliente.read = true ✓
|
|
cliente.write = false ✗ (somente leitura por enquanto)
|
|
financeiro.read = false ✗ (dado sensível, bloqueado)
|
|
```
|
|
|
|
---
|
|
|
|
## Frontend Embarcado
|
|
|
|
### O que é
|
|
|
|
As três telas principais do NewWhats servidas **dentro do sistema da empresa**,
|
|
sem precisar abrir outro sistema ou fazer login separado.
|
|
|
|
```
|
|
Sistema da Empresa (ERP / CRM)
|
|
└── Menu
|
|
├── [módulos da empresa]
|
|
└── NewWhats ← plugin embarcado
|
|
├── Inbox (conversas WhatsApp em tempo real)
|
|
├── Sessions (instâncias Baileys, status de conexão)
|
|
└── Secretária IA (configuração + chat de teste)
|
|
```
|
|
|
|
### Opções de implementação
|
|
|
|
**Opção 1 — iFrame com token SSO** (mais simples)
|
|
- Plugin gera um token de sessão temporário (15min, renovável)
|
|
- Abre `https://newwhats-server/embed?token=<sso_token>` em iFrame
|
|
- NewWhats valida o token e serve a interface sem tela de login
|
|
|
|
**Opção 2 — Micro-frontend (componentes standalone)** (mais integrado)
|
|
- Plugin distribui componentes React/Vue que consomem a API do NewWhats
|
|
- Renderizam dentro do layout da empresa sem iFrame
|
|
- Requerem que a empresa use React/Vue no frontend
|
|
|
|
**Recomendação:** começar com iFrame SSO — funciona em qualquer stack,
|
|
entrega valor rápido. Migrar para micro-frontend quando houver demanda.
|
|
|
|
### Autenticação cruzada (SSO)
|
|
|
|
```
|
|
1. Usuário logado no sistema da empresa clica em "NewWhats"
|
|
2. Sistema da empresa chama POST /nw/auth/sso no NewWhats com a integration_key
|
|
3. NewWhats retorna um token de sessão temporário
|
|
4. Plugin abre o iFrame com esse token
|
|
5. Usuário entra direto, sem segunda tela de login
|
|
```
|
|
|
|
---
|
|
|
|
## Números e Papéis
|
|
|
|
O plugin da empresa cadastra os números WhatsApp relevantes e seus papéis:
|
|
|
|
| Papel | Descrição | Exemplo |
|
|
|---|---|---|
|
|
| `secretary_virtual` | Número principal da secretária IA | Atende clientes |
|
|
| `clinic` | Número geral da empresa | Recebe notificações |
|
|
| `doctor` / `specialist` | Profissional responsável por área | Recebe dúvidas específicas |
|
|
| `manager` | Fallback universal | Recebe quando ninguém mais responde |
|
|
| `reserve` | Backup da secretária | Entra quando principal cai ou é banido |
|
|
| `human_secretary` | Secretária humana | Pode assumir conversa da IA |
|
|
|
|
O NewWhats consulta esses papéis via `GET /nw/profissionais` e usa para roteamento interno.
|
|
|
|
---
|
|
|
|
## Fluxo Completo — Exemplo Real
|
|
|
|
**Cenário:** Paciente pergunta se pode agendar com o Dr. Carlos na quinta-feira.
|
|
|
|
```
|
|
1. Paciente envia mensagem no WhatsApp
|
|
2. Baileys recebe → NewWhats aciona Secretária IA
|
|
3. Nó de intenção classifica: "agendamento"
|
|
4. Nó de calendário chama GET /nw/agenda?data=2026-04-16&profissional=Dr.Carlos
|
|
5. Plugin da empresa consulta banco → retorna horários livres
|
|
6. Secretária oferece opções ao paciente
|
|
7. Paciente confirma horário das 14h
|
|
8. Secretária chama POST /nw/agenda/agendar com os dados
|
|
9. Plugin grava no banco da empresa
|
|
10. Secretária confirma para o paciente via WhatsApp
|
|
11. Sistema da empresa exibe o agendamento normalmente no próprio sistema
|
|
```
|
|
|
|
**Tudo isso sem o paciente saber que são dois sistemas.**
|
|
|
|
---
|
|
|
|
## Roadmap de Implementação
|
|
|
|
### Fase 1 — Conexão básica
|
|
- [ ] Geração e troca de `integration_key` entre os dois plugins
|
|
- [ ] Endpoints mínimos no plugin da empresa (agenda, profissionais, cliente)
|
|
- [ ] Nó do tipo `api_query` no cérebro da secretária
|
|
- [ ] Teste end-to-end: secretária consulta agenda real
|
|
|
|
### Fase 2 — Agente de consulta
|
|
- [ ] Agente interno no plugin da empresa com mapeamento de permissões
|
|
- [ ] Push de eventos (webhook): cancelamentos, atualizações
|
|
- [ ] Roteamento por papel: secretária sabe para qual número perguntar
|
|
|
|
### Fase 3 — Frontend embarcado
|
|
- [ ] SSO por token temporário
|
|
- [ ] iFrame com Inbox + Sessions + Secretária IA
|
|
- [ ] Personalização básica (logo, cores da empresa)
|
|
|
|
### Fase 4 — Expansão
|
|
- [ ] SDK para empresas implementarem o plugin em qualquer stack
|
|
- [ ] Marketplace de conectores prontos (ex: conector para sistemas populares do setor)
|
|
- [ ] Painel de auditoria cruzada (o que a secretária consultou e quando)
|