Admin: /* Conclusão */

2026-09-13T20:59:33Z

‎Conclusão

Admin em 20h59min de 13 de setembro de 2026

2026-09-13T20:59:07Z

Admin: Criou página com '==='''Conceito'''=== Esta página descreve o formato dos arquivos de exportação e importação de dashboards e widgets. Serve de referência para quem precisa gerar esses ar...'

2026-09-13T20:58:19Z

Criou página com '==='''Conceito'''=== Esta página descreve o formato dos arquivos de exportação e importação de dashboards e widgets. Serve de referência para quem precisa gerar esses ar...'

Página nova

==='''Conceito'''===
Esta página descreve o formato dos arquivos de exportação e importação de dashboards e widgets. Serve de referência para quem precisa gerar esses arquivos fora do sistema — inclusive para orientar um agente de IA (veja Assuntos Relacionados).

==='''Os arquivos'''===
São dois arquivos no formato JSON, ambos gravados em UTF-8, lidos pelos botões Importar dos respectivos cadastros.

{| class="wikitable"
!Arquivo
!Extensão
!Cadastro
|-
|'''Dashboard'''
|.phdashapp
|Dashboards
|-
|'''Widget avulso'''
|.phwidget
|Widgets
|}

O arquivo de dashboard já traz os widgets embutidos: importar um dashboard cria ou atualiza também os widgets que ele utiliza, o catálogo de Campos de cada um e os Filtros do Item.

==='''Regras gerais'''===
*'''Identificação pelo Nome:''' a importação cria o que não existe e atualiza o que existe. O dashboard é identificado pelo '''nome'''; o widget pelo '''nome''' mais o '''tipoWidget'''; o item pela '''sequencia''' dentro do dashboard; a série pela '''sequencia''' dentro do widget. Reimportar o mesmo arquivo atualiza no lugar, sem duplicar.
*'''Validação antes de gravar:''' o arquivo é conferido por inteiro antes de qualquer gravação. Havendo problema, nada é importado e é devolvida a lista completa das correções, numerada e identificando o item e o widget de cada uma.
*'''Formulário:''' quando o dashboard tem filtro, o Formulário é referenciado pelo nome e precisa já existir na base de destino — ele não vai dentro do arquivo.
*'''Cores:''' aceitam o formato #RRGGBB ou o número inteiro usado pelo sistema. Em branco, vale a cor padrão do tema.

===='''Campos omitidos'''====
Campo que não for informado grava o padrão abaixo. Não é necessário repetir as opções que valem "não".

{| class="wikitable"
!Campo
!Padrão
|-
|'''tipoSerie'''
|F (série fixa). Somente D liga a série dinâmica.
|-
|'''posicaoLegenda'''
|D (direita).
|-
|'''exibirTitulo''', '''exibirValores''', '''destacarDiferenca''', '''exibirFundoBarra''', os quatro '''arredondamento''', '''exibirPercentual'''
|N
|-
|'''ehSistema''' (dashboard, item, widget, campo e filtro)
|N
|-
|'''titulo''' do item
|O título do widget daquele item.
|}

==='''Arquivo de dashboard'''===
<pre>
{
"versao": 2,
"nome": "DASH_RECEITAS",
"legenda": "Receitas",
"ehSistema": "N",
"formulario": "",
"itens": [
{
"sequencia": 1,
"titulo": "",
"altura": 7,
"largura": 16,
"ehSistema": "N",
"widget": { },
"filtros": []
}
]
}
</pre>

{| class="wikitable"
!Campo
!Regra
|-
|'''nome'''
|Obrigatório. É a chave de importação.
|-
|'''legenda'''
|Obrigatória. Texto exibido ao usuário.
|-
|'''formulario'''
|Nome de um Formulário existente na base. Obrigatório quando algum item tiver filtros; em branco para dashboard sem filtro.
|-
|'''itens'''
|Ao menos um item.
|-
|'''itens.sequencia'''
|Maior que zero e única dentro do dashboard.
|-
|'''itens.largura'''
|De 1 a 16 colunas da grade.
|-
|'''itens.altura'''
|Maior que zero, em linhas da grade.
|-
|'''itens.titulo'''
|Em branco assume o título do widget.
|-
|'''itens.widget'''
|O widget completo, no mesmo formato do arquivo avulso.
|}

===='''Filtro do item'''====
Liga um campo do Formulário do dashboard a um Campo do widget daquele item.

<pre>
{"formularioCampo": "DATAINICIAL", "widgetCampo": "DATAEMISSAO", "operacao": 3, "ehSistema": "N"}
</pre>

{| class="wikitable"
!Operação
!Significado
|-
|1
|Igual
|-
|2
|Diferente
|-
|3
|Maior ou igual
|-
|4
|Menor ou igual
|-
|5
|Contém
|-
|6
|Está na lista
|}

O '''formularioCampo''' precisa existir no Formulário do dashboard, e o '''widgetCampo''' precisa estar em '''campos''' do widget daquele item.

==='''Arquivo de widget'''===
<pre>
{
"versao": 2,
"nome": "REC_EVOLUCAO_MENSAL",
"tipoWidget": 1,
"titulo": "Evolução Mensal das Receitas",
"exibirTitulo": "S",
"tamanhoFonteTitulo": 14,
"ehSistema": "N",
"expressaoSQL": "select ... from documentos a where ...",
"campos": [
{"nome": "ANO_MES", "tipoCampo": 1, "formato": "", "ehSistema": "N"},
{"nome": "DATAEMISSAO", "tipoCampo": 2, "formato": "", "ehSistema": "N"},
{"nome": "VALOR", "tipoCampo": 3, "formato": "###,##0.00", "ehSistema": "N"}
],
"grafico": { }
}
</pre>

{| class="wikitable"
!Campo
!Regra
|-
|'''nome'''
|Obrigatório. Chave de importação junto com o tipoWidget.
|-
|'''tipoWidget'''
|1 para gráfico (preenche a seção grafico) ou 2 para indicador (preenche a seção indicador).
|-
|'''expressaoSQL'''
|Obrigatória e crua: sem soma, sem agrupamento e sem ordenação. A agregação é montada pelo sistema a partir do campoX, do campoSerie e das colunas.
|-
|'''campos'''
|Catálogo das colunas devolvidas pela consulta. Ao menos um, sem nomes repetidos. Todo campo citado em campoX, campoSerie, campoOrdenacao, colunas, indicador e nos filtros precisa estar aqui.
|-
|'''campos.tipoCampo'''
|1 texto, 2 data, 3 valor.
|-
|'''campos.formato'''
|Máscara de exibição, como ###,##0.00. É ela que formata o rótulo do gráfico e o número do indicador.
|}

===='''Seção grafico'''====
<pre>
"grafico": {
"tipoGrafico": "BH",
"campoX": "ANO_MES",
"campoSerie": "",
"campoOrdenacao": "ANO_MES",
"tipoSerie": "",
"exibirValores": "S",
"escala": 0,
"destacarDiferenca": "N",
"tamanhoFonteX": 13,
"posicaoLegenda": "D",
"corBarra": "#3E3E3E",
"corFundoBarra": "#FBF1E6",
"exibirFundoBarra": "S",
"arredondamentoInicial": "S",
"arredondamentoFinal": "S",
"arredondamentoFundoInicial": "N",
"arredondamentoFundoFinal": "S",
"colunas": [
{"sequencia": 1, "legenda": "Valor", "campoValor": "VALOR",
"corFonteValor": "", "corFonteValor2": "#FFFFFF", "exibirPercentual": "N"}
]
}
</pre>

{| class="wikitable"
!Campo
!Regra
|-
|'''tipoGrafico'''
|BH para colunas verticais, BV para barras horizontais, LI para linhas e PI para pizza.
|-
|'''campoX'''
|Obrigatório. É a categoria do eixo.
|-
|'''campoSerie'''
|Usado apenas com tipoSerie D: cada valor distinto do campo vira uma série.
|-
|'''campoOrdenacao'''
|Ordena as categorias por este campo, em vez da ordem alfabética.
|-
|'''tipoSerie'''
|D para série dinâmica, que exige o campoSerie. Em branco, as séries são as informadas em colunas.
|-
|'''exibirValores'''
|S mostra o valor em cada ponto, E mostra a escala no eixo e N não mostra nenhum.
|-
|'''posicaoLegenda'''
|T, B, E, D ou I. Somente o gráfico de pizza desenha legenda.
|-
|'''colunas'''
|Ao menos uma série. A sequencia é maior que zero e única, e o campoValor é obrigatório e precisa ser um campo do tipo valor.
|-
|'''colunas.exibirPercentual'''
|S exibe o percentual sobre o total da série, em vez do valor.
|}

===='''Seção indicador'''====
<pre>
"indicador": {
"campoValor": "VALOR",
"corFundo": "#D66815",
"corValor": "#FFFFFF",
"corDestaque": "#EFA55F",
"corIdentificacao": "#FFFFFF"
}
</pre>

O '''campoValor''' é obrigatório, precisa estar em '''campos''' e ser do tipo valor — é o campo somado no cartão. O formato exibido vem do formato desse campo.

{| class="wikitable"
!Campo
!Aplica-se a
|-
|'''corFundo'''
|Fundo do cartão.
|-
|'''corValor'''
|Número em destaque.
|-
|'''corIdentificacao'''
|Rótulo acima do número.
|-
|'''corDestaque'''
|Realce do cartão.
|}

O indicador sempre soma o campo escolhido. Média, contagem ou maior valor precisam vir resolvidos dentro da própria consulta — uma coluna 1 as quantidade, por exemplo, quando somada resulta na contagem de linhas.

==='''Mensagens de erro'''===
Quando o arquivo tem problemas, nada é importado e a mensagem traz todos de uma vez:

<pre>
Não foi possível importar o dashboard. 3 problemas encontrados:
1) item 1 (widget "REC_EVOLUCAO_MENSAL"): "grafico.campoX" "ANOMES" não está
em "campos". Todo campo usado precisa estar catalogado lá.
2) item 2 (widget "REC_POR_CC"): "grafico.colunas[0].campoValor" "CENTROCUSTO"
precisa ser do tipo valor ("tipoCampo": 3) em "campos", e está como 1.
3) item 2 (widget "REC_POR_CC"): "sequencia" 1 já foi usada em outro item --
ela identifica o item no dashboard.
</pre>

==='''Conclusão'''===
O formato descreve o dashboard por inteiro: itens, widgets, catálogo de Campos, séries de valor e filtros. Por ser texto estruturado com regras conhecidas e validação completa na importação, o mesmo arquivo pode ser gerado fora do sistema, revisado e aplicado em qualquer base.

'''Assuntos Relacionados'''

[[Dashboards]]

[[Widgets]]

[[Dashboards com IA]]

← Edição anterior		Edição das 20h59min de 13 de setembro de 2026
Linha 292:		Linha 292:
	[[Widgets]]		[[Widgets]]

−	[[Criando_Dashboards_com_IA]]	+	[[Criando_Dashboards_com_IA\|Criando Dashboards com IA]]

← Edição anterior		Edição das 20h59min de 13 de setembro de 2026
Linha 292:		Linha 292:
	[[Widgets]]		[[Widgets]]

−	[[~~Dashboards com IA~~]]	+	[[Criando_Dashboards_com_IA]]

Layout Importação Dashboards - Histórico de revisão

Admin: /* Conclusão */

Admin em 20h59min de 13 de setembro de 2026

Admin: Criou página com '==='''Conceito'''=== Esta página descreve o formato dos arquivos de exportação e importação de dashboards e widgets. Serve de referência para quem precisa gerar esses ar...'