ruicesar/clube67_newwhats.local

Fork 0

Files

T

VPS 4 Deploy Agent 2f8c04a0a7

continuous-integration/webhook Falha no deploy de clube67_newwhats.local (VPS 4)

Details

chore(ops): restore all source files in newwhats.clube67.com

2026-05-18 03:28:29 +02:00

8.2 KiB

Raw Blame History

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:

Recebe a query da secretária (ex: agenda?data=2026-04-15&profissional=Dr. Carlos)
Traduz para uma query SQL ou chamada interna do sistema da empresa
Filtra apenas os campos permitidos (sem dados sensíveis)
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)

8.2 KiB Raw Blame History