PHSYS - Wiki - Contribuições do(a) usuário(a) [pt-br]

Instalação do Serviço PHSServer

2026-09-14T22:30:02Z

Admin:

O PHSServer é o serviço da aplicação que fica junto ao servidor e é responsável pelo controle de acessos e execução das regras de negócio solicitadas via interfaces Desktop, Mobile ou Web.

Para instalação, são necessários os seguintes arquivos:

*'''PHServer.exe:''' Arquivo de execução do serviço no Windows. Para criação do serviço junto aos serviços do Windows, deve executar o arquivo PHServer.exe com o parâmetro -install. Pode ser feito utilizando o CMD como administrador.
*'''PHServer.sqlite:''' Necessário somente quando utilizado banco de dados SQLite para o PHServerConf.
*'''PHSys.Lic:''' Arquivo de licenciamento, que contem as informações com módulos, segmentos e usuários contratos.
*'''Pasta Certificados:''' A pasta '''Certificados''', deve estar presente no mesmo diretório de PHServer.exe, neste devem estar presentes os certificados digitais utilizado na emissão dos documentos eletrônicos.
*'''Pasta Páginas:''' Contém os arquivos utilizados pela interface web do PHServerConf.
{| class="mw-collapsible mw-collapsed wikitable" style="width: 100%"
! colspan = "2" | Estrutura de arquivos do ServerConfWeb
|-
|Arquivos Principais:
|-
|APIs - Contém todos as API's utilizado na construção Web.
|-
|Boostrap - Framework para construção das telas.
|-
|DataTabels - Construção das Grids
|-
|Fontawesome - Ícones.
|-
|GoogleFont - Ícones.
|-
|jQuery - Extensão para utilização no JavaScript.
|-
|Selectize - Utilização de campos lista estilizados para utilização de Ajax para pesquisa.
|-
|SweetAlert2 - Mensagens estilizadas na tela.
|-
|Serverconf - Contém as páginas, arquivos css's e javascripts necessários para abertura do serverconfweb.
|-
|CSS - Arquivos de estilização para o serverconfweb.
|-
|estilo.css - Estilização das telas.
|-
|estilologin.css - Estilização da tela de login.
|-
|Imagens - Contém os ícones do sistema utilizados nas páginas do serverconfweb.
|-
|JS - Arquivos js necessários.
|-
|PH_Script_ServerConf.js - Script para comunicação com o servidor e tratamentos dos campos.
|-
|PH_Script_ServerConf_Login.js - Script para criação da sessão e validação do login.
|-
|basedados.html - Tela de base de dados.
|-
|login.html - Tela de login.
|-
|servidores.html - Tela de servidores de banco.
|-
|usuarios.html - Tela de usuários do serverconf.
|}

*'''Parametros.ini:''' Contém os parâmetros necessários para instalação e inicialização do serviço da aplicação. Estrutura padrão do arquivo ini:
'''[CONEXAO]'''
Servidor=LOCALHOST
Porta=211
SSLCERTFILE=
SSLPRIVATEKEYFILE=
SSLPRIVATEKEYPASSOWORD=

'''[PARAMETROS]'''
NomeServico=PHSServer
DescricaoServico=PH Sys - Server
'''[CONEXAOBASESDADOS]'''
TipoConexao=4
Servidor=LOCALHOST
Porta=5233
DataBase=serverconf
Usuario=usuario
Senha=*****

O '''tipo de conexão''' corresponde ao banco de dados utilizado, pode ser:
:0 - SQLite
:1 - SQLServer
:2 - Oracle
:3 - Firebird
:4 - PostGreSQL

==='''DLL's'''===

*libcrypto-1_1.dll ou libcrypto-1_1-x64.dll
*libssl-1_1.dll ou libssl-1_1-x64.dll
*libexslt.dll
*libiconv.dll
*libssl-1_1.dll
*libxml2.dll
*libxslt.dll

*Clientes que utilizam banco de dados '''Firebird''':
**fbclient.dll

*Clientes que utilizam banco de dados '''PostGreSQL''':
**Lib\libcrypto-1_1-x64.dll
**Lib\libiconv-2.dll
**Lib\libintl-8.dll
**Lib\libpq.dll
**Lib\libssl-1_1-x64.dll
**Lib\ssleay32.dll

*Clientes que utilizam agendamento de e-mails por '''IMAP''', ou '''SSL''' em '''x32''':
**dlls - Openssl - 32bits\libeay32.dll
**dlls - Openssl - 32bits\ssleay32.dll
**dlls - Openssl - 32bits\libcrypto-3.dll
**dlls - Openssl - 32bits\libssl-3.dll

*Clientes que utilizam agendamento de e-mails por '''IMAP''', ou '''SSL''' em '''x64''':
**libeay32.dll
**ssleay32.dll

==='''Pastas de Schemas'''===
Para os clientes que realizam a geração de documentos eletrônicos como NF-e, CT-e, CFS-e ou MDF-e, são necessárias os arquivos disponibilizados nas pasta abaixo:
*Schemas_CTE
*Schemas_MDFE
*Schemas_NFE
*Schemas_NFSE

