PHSYS - Wiki

Conceito

É possível construir um dashboard pedindo a um agente de IA que gere o arquivo de importação. Você fornece o contexto do que quer acompanhar, a consulta SQL que traz os dados e o layout desejado; o agente devolve um arquivo compatível com o ERP, que é carregado pelo botão Importar do cadastro de Dashboards.

O que é

O dashboard e seus Widgets podem ser descritos inteiramente por um arquivo (formato JSON), o mesmo que o botão Exportar gera. Como esse arquivo é texto estruturado e tem regras conhecidas, um agente de IA consegue produzi-lo a partir de uma descrição em linguagem natural, sem que ninguém precise preencher os cadastros campo a campo.

O agente não acessa o sistema: ele apenas escreve o arquivo. Quem cria, atualiza e valida os registros continua sendo o ERP, no momento da importação.

Para que serve

Serve para encurtar o caminho entre "eu preciso enxergar esse número" e um painel pronto. Em vez de cadastrar Widget, Campos, Colunas, Dashboard e Itens um a um, descreve-se o resultado esperado e revisa-se o que foi gerado.

Quais os benefícios e/ou ganhos de uso

Reduz o tempo de montagem de um painel novo e o conhecimento prévio exigido sobre a estrutura dos cadastros. Facilita a criação de modelos padronizados para distribuir a vários clientes, já que o mesmo arquivo pode ser importado em qualquer base. Também torna a manutenção mais simples: ajustes no painel são pedidos ao agente e reimportados, sem retrabalho manual nos cadastros.

O que informar ao agente

• Contexto: o que o painel precisa responder e para quem. Ex.: "acompanhamento mensal das receitas emitidas, para a diretoria".
• Expressão SQL: a consulta que traz os dados, já validada no banco. Ela deve ser crua: sem soma, sem agrupamento e sem ordenação — o próprio sistema monta a agregação a partir dos campos escolhidos.
• Colunas da consulta: quais colunas ela devolve e o que cada uma representa (texto, data ou valor).
• Layout: quais itens o painel terá, em que ordem, e o tamanho de cada um na grade de 16 colunas. Ex.: "dois indicadores lado a lado no topo e, abaixo, um gráfico de colunas ocupando a largura toda".
• Formato do arquivo: a especificação do arquivo de importação, que descreve as seções, os campos obrigatórios e os valores aceitos.

Exemplos

O ponto de partida é a consulta. O exemplo abaixo traz as receitas emitidas, uma linha por documento — sem soma e sem agrupamento, como a ferramenta espera:

select TO_CHAR(a.dataemissao, 'Mon') as mes,
       EXTRACT(YEAR FROM a.dataemissao) || '/' ||
       LPAD(EXTRACT(MONTH FROM a.dataemissao)::text, 2, '0') as ano_mes,
       a.valorliquido as valor,
       a.dataemissao
from documentos a
where a.tipomovimento = 'S'
  and a.ehcre = 'S'
  and a.ehaglutinador = 'N'
  and a.situacaofinanceiro = '2'

Ela devolve quatro colunas: mes e ano_mes (texto), valor (valor) e dataemissao (data). Repare que a soma por mês não está na consulta — quem agrupa e soma é o sistema, a partir do campo escolhido como categoria e da coluna de valor do Widget.

Com isso em mãos, o pedido ao agente pode ser:

Monte um dashboard chamado "Receitas Emitidas" com esta consulta.
Quero, no topo, um indicador com o total emitido no período ocupando
metade da largura e, abaixo, um gráfico de colunas com a evolução
mensal usando o ano_mes como categoria, ordenado por ele.
Siga a especificação do formato de importação em anexo.

O agente devolve um único arquivo contendo o dashboard, os dois Widgets, o catálogo de Campos de cada um (com o tipo de cada coluna da consulta) e a Coluna de valor apontando para valor. Basta importar.

Para acrescentar um indicador com a quantidade de documentos, sem mudar o painel, basta pedir uma coluna a mais na consulta — por exemplo 1 as quantidade — e um indicador que some esse campo.

Da mesma forma, a partir de uma consulta que devolve centro de custo, valor e data, pede-se um painel de participação: o agente monta um gráfico de pizza com o percentual de cada centro de custo e um gráfico de barras com o ranking em valor.

Como Utilizar

Esta seção resume o que precisa ser feito para construir um dashboard com o apoio de um agente de IA.

Escreva e teste a Expressão SQL no banco, conferindo as colunas que ela devolve. Reúna o contexto e o layout desejado, e entregue ao agente junto com a especificação do formato do arquivo. Revise o arquivo devolvido, principalmente a consulta e os campos utilizados em cada Widget. No cadastro de Dashboards, use o botão Importar e selecione o arquivo. Se a importação apontar problemas, devolva a mensagem ao agente e peça a correção — ela indica exatamente o item, o Widget e o campo de cada pendência. Abra o dashboard e confira os números antes de liberar para os usuários.

Comportamentos

• Validação antes de gravar: a importação confere o arquivo inteiro antes de criar qualquer registro. Havendo problema, nada é importado e é apresentada a lista completa das correções necessárias, numerada e identificando o item e o Widget de cada uma.
• Correção em ciclo: as mensagens de erro são escritas para serem devolvidas ao agente — ele corrige o arquivo e a importação é repetida, até o painel entrar sem pendências.
• Cria ou atualiza: os registros são identificados pelo Nome. Reimportar um arquivo corrigido atualiza o dashboard existente, sem duplicar itens nem Widgets.

Pontos de atenção

• Revise a consulta gerada. A Expressão SQL roda no banco do cliente. Um agente pode propor junções ou filtros que não refletem a regra do seu negócio — a conferência de quem conhece a operação continua sendo necessária.
• Confira os números. Antes de publicar, compare o resultado do painel com um relatório já conhecido. O arquivo pode estar formalmente correto e ainda assim somar a coluna errada.
• Indicador sempre soma. Um indicador totaliza o campo escolhido. Média e maior valor não saem de um indicador — quando necessário, isso precisa vir resolvido dentro da própria consulta.
• Formulário de filtro. Se o painel usar filtro, o Formulário vinculado precisa existir na base de destino antes da importação.
• Nomes são a chave. Como a importação identifica os registros pelo Nome, escolha nomes estáveis e específicos para dashboards e Widgets, evitando que um modelo sobrescreva outro por coincidência de nome.
• Dados sensíveis. Quem tem permissão para ver o dashboard vê o resultado da consulta. Isso não muda por o arquivo ter sido gerado por um agente.

Conclusão

A construção de dashboards com o apoio de um agente de IA aproveita o fato de o painel inteiro poder ser descrito por um arquivo de importação. O agente traduz contexto, consulta e layout nesse arquivo; o ERP valida e cria os registros. O ganho está na velocidade de montagem e na padronização dos modelos, mantendo com quem conhece o negócio a responsabilidade de revisar a consulta e conferir os números.

Assuntos Relacionados

Dashboards

Widgets

Layout Importação Dashboards