VPS 4 Builder
14 KiB
14 KiB
Inbox Interna — Arquitetura & Roadmap
Data: 2026-04-23
Status: v1 (Escalações + Human API) ✅ | v2.1 (DM entre Colaboradores) ✅ | v2.2 (Planejado: Group Chat + Broadcast)
📋 O que é?
Inbox Interna = Centro de comunicação interna da equipe para gerenciar escalações de clientes, pedidos de ajuda da IA e colaboração entre setores.
É onde:
- 🎯 Escalações chegam quando cliente pede falar com humano no WhatsApp
- 🤖 IA pede ajuda quando não consegue resolver algo (Human API)
- 💬 Equipe colabora deixando mensagens de contexto sobre protocolos
🏗️ Arquitetura Atual (v1)
Tipos de Threads
| Tipo | Trigger | Origem | Exemplo |
|---|---|---|---|
| escalation | Cliente escala no WhatsApp | Motor NewWhats | Protocolo #123: cliente reclamando |
| human_api | IA não consegue responder | Motor NewWhats | "Qual é a política de devolução?" |
| ajuda | Colaborador solicita suporte | UI "Preciso de ajuda" | Dúvida sobre procedimento |
| mensagem | Anotação de contexto | Colaboradores | "Cliente quer falar com gerente" |
| sistema | Avisos automáticos | Sistema | "Handoff expirou" |
Estrutura de Dados
internal_messages {
id UUID
tenant_id INT (isolamento multi-tenant)
thread_id UUID (agrupa msgs da mesma conversa)
from_account INT (FK → accounts.id)
type VARCHAR (escalation|human_api|ajuda|mensagem|sistema)
content TEXT
ref_id VARCHAR (protocolo ou human_api_request.id)
chat_id VARCHAR (vinculado ao chat do WhatsApp)
lida BOOLEAN (marca como lida)
created_at TIMESTAMP
}
sector_brain_nodes {
id UUID
sector_id INT
type VARCHAR (knowledge|rules|escalation|persona)
title VARCHAR
content TEXT
active BOOLEAN
sort_order INT
}
Fluxo Atual
┌─ WhatsApp ─────┐
│ Cliente fala │
│ com IA │
└────────┬────────┘
│
┌────▼──────────┐
│ Motor NewWhats│
│ (porta 8008) │
└────────┬──────┘
│
┌──────▼────────────────┐
│ Precisa de ajuda? ────┼─→ Cria Human API request
│ Cliente quer humano? ─┼─→ Cria Escalação + Protocolo
└──────┬────────────────┘
│
┌──────▼──────────────┐
│ Inbox Interna │
│ (internal_messages)│
│ │
│ Colaborador lê ←──┤── Thread
│ Responde ──→┤── Mensagem
│ Encerra ←──┤── Reset handoff
└──────┬──────────────┘
│
┌──────▼────────────────┐
│ Resposta volta à IA │
│ IA continua conversa │
│ com cliente │
└───────────────────────┘
Filtros (Abas)
- Todos — todas as threads abertas
- Human API — apenas pedidos de ajuda da IA
- Escalação — clientes que escalaram
- Ajuda — colaboradores pedindo suporte interno
- Mensagem — anotações de contexto
- Sistema — avisos automáticos
🔴 Lacunas Atuais (v1)
❌ Falta: Comunicação Livre entre Colaboradores
Situação atual:
- Só há threads de CONTEXTO (vinculadas a escalações/human API)
- Colaboradores não conseguem falar entre si sem um protocolo
- Sem forma de fazer DM privada, group chat por setor, ou broadcast
Exemplos de uso que FALTAM:
João: "Maria, qual é o status do pedido #456?"
(não há como enviar DM privada)
Secretária (broadcast): "Servidor em manutenção em 5 min!"
(não há como mandar aviso para todos)
Setor Financeiro: "Pessoal, cliente quer falar sobre boleto..."
(não há como falar só com o time do setor)
💡 Sugestão: Coluna de Colaboradores (v2)
Análise da Sugestão ✅
Layout proposto:
┌──────────────────────────────────────────────────────┐
│ Abas: Todos | Human API | Escalação | Ajuda | ... │
├──────────────────┬──────────────────────────────────┐
│ COLABORADORES │ THREADS / CONTEXTO │
│ (Coluna) │ │
│ │ Protocolo #123 │
│ • João (online) │ ├─ Cliente: Fulano │
│ • Maria (busy) │ ├─ Setor: Secretária │
│ • Pedro (away) │ ├─ Última msg: há 2min │
│ • Carla (offline)│ └─ [Responder] [Encerrar] │
│ │ │
│ [+] Novo │ Protocolo #122 │
│ │ ├─ Tipo: Human API │
│ │ ├─ Pergunta: "Política..?" │
│ │ └─ [Responder] │
└──────────────────┴──────────────────────────────────┘
Vantagens ✅
| Aspecto | Ganho |
|---|---|
| Navegação rápida | Clique em colaborador = DM privada |
| Presença visual | Cor indica online/busy/offline |
| Unread badges | Quantas DMs não lidas por pessoa |
| Busca | Filtrar colaboradores por nome |
| Contexto duplo | Ver threads E falar com pessoas |
| Similar a Slack/WhatsApp | UX familiar para usuários |
| Iniciar conversa | Botão [+] abre nova DM |
| Gestão de setores | Filter "mostrar só meu setor" |
Desvantagens ⚠️
| Risco | Mitigation |
|---|---|
| Coluna muitas pessoas | Busca + virtualization se >50 pessoas |
| Clutter na UI | Coluna colapsável (toggle) |
| Sem histórico persistente | Arquitetar tabela direct_messages |
| Sem notificações SSE | Adicionar evento SSE direct_message.new |
🎯 Proposta de Implementação (v2)
Fase 1: Estrutura de Dados
-- Threads de chat direto (novo tipo)
direct_messages {
id UUID PRIMARY KEY
tenant_id INT NOT NULL
from_account INT NOT NULL (FK → accounts.id)
to_account INT NOT NULL (FK → accounts.id) -- NULL = group chat
content TEXT NOT NULL
lida BOOLEAN DEFAULT false
created_at TIMESTAMP DEFAULT now()
}
-- Group chats por setor
group_chats {
id UUID PRIMARY KEY
tenant_id INT NOT NULL
sector_id INT NOT NULL (FK → sectors.id)
name VARCHAR NOT NULL
topic TEXT
created_at TIMESTAMP DEFAULT now()
}
group_chat_members {
id UUID PRIMARY KEY
group_chat_id UUID (FK → group_chats.id)
account_id INT (FK → accounts.id)
joined_at TIMESTAMP DEFAULT now()
}
Fase 2: UI Layout
Nova estrutura:
├── Sidebar esquerdo
│ └─ COLABORADORES (coluna conversável)
│ ├─ [🔍 Buscar...]
│ ├─ 🟢 João (2 DMs não lidas)
│ ├─ 🟡 Maria (online)
│ ├─ ⚪ Pedro (away)
│ ├─ ⚫ Carla (offline)
│ └─ [+] Iniciar DM
│
└── Conteúdo principal
├─ Abas: Todos | Human API | Escalação | Ajuda | Mensagem | Sistema
└─ Threads de contexto (atuais)
Fase 3: Funcionalidades
📌 DM Privada
- Clique em colaborador → abre chat
- Histórico persistente
- Marca como lido
👥 Group Chat por Setor
- Secretária, Financeiro, etc.
- Mensagens visíveis para todo o setor
- Notificação de @menção
📢 Broadcast
- Só owner/manager
- Aviso para TODOS os colaboradores
- "Sistema está em manutenção em 5 min"
🔔 Notificações SSE
- `direct_message.new` → atualiza badge
- `group_message.new` → notifica setor
- `broadcast.sent` → notifica todos
📊 Comparação: Atual vs Proposto
Inbox Interna v1 (Atual)
Uso: Gerenciar escalações + ajuda da IA
Threads: Escalação, Human API, Ajuda, Sistema
Colaboradores: Implícitos (apenas quem responde)
Chat: Não há comunicação livre
Comunicação: Apenas REATIVA (resposta a eventos)
Inbox Interna v2 (Proposto)
Uso: Escalações + IA + Chat interno + Broadcasts
Threads: Escalação, Human API, Ajuda, Sistema, DM, Group, Broadcast
Colaboradores: Listados na coluna, clickable
Chat: DMs privadas + Group por setor
Comunicação: Reativa + Proativa (falar entre si)
🚀 Priorização
| # | Feature | Complexidade | Impacto | Prioridade |
|---|---|---|---|---|
| 1 | Coluna Colaboradores | 🟡 Média | Alto | 🔴 ALTA |
| 2 | DM Privada | 🟢 Baixa | Muito Alto | 🔴 ALTA |
| 3 | Group Chat por Setor | 🟡 Média | Alto | 🟡 MÉDIA |
| 4 | Broadcast | 🟢 Baixa | Médio | 🟡 MÉDIA |
| 5 | Notificações SSE | 🟡 Média | Alto | 🔴 ALTA |
| 6 | Busca/Filter | 🟢 Baixa | Médio | 🟢 BAIXA |
📝 Implementação Concluída (Fase 1)
✅ Completados (2026-04-23)
Backend:
- Tabela
direct_messagescriada com indexes - Endpoint:
POST /api/admin/inbox/direct-message← enviar DM - Endpoint:
GET /api/admin/inbox/direct/:otherAccountId← histórico - Endpoint:
GET /api/admin/inbox/direct-messages← últimas DMs - Endpoint:
GET /api/admin/inbox/colleagues← listar colaboradores - Endpoint:
PATCH /api/admin/inbox/direct/:messageId/read← marcar como lida - DirectMessage model com 6 métodos (send, getConversation, getLastMessages, getUnreadCount, markAsRead, getUnreadCountByContact)
- DirectMessageService exportado em admin-app/src/services/api.ts
Frontend:
- CollaboratorsPanel.tsx: coluna com busca, status, badges de não lida
- DMConversationView.tsx: chat bubbles, input, auto-scroll
- InboxInternaTab.tsx: integração two-column (Inbox + Colaboradores tabs)
- Auto-load conversation quando abrir chat
- Auto-mark-as-read ao abrir conversa
- 30-segundo auto-refresh de colaboradores
Database:
direct_messages {
id SERIAL PRIMARY KEY,
tenant_id INT,
from_account INT,
to_account INT,
content TEXT,
read_at TIMESTAMPTZ,
created_at TIMESTAMPTZ DEFAULT NOW()
}
-- Indexes: (tenant_id, from_to pairs, read_status, created_at DESC)
🔄 Próximos Passos
- SSE: adicionar evento
direct_message.newpara notificação real-time - Group Chat por Setor (Fase 2)
- Broadcast para todos (Fase 2)
- Busca em conversas
- Pinning/Marking de mensagens importantes
🎨 Mockup
Inbox Interna v2 (esboço)
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ COLABORADORES ┃ [Todos] [Human API] [Escalação]... ┃
┣━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
┃ [🔍 Buscar...] ┃ ┃
┃ ┃ ┌────────────────────────────────┐ ┃
┃ 🟢 João 2 ┃ │ Protocolo #123 │ ┃
┃ 🟡 Maria 0 ┃ │ ├─ Cliente: Fulano Silva │ ┃
┃ ⚪ Pedro 1 ┃ │ ├─ Setor: Secretária │ ┃
┃ ⚫ Carla 0 ┃ │ ├─ Criado: há 15 min │ ┃
┃ ┃ │ ├─ Status: Aberto │ ┃
┃ [+] Iniciar DM ┃ │ └─ [Responder] [Encerrar] │ ┃
┃ ┃ └────────────────────────────────┘ ┃
┃ ┃ ┃
┃ ┃ ┌────────────────────────────────┐ ┃
┃ ┃ │ Human API Request │ ┃
┃ ┃ │ ├─ Pergunta: "Qual política..."│ ┃
┃ ┃ │ ├─ Setor: Financeiro │ ┃
┃ ┃ │ └─ [Responder] │ ┃
┃ ┃ └────────────────────────────────┘ ┃
┗━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
✅ Conclusão
A sugestão da coluna de colaboradores é excelente porque:
- ✅ Resolve a lacuna de comunicação entre colaboradores
- ✅ UX familiar (similar a Slack/WhatsApp)
- ✅ Melhora discoverabilidade (ver quem está online)
- ✅ Simples de implementar (coluna + nova tabela)
- ✅ Impacto alto na experiência de colaboração
Recomendação: Implementar em duas fases:
- Fase 1 (rápida): Coluna + DM privada + SSE
- Fase 2 (depois): Group chat + broadcast
Autor: Claude
Revisor: Necessário
Status: Draft para aprovação