Dashboards

2026-09-13T21:00:25Z

Admin: /* Conclusão */

==='''Conceito'''===
O Dashboard é a funcionalidade do sistema que reúne, em um único painel visual, indicadores e gráficos configuráveis, permitindo o acompanhamento rápido de informações relevantes do negócio sem a necessidade de gerar relatórios manualmente. Cada dashboard é composto por um conjunto de itens — cada um exibindo um Widget do tipo indicador numérico (card) ou gráfico (barra, linha ou pizza) — organizados em um layout de grade dentro da tela.

==='''O que é'''===
O Dashboard é uma tela de visualização somente leitura, formada por blocos (itens) distribuídos em grade. Cada item exibe o resultado de um Widget previamente configurado no sistema, que pode assumir dois tipos:
*'''Indicador (card):''' exibe um único valor em destaque, geralmente representando uma contagem, total.
*'''Gráfico:''' exibe uma série de dados no formato de barra, linha ou pizza.

A montagem do dashboard (quais itens existem, em que ordem, com que tamanho e com que Widget) é feita previamente pelos cadastros de '''Dashboard''', '''Itens do Dashboard''' e '''Widget'''. A tela do Dashboard em si apenas exibe o resultado já configurado — não é nela que se adiciona, remove ou redimensiona itens. Cada item é alimentado por uma consulta SQL própria (Expressão SQL), definida no cadastro do Widget correspondente. Opcionalmente, um Dashboard pode ter um Formulário vinculado, permitindo ao usuário filtrar os dados exibidos sem precisar de um novo cadastro.

==='''Para que serve'''===
Quando compreendemos a funcionalidade do Dashboard, conseguimos acompanhar de forma visual e centralizada os principais números da operação, tomando decisões com mais agilidade e sem depender da geração manual de relatórios para obter uma visão geral da situação atual.

==='''Quais os benefícios e/ou ganhos de uso'''===
Ao concentrar as informações mais relevantes em um único painel visual, o usuário reduz o tempo gasto navegando por diferentes telas e relatórios para entender a situação do negócio. Isso favorece a identificação rápida de tendências, desvios e pontos de atenção, além de padronizar a forma como diferentes usuários enxergam os mesmos indicadores, evitando interpretações divergentes sobre os mesmos dados.

==='''Exemplos'''===
Um dashboard pode reunir, por exemplo, um Widget indicador com o total de pedidos em aberto, um Widget gráfico de barras com o volume de vendas por período e um Widget gráfico de pizza com a participação de cada categoria de produto no faturamento. Dessa forma, em uma única tela, o usuário consegue visualizar tanto números pontuais quanto tendências ao longo do tempo.

==='''Cadastro'''===
O Dashboard é composto por dois cadastros: o Dashboard propriamente dito e os Itens do Dashboard. Cada item, por sua vez, exibe um Widget já cadastrado (do tipo Gráfico ou Indicador) — o cadastro do Widget (onde entram título, cores, formato e a Expressão SQL) é tratado em página própria (veja Sugestão de Leitura).

'''Dashboard'''
*'''Nome:''' Nome interno do dashboard, utilizado também como identificador ao exportar/importar sua configuração.
*'''Legenda:''' Subtítulo/legenda exibida para o usuário.
*'''Formulário:''' Formulário (tela de filtro) opcional vinculado ao dashboard. Quando informado, a tela de Dashboard passa a exibir o botão "Filtrar", permitindo restringir os dados exibidos nos itens configurados com Filtros do Item (veja abaixo).
*'''Data/Hora:''' Data e horário da última alteração. Preenchido automaticamente pelo sistema.
*'''É Sistema:''' Indica se o dashboard é nativo do sistema (padrão) ou foi criado pelo usuário.

'''Itens do Dashboard'''
*'''Dashboard:''' Dashboard ao qual o item pertence.
*'''Sequência:''' Posição/ordem do item dentro do dashboard.
*'''Nome:''' Nome interno do item.
*'''Título:''' Título exibido no topo do item. Quando deixado em branco, o item assume o título configurado no próprio Widget.
*'''Altura:''' Altura do item na grade do dashboard.
*'''Largura:''' Largura do item na grade do dashboard (a grade possui 16 unidades de largura por linha; itens são distribuídos lado a lado até completar esse limite, quebrando para a linha seguinte quando necessário).
*'''Widget:''' Widget já cadastrado (do tipo Gráfico ou Indicador) a ser exibido neste item.
*'''Filtros do Item:''' Disponível apenas quando o Dashboard tem um Formulário vinculado. Mapeia cada campo do Formulário para um Campo já catalogado (via "Incluir Campos") do Widget deste item, definindo a operação a aplicar (igual, diferente, maior ou igual, menor ou igual, contém, está na lista) quando o usuário preencher aquele campo no filtro. Um campo do Formulário sem mapeamento fica disponível para preenchimento, mas não afeta a consulta deste item específico.
*'''Data/Hora:''' Data e horário da última alteração. Preenchido automaticamente pelo sistema.
*'''É Sistema:''' Indica se o item é nativo do sistema (padrão) ou foi criado pelo usuário.

