Dashboards agrupam widgets — contadores, séries temporais, decomposições, funis, tabelas, listas top-n — sobre eventos de agente. Combine canônicos do sistema (agent_view, agent_atc, agent_purchase, …) com tipos de evento personalizados registrados via o registro de Tipos de Evento Personalizados.
Composição
Um dashboard pertence a uma única marca. Cada widget contém:
- type — um dos seis tipos iniciais (
counter, time_series, breakdown_bar, funnel, table, top_n)
- config — opções específicas do tipo, validadas pelo schema zod do widget. Título e os parâmetros de agregação por widget vivem dentro do
config (não há colunas title ou aggregation separadas na linha do widget)
- position — coordenadas de grid
(x, y, w, h) para react-grid-layout
O motor de agregação executa contra agent_events no DO Postgres com SQL parametrizado — workspace_id e brand_id são sempre adicionados ao predicado a partir do contexto da requisição, independente dos filtros enviados pelo usuário, garantindo isolamento por marca por construção. Os resultados são armazenados em cache no Redis por 60 segundos.
Papéis
- Members podem visualizar dashboards
- Owners e admins podem criar, editar e excluir
Contexto de marca
Toda leitura e escrita requer contexto de marca. Envie como:
- Header
X-Active-Brand: <uuid> (preferido), ou
- Query
?brand_id=<uuid> (alternativa para clientes que não conseguem enviar headers)
Para o endpoint POST /aggregate, o header / query é a única fonte de contexto de marca — o corpo da requisição não carrega marca. Isso elimina a classe de bugs em que um campo do body discorda do header.
Veja também
Última modificação em 25 de abril de 2026
