# 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)