==='''Comportamentos'''===
*'''Atualizar:''' Permite recarregar o dashboard por completo, buscando novamente a estrutura e os dados de todos os itens.
*'''Carregamento por item:''' Cada item do dashboard é carregado de forma independente: a estrutura visual (títulos, cores, formato) aparece imediatamente, enquanto os dados de cada item são buscados individualmente e exibidos em seguida, com uma animação de entrada.
*'''Indicação de carregamento:''' Enquanto os dados de um item ainda não retornaram, é exibido um indicador de carregamento (spinner) sobre o item.
*'''Sem dados / Erro ao carregar:''' Caso a consulta de um item não retorne dados, ou ocorra uma falha ao buscá-los, o item exibe uma mensagem informando a situação, sem impedir a exibição dos demais itens do dashboard.
*'''Distribuição em grade:''' Os itens são organizados automaticamente em uma grade de 16 colunas, respeitando a largura e altura configuradas em cada item, se ajustando ao tamanho da tela.
*'''Filtrar:''' Quando o dashboard tem um Formulário vinculado, um botão "Filtrar" aparece no topo da tela, abrindo uma janela com os campos configurados. Ao confirmar, todos os itens com Filtros do Item configurados são recarregados considerando os valores informados.
*'''Lembrar filtro:''' Se o Formulário vinculado estiver marcado para "Salvar", o último filtro confirmado pelo usuário é lembrado entre acessos, inclusive reabrindo o dashboard em outro momento. Se essa opção não estiver marcada, o filtro é considerado apenas enquanto a tela permanecer aberta — ao reabrir o dashboard, os campos voltam ao valor padrão configurado no Formulário.
*'''Baixar/Copiar imagem:''' Ao clicar com o botão direito sobre um Widget do tipo gráfico, é possível baixar a imagem gerada (PNG) ou copiá-la para a área de transferência, para uso em outros documentos ou apresentações.
*'''Disponível no aplicativo:''' Os dashboards liberados para o grupo do usuário também são exibidos no aplicativo, com a mesma configuração de itens e o mesmo resultado. A barra superior mostra o dashboard aberto e, havendo mais de um disponível, um botão ao lado permite escolher qual exibir.
*'''Exportar:''' No cadastro de Dashboards, gera um arquivo com a configuração completa do dashboard: seus itens, os Widgets utilizados (com Campos, Colunas e configuração visual) e os Filtros do Item. O Formulário vinculado é referenciado pelo nome, mas não vai dentro do arquivo.
*'''Importar:''' Lê um arquivo gerado pela exportação, no mesmo ambiente ou em outro. Os registros são identificados pelo Nome — dashboard, Widget e Campos — de modo que a importação cria o que ainda não existe e atualiza o que já existe, sem duplicar. Antes de gravar, o arquivo é validado por inteiro: havendo qualquer problema, nada é importado e é apresentada a lista completa das correções necessárias, indicando o item e o Widget de cada uma.
*'''Sem armazenamento temporário (cache):''' Toda abertura ou atualização do dashboard executa novamente, em tempo real, a Expressão SQL de todos os seus itens — não há reaproveitamento de um resultado buscado anteriormente.

==='''Como Configurar um Dashboard'''===
Esta seção resume, o que precisa ser feito para configurar um dashboard.

Cadastre primeiro o '''Widget''' (do tipo Gráfico ou Indicador) que você quer usar no dashboard — é lá que ficam o título, as cores, o formato e a Expressão SQL que busca os dados (veja a página de Widgets em Sugestão de Leitura).
Cadastre o '''Dashboard''', informando nome e legenda.
(Opcional) Para permitir que o usuário filtre os dados do dashboard, cadastre um '''Formulário''' com os campos desejados e vincule-o ao Dashboard.
Cadastre os '''Itens do Dashboard''', vinculando cada item ao Dashboard criado e ao Widget já cadastrado, e definindo seu título, posição e tamanho na grade.
(Opcional) Se o Dashboard tiver um Formulário vinculado, configure em cada Item os '''Filtros do Item''' que devem respeitar o filtro, mapeando o campo do Formulário para o Campo correspondente do Widget.
Abra a tela de Dashboard apontando para o dashboard desejado — os itens cadastrados aparecem automaticamente, cada um já exibindo seu resultado.

Se você recebeu um dashboard pronto em arquivo, todo esse roteiro pode ser substituído pelo botão '''Importar''' no cadastro de Dashboards: o dashboard, seus itens e os Widgets utilizados são criados de uma só vez.

'''Pontos de atenção'''
*Como a Expressão SQL é texto livre, o controle de quem pode ver informações sensíveis num dashboard depende de quem tem permissão para visualizar os Dashboard.
*Ao importar um dashboard que tenha Formulário vinculado, o Formulário precisa existir na base de destino antes da importação — cadastre-o ou importe-o primeiro, senão a importação é recusada informando qual Formulário está faltando.

==='''Conclusão'''===
O Dashboard é o recurso responsável por consolidar, em uma única tela, os principais indicadores e gráficos definidos para acompanhamento do negócio. Por ser inteiramente configurável através dos cadastros de Dashboard e Itens — que reaproveitam Widgets já cadastrados, permite que diferentes visões sejam montadas conforme a necessidade de cada área ou perfil de usuário, sem exigir alterações no sistema. Dessa forma, contribui para uma tomada de decisão mais ágil, baseada em informação centralizada e sempre atualizada.

'''Assuntos Relacionados'''

[[Widgets]]

[[Layout_Importação_Dashboards|Layout Importação Dashboards]]

[[Criando Dashboards com IA]]

Criando Dashboards com IA

2026-09-13T20:59:50Z

Admin: /* Conclusão */

==='''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:

<pre>
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'
</pre>

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:

<pre>
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.
</pre>

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 Importação Dashboards|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|Layout Importação Dashboards]]

Layout Importação Dashboards

2026-09-13T20:59:33Z

Admin: /* Conclusão */

==='''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]]

[[Criando_Dashboards_com_IA|Criando Dashboards com IA]]

Layout Importação Dashboards

2026-09-13T20:59:07Z

Admin:

Layout Importação Dashboards

2026-09-13T20:58:19Z

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:50:40Z

Admin: /* Conclusão */

2026-09-12T13:49:21Z

Admin: /* Sugestão de Leitura */

==='''Conceito'''===

A Agenda é a tela que reúne, numa única visão de calendário, os compromissos de cada recurso da empresa. O que ela mostra não é fixo: cada '''Agenda''' cadastrada aponta para um cadastro do sistema e ensina a Agenda a ler aquele cadastro como se fosse um compromisso, dizendo qual campo guarda a data, quais guardam a hora de início e fim, e qual guarda o recurso responsável.

Várias Agendas convivem ao mesmo tempo na mesma tela. Os compromissos de todas aparecem juntos, cada um com a sua cor, e o usuário decide quais quer enxergar pelo filtro.

==='''O que é'''===

É o cadastro que define uma origem de compromissos para a Agenda. Um registro aqui não guarda compromisso nenhum: ele descreve onde os compromissos estão e como devem ser exibidos.

Por isso, incluir uma Agenda nova é trabalho de configuração, não de programação. Cadastros que hoje não aparecem na Agenda podem passar a aparecer desde que tenham data, hora e recurso.

==='''Para que serve'''===

Serve para dar ao usuário uma visão única da ocupação dos recursos, sem que ele precise abrir cada cadastro para descobrir o que está agendado. A partir dessa visão ele consegue:

* enxergar a ocupação de um recurso por dia, semana ou mês, e comparar recursos lado a lado;
* localizar espaço livre antes de assumir um novo compromisso;
* abrir o registro de origem direto pelo compromisso, sem procurar na tela do cadastro;
* incluir um compromisso novo clicando no espaço vazio da agenda.

==='''Quais os benefícios e/ou ganhos de uso'''===

O ganho principal é o compromisso deixar de existir só dentro do cadastro em que foi lançado e passar a disputar espaço na agenda do recurso junto com todos os demais. Quem marca passa a ver o que já está marcado, e a sobrecarga de um recurso fica visível antes de virar atraso.

O segundo ganho é a regra de persistência. Um compromisso cuja situação ainda não foi resolvida continua aparecendo na data de hoje mesmo depois de a data original passar, em vez de ficar para trás no calendário. Ele só sai da frente do usuário quando a situação muda para uma que não persiste, o que transforma a agenda também em lista do que está pendente.

O terceiro é a configuração ser por cadastro. Cada empresa decide o que vira compromisso, com que texto, com que cor e sob que condição, sem depender de versão nova do sistema.

==='''Exemplos'''===

Uma empresa de serviços usa duas Agendas. A primeira lê os apontamentos de ordem de serviço, para o técnico enxergar os atendimentos do dia. A segunda lê as anotações da agenda, usadas para lembretes e retornos a clientes.

Nessa mesma empresa, o apontamento que já virou item de ordem de serviço aparece numa cor própria e não aceita ser arrastado, porque o trabalho já foi registrado. A anotação com situação de pendência continua aparecendo hoje até alguém trocá-la por uma situação concluída.

Uma terceira Agenda pode ser criada para visitas comerciais, apontando para o cadastro de visitas, sem nenhuma alteração de programa.

==='''Cadastro'''===

{| class="wikitable"
!Campo
!Finalidade
|-
|'''Nome'''
|Identificação da Agenda. É por ele que a Agenda é reconhecida ao exportar e importar a configuração entre ambientes.
|-
|'''Legenda'''
|Texto apresentado ao usuário, inclusive na lista de Agendas do filtro.
|-
|'''Cadastro'''
|Cadastro de origem dos compromissos. Define a tabela que a Agenda lê e também qual tela é aberta quando o usuário clica em um compromisso.
|-
|'''Campo Data'''
|Coluna que guarda a data do compromisso. É por ela que a Agenda decide se o registro cai dentro do período exibido.
|-
|'''Campo Hora Início'''
|Coluna com a hora de início. Define onde o card começa na grade de horas.
|-
|'''Campo Hora Fim'''
|Coluna com a hora de término. Define a altura do card na grade de horas.
|-
|'''Campo Recurso'''
|Coluna que liga o compromisso ao recurso responsável. É ela que distribui os compromissos entre as colunas de recurso e que faz valer a permissão de enxergar a agenda de outro recurso.
|-
|'''Título'''
|Expressão que monta o texto principal do card.
|-
|'''Expressão'''
|Expressão que monta o texto complementar, exibido como segunda linha do card quando há espaço.
|-
|'''Condição SQL'''
|Condição adicional aplicada à busca dos compromissos desta Agenda. Serve para restringir o que aparece, por exemplo ignorando registros cancelados.
|-
|'''Expressão Cor'''
|Expressão que devolve a cor do card. Em branco, o card assume a cor do recurso.
|-
|'''Expressão Persistir'''
|Condição que, sendo verdadeira, mantém o compromisso visível na data de hoje depois de a data original passar. Em branco, o compromisso aparece apenas na data dele.
|-
|'''Expressão Leitura'''
|Condição que, sendo verdadeira, trava o compromisso: ele não aceita ser arrastado nem redimensionado na agenda. Em branco, nada é travado.
|-
|'''Margem Direita'''
|Espaço reservado à direita do card no aplicativo, útil quando o card precisa conviver com um ícone.
|-
|'''Máximo de Linhas'''
|Quantidade máxima de linhas do texto complementar no card do aplicativo.
|-
|'''Padrão'''
|Marca a Agenda usada quando o usuário pede um compromisso novo sem partir de um compromisso existente. Somente uma Agenda fica marcada: ao marcar uma, as demais são desmarcadas.
|}

====Sobre as expressões====

As três expressões são escritas em SQL e valem sobre o registro do compromisso, que na consulta recebe o apelido '''A'''. Uma coluna do próprio cadastro é referenciada como ''A.NOMEDACOLUNA''.

Quando a expressão precisa de informação de outra tabela, ela é escrita como subconsulta, e não como junção. Assim a expressão se basta e a Agenda não exige nenhuma configuração adicional de relacionamento.

Funções de data e outras que mudam de nome conforme o banco de dados são escritas com os marcadores do sistema, como ''@DATA'', que são substituídos no momento da consulta. Isso permite que a mesma expressão funcione em qualquer banco homologado.

====Filtros====

Cada Agenda aceita uma lista de filtros, que ligam um campo do formulário de filtro da Agenda a uma coluna do cadastro de origem, com o operador desejado. É assim que um campo novo no formulário passa a filtrar os compromissos, sem alteração de programa.

{| class="wikitable"
!Campo
!Finalidade
|-
|'''Formulário Campo'''
|Campo do formulário de filtro que fornece o valor informado pelo usuário.
|-
|'''Operação'''
|Forma de comparação entre o valor informado e a coluna: igual, diferente, maior ou igual, menor ou igual, contém ou em.
|-
|'''Campo'''
|Coluna do cadastro de origem que será comparada.
|}

Campo do formulário deixado em branco pelo usuário não gera filtro, o que permite um formulário com vários campos sem obrigar o preenchimento de todos. Recurso, Agenda e situação das anotações são filtros próprios da tela e não precisam ser configurados aqui.

==='''Conclusão'''===

Uma Agenda bem configurada resume-se a responder três perguntas: de onde vêm os compromissos, como eles se apresentam e sob que condição continuam exigindo atenção. As duas primeiras são atendidas pelos campos de cadastro e de texto; a terceira, pelas expressões.

Vale rever a configuração sempre que o cadastro de origem ganhar um campo relevante, como uma situação nova, já que a cor e a persistência são consequência do que estiver escrito nas expressões.

2026-08-29T23:40:48Z

Admin: Admin moveu Gráficos para Widgets sem deixar um redirecionamento

==='''Conceito'''===
O cadastro de Gráfico define, de forma reutilizável, a fonte de dados e a aparência de um gráfico que poderá ser exibido em um ou mais itens de um Dashboard. É neste cadastro que fica a consulta SQL responsável por buscar os dados, além de todas as configurações visuais: tipo de gráfico, cores, fontes, legendas e formatação dos valores.

==='''O que é'''===
A tela de cadastro de Gráfico é dividida em duas abas principais: '''Geral''' e '''Expressão SQL'''. Dentro da aba Geral existem ainda duas sub-abas: '''Campo X''' (aparência do eixo/rótulo e da barra ou linha) e '''Colunas''' (os valores exibidos no gráfico). Um mesmo Gráfico, dependendo do Tipo escolhido, também pode ser exibido como um card de indicador em vez de um gráfico tradicional.

==='''Para que serve'''===
Quando compreendemos a funcionalidade do cadastro de Gráfico, conseguimos criar visualizações próprias para acompanhar qualquer informação do sistema, sem depender de um relatório específico, e reaproveitar essa mesma visualização em quantos dashboards forem necessários.

==='''Quais os benefícios e/ou ganhos de uso'''===
Ao centralizar em um único cadastro a consulta e a aparência de um gráfico, diferentes dashboards podem reaproveitar a mesma visualização sem retrabalho, garantindo que todos que a utilizam enxerguem a informação da mesma forma. Isso também facilita ajustes futuros: ao alterar o gráfico uma única vez, a mudança se reflete em todos os dashboards que o utilizam.

==='''Exemplos'''===
Um Gráfico pode ser criado, por exemplo, para exibir em barras verticais o total vendido por vendedor, em linha a evolução de um indicador ao longo de um período, ou em pizza a participação de cada categoria em um total. O mesmo cadastro, se configurado como Indicador, pode ser reaproveitado para mostrar apenas um número em destaque, como o total de pedidos em aberto.

==='''Cadastro'''===
O cadastro de Gráfico é organizado nas abas '''Geral''', '''Campo X''', '''Colunas''' e '''Expressão SQL''', conforme aparecem na tela.

'''Geral'''
*'''Nome:''' Nome interno do gráfico.
*'''Título:''' Título exibido no gráfico.
*'''Tamanho Fonte Título:''' Tamanho da fonte utilizada no título.
*'''Tipo de Gráfico:''' Define o formato de exibição (veja tabela de tipos abaixo).
*'''Exibir o Título:''' Define se o título do gráfico é exibido.
*'''Exibir valores:''' Define se os valores são exibidos junto aos elementos do gráfico.
*'''Data/Hora:''' Data e horário da última alteração. Preenchido automaticamente pelo sistema.

{| class="wikitable" style="width:70%;"
! Tipo de Gráfico
! Descrição
|-
| '''Barra Horizontal'''
| Exibe os valores em barras dispostas horizontalmente.
|-
| '''Barra Vertical'''
| Exibe os valores em barras dispostas verticalmente (colunas).
|-
|-
| '''Linha'''
| Exibe os valores como uma série contínua, indicada para visualizar tendências ao longo de um período.
|-
| '''Pizza'''
| Exibe os valores como percentual de participação em relação ao total.
|}

'''Campo X'''
*'''Campo X:''' Nome da coluna, retornada pela Expressão SQL, utilizada como rótulo/categoria (eixo horizontal).
*'''Tamanho da Fonte:''' Tamanho da fonte utilizado nos rótulos do eixo.
*'''Posição da Legenda:''' Define onde a legenda é exibida (Superior, Esquerda, Direita, Inferior ou Dentro do gráfico).
*'''Cor da Barra ou Linha:''' Cor principal utilizada no gráfico.
*'''Cor do Fundo da Barra:''' Cor de fundo (trilho) desenhada atrás da barra ou linha.
*'''Arredondamento inicial da barra de fundo / Arredondamento inicial da barra:''' Controlam o arredondamento no início da barra e do seu fundo.
*'''Arredondamento final da barra de fundo / Arredondamento final da barra:''' Controlam o arredondamento no final da barra e do seu fundo.
*'''Exibir o fundo da barra:''' Define se o fundo/trilho da barra é exibido.

'''Colunas'''
Cada linha desta grade representa um valor exibido no gráfico:
*'''Sequência:''' Ordem da coluna de valores.
*'''Legenda:''' Texto de legenda associado a esse valor/série.
*'''Campo Valor:''' Nome da coluna, retornada pela Expressão SQL, utilizada como valor numérico.
*'''Cor da Fonte do Valor / Cor da Fonte do Valor (alternativa):''' Cores utilizadas no texto do valor, sendo a segunda aplicada quando o valor é exibido sobre um fundo colorido (dentro da barra ou fatia).
*'''Formato:''' Máscara de formatação numérica aplicada ao valor (ex.: separador de milhar, casas decimais).

'''Expressão SQL'''
Aba onde é escrita a consulta SQL responsável por buscar os dados do gráfico. O resultado dessa consulta deve conter uma coluna com o mesmo nome informado em Campo X (o rótulo) e uma coluna com o mesmo nome informado em Campo Valor, em Colunas.

==='''Como Configurar um Gráfico'''===
Esta seção resume, o que precisa ser feito para deixar um Gráfico pronto para uso em um Dashboard.

# Na aba '''Expressão SQL''', escreva a consulta que retorna os dados desejados. O resultado precisa ter uma coluna para servir de rótulo/categoria e uma coluna com o valor numérico.
# Na aba '''Geral''', informe Nome, Título e escolha o Tipo de Gráfico.
# Na guia '''Campo X''', informe o nome da coluna de rótulo (igual ao nome retornado pela consulta) e configure a aparência: cores, arredondamento, fundo e posição da legenda.
# Na guia '''Colunas''', cadastre a coluna de valor, informando o nome da coluna de valor (igual ao retornado pela consulta), a legenda, a cor e o formato.
# Salve o cadastro. O Gráfico já pode ser selecionado no campo Gráfico de um Item do Dashboard.

'''Ponto de atenção'''
*Os nomes informados em Campo X e em Campo Valor precisam ser exatamente iguais aos nomes das colunas retornadas pela Expressão SQL, ou o gráfico não exibirá dados.

==='''Conclusão'''===
O cadastro de Gráfico é o responsável por definir, em um único lugar, tanto a origem dos dados (a Expressão SQL) quanto a forma como eles são apresentados visualmente. Por ser independente do Dashboard em si, um mesmo Gráfico pode ser reaproveitado em diferentes dashboards, facilitando a manutenção e garantindo consistência visual entre eles.

==='''Sugestão de Leitura'''===
'''Assuntos Relacionados'''

[[Dashboard|Dashboard]]

[[Indicadores|Indicadores]]

Dashboards

2026-08-29T23:39:54Z

Admin: /* Conclusão */

Formulários

2026-08-29T20:03:08Z

Admin: /* Quais os benefícios e/ou ganhos de uso */

==='''O que é'''===

O '''Formulário''' é uma tela dinâmica de coleta de informações, configurada inteiramente via cadastro (sem precisar de programação pra cada caso novo). Cada Formulário é composto por um cabeçalho (nome, legenda, tamanho) e uma lista de campos, onde cada campo é configurado como um registro próprio — com tipo, obrigatoriedade, valor padrão, etc.

O mesmo motor de Formulário é reaproveitado em vários pontos do sistema, tanto no desktop quanto na web: não existe um "Formulário de relatório" e um "Formulário de dashboard" separados — é a mesma engine, o que muda é só onde ela é acionada e o que é feito com os valores preenchidos.

==='''Para que serve'''===

Hoje o Formulário é usado em quatro frentes:

* '''Preenchimento de informações durante um processo:''' Um botão de cadastro pode abrir um Formulário pra pedir dados antes de executar uma rotina (ex: confirmar um período, escolher uma opção, informar uma observação) antes de rodar o script/regra de negócio vinculada ao botão.
* '''Filtro de relatório:''' Um formato de relatório pode ter um Formulário vinculado; os valores preenchidos viram parâmetros disponíveis pra a consulta do relatório.
* '''Filtro de dashboard:''' Um dashboard pode ter um Formulário vinculado; cada campo do Formulário pode ser ligado a uma coluna catalogada de um widget do dashboard (cadastro '''Filtro do Widget do Dashboard'''), o que monta automaticamente a condição de filtro sem precisar mexer na consulta (EXPRESSAOSQL) do widget.
* '''(Em breve) Filtro de Kanban e de Agenda:''' Mesmo mecanismo de filtro do dashboard, aplicado às próximas telas que vão passar a aceitar filtro por Formulário.

==='''Quais os benefícios e/ou ganhos de uso'''===

* Um único motor atende as quatro frentes, quem aprende a montar um Formulário sabe montar pra qualquer um dos usos acima, sem curva de aprendizado nova a cada contexto.
* Campo, tipo, obrigatoriedade e valor padrão são '''configuração''', não programação, reduz a dependência de desenvolvimento pra ajustes pontuais.
* O preenchimento automático de data (Valor Padrão dinâmico, ver Exemplos) evita que o usuário esqueça de ajustar o filtro e acabe analisando um período desatualizado sem perceber, o campo já abre certo, todo dia. Recurso valioso para os dashboards, na qual podemos definir comportamentos de filtro, se a necessidade de informar manualmente um período.
* Um Formulário marcado para "Salvar" o preenchimento evita que o usuário tenha que redigitar o mesmo filtro toda vez que reabre a tela.

==='''Cadastro'''===

'''Formulário''' (cabeçalho)

* '''Nome:''' Identificador único do Formulário, usado internamente pra vincular a um botão de cadastro, formato de relatório ou dashboard.
* '''Legenda:''' Título exibido no cabeçalho da tela/modal do Formulário.
* '''Largura''' / '''Altura:''' Tamanho da tela do Formulário no desktop.
* '''Salvar:''' Quando marcado, o sistema lembra o último valor preenchido por cada usuário em cada campo, e já abre o Formulário preenchido da próxima vez (útil pra filtros repetitivos, como os de relatório/dashboard).
* '''Ajuda:''' Link relacionado à página de ajuda correspondente. Quando informado, é criado um botão de ajuda que serve de atalho para a respectiva página de ajuda.

'''Campo do Formulário''' (um registro por campo)

* '''Nome:''' Identificador do Formulário; é esse nome que aparece como parâmetro disponível pra quem consome o Formulário (relatório, dashboard, botões).
* '''Legenda:''' Rótulo exibido acima do campo pro usuário.
* '''Tipo de Campo:''' Define o tipo de dado e o controle exibido. Principais tipos disponíveis: String, Inteiro, Valor (numérico com casas decimais), Data, Data/Hora, Hora, Lógico (sim/não), Lista de Opções, Radio, Tabela (busca/vínculo a um cadastro), Filtro, Diretório, Imagem.
* '''Sequência:''' Ordem de exibição do campo na tela.
* '''Nova Linha:''' Força o campo a começar sozinho numa linha nova, mesmo sobrando espaço na linha anterior.
* '''Opcional:''' Quando marcado, o campo não é obrigatório pra confirmar o Formulário.
* '''Leitura:''' Torna o campo somente-leitura (exibe o valor mas não permite edição).
* '''É Senha:''' Mascara o valor digitado (usado em campos de texto sensíveis).
* '''Valor Padrão:''' Valor com que o campo já abre preenchido. Além de um valor literal fixo, campos de Data/Data e Hora aceitam uma '''expressão dinâmica''' que é recalculada toda vez que o Formulário é aberto (ver Exemplos abaixo) — é a forma recomendada de propor um período relativo (últimos 30 dias, mês atual, ano atual, etc.) sem deixar uma data fixa "esquecida" na configuração.
* '''Agora:''' Quando marcado (só se aplica a campos de Data/Data e Hora), o campo sempre abre com a data do dia. Tem prioridade sobre o Valor Padrão.
* '''Condição SQL:''' Filtro adicional aplicado à busca de um campo do tipo Tabela/Lista de Opções (ex: restringir a busca a registros ativos, ou de uma filial específica).
* '''Tabela de Pesquisa''' / '''Campo Exibição''' / '''Campo Pai:''' Usados no campo tipo Tabela, definem em qual cadastro buscar, qual coluna mostrar como resultado, e (se aplicável) qual campo pai relaciona a busca a um valor já preenchido em outro campo do mesmo Formulário.
* '''Lista de Opções:''' Grupo de opções (DB_LISTASOPCOES) usado nos tipos Lista de Opções e Radio.
* '''Casas Decimais:''' Quantidade de casas decimais exibidas no tipo Valor.
* '''Mínimo:''' Tamanho mínimo de caracteres aceito (tipo Texto) ou valor mínimo (conforme o tipo).
* '''Vários Registros:''' Permite selecionar mais de um valor no mesmo campo (tipos Tabela/Lista de Opções), tratados como uma lista na hora de aplicar o filtro.
* '''Colunas:''' Colunas exibidas na grade de busca do campo tipo Tabela.

''Por padrão, não adicionamos imagens/figuras ao processo de documentação.''

==='''Exemplos'''===

'''Sintaxe dinâmica de data no Valor Padrão'''

Um campo de Data ou Data/Hora aceita, no Valor Padrão, a expressão <code>[DATA;TIPO;VARIAÇÃO]</code>, resolvida pra uma data real toda vez que o Formulário é aberto — o campo nunca fica "parado" numa data antiga.

{| class="wikitable"
|-
! Tipo !! Significado !! Variação
|-
| D || Variação em dias || quantidade de dias a somar/subtrair de hoje
|-
| MP || Primeiro dia do mês, variando mês a mês || quantidade de meses a deslocar antes de tomar o 1º dia
|-
| MU || Último dia do mês, variando mês a mês || quantidade de meses a deslocar antes de tomar o último dia
|-
| AP || Primeiro dia do ano, variando ano a ano || quantidade de anos a deslocar antes de tomar o 1º dia
|-
| AU || Último dia do ano, variando ano a ano || quantidade de anos a deslocar antes de tomar o último dia
|}

Exemplos de resultado (tomando "hoje" como uma data qualquer de referência):

* <code>[DATA;D;0]</code> → hoje
* <code>[DATA;D;-30]</code> → hoje menos 30 dias
* <code>[DATA;MP;0]</code> → primeiro dia do mês atual
* <code>[DATA;MU;0]</code> → último dia do mês atual
* <code>[DATA;MP;-1]</code> → primeiro dia do mês passado
* <code>[DATA;AP;0]</code> → primeiro dia do ano atual
* <code>[DATA;AU;0]</code> → último dia do ano atual

'''Formulário como filtro de período de um dashboard'''

Um Formulário com dois campos de Data — "Data Inicial" (Valor Padrão <code>[DATA;D;-30]</code>) e "Data Final" (Valor Padrão <code>[DATA;D;0]</code>) — vinculado a um dashboard, sempre abre propondo "os últimos 30 dias até hoje", sem que ninguém precise lembrar de ajustar manualmente. Cada um desses dois campos é então ligado, no cadastro de Filtro do Widget do Dashboard, à coluna do widget que representa a data (uma condição "maior ou igual" pra Data Inicial, "menor ou igual" pra Data Final) — um período é sempre modelado como duas condições simples, não como um único campo de intervalo.

==='''Conclusão'''===

O Formulário é a peça que conecta processos, relatórios e dashboards a uma tela de coleta configurável — sem depender de programação pra cada tela nova. Dominar a criação de um Formulário (tipos de campo, valor padrão, condição SQL) aproveita pras quatro frentes de uso atuais e futuras (processo, relatório, dashboard, e em breve Kanban/Agenda).

'''Assuntos Relacionados'''

[[Dashboards|Dashboards]]