feat: sincronização de desenvolvimento local da VPS 4 para o Gitea
This commit is contained in:
VPS 4 Deploy Agent
@@ -0,0 +1,240 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user