1. Visão Geral do Sistema

A aplicação foi criada para centralizar dados de programação de produção, consolidar informações de uma ou mais fontes, exibir indicadores operacionais e apoiar a tomada de decisão em tempo real.

Em termos práticos, o fluxo principal da ferramenta e este: a fonte e configurada, os dados são sincronizados para dentro do sistema, o dashboard passa a refletir os registros importados e, por cima disso, entram filtros, visões, alertas, relatórios e KPIs personalizados.

Menus mais importantes: Dashboard, Fontes de Dados, Importações, Configurações, Relatórios e Logs.

2. Primeiros Passos

O primeiro passo e validar se a fonte certa esta cadastrada em Fontes de Dados. Cada fonte pode representar um CSV de rede, um banco, uma API, um JSON ou outro conector suportado.

Depois disso, teste a conexão, confira a frequência de sincronização, execute uma sincronização manual e valide o resultado em Importações. So depois vale a pena ajustar dashboard, KPIs e filtros, porque esses recursos dependem dos dados estarem consistentes.

3. Dashboard e Filtros

O Dashboard e o painel principal da operação. Ele mostra cards de KPI, graficos e listas de apoio. Os filtros do topo aplicam o recorte em tempo real sobre os dados ja importados para o banco.

Os filtros podem considerar período, processo, recurso, fonte de dados, status, unidade de atraso e busca textual. A página foi ajustada para reaplicar automaticamente quando o usuário muda um campo, sem necessidade de clicar em um botao de confirmar.

Regra importante: o dashboard não consulta o CSV diretamente a cada clique. Ele consulta os dados ja sincronizados no sistema. Por isso, quando um número parece diferente do arquivo bruto, o primeiro ponto a revisar e a última importação da fonte e as regras de deduplicação, mapeamento e status.

4. Fontes, Mapeamentos e Sincronização

Em Fontes de Dados você cadastra a origem de cada conjunto de informações. Para CSV, normalmente entram o caminho do arquivo, encoding, delimitador, configurações de parser e frequência de sincronização.

Cada fonte possui ação de testar, sincronizar e pausar. A data de última sincronização mostra quando os dados foram trazidos para dentro do sistema. Se o arquivo mudar na rede mas a sincronização não rodar, o dashboard continuara mostrando o retrato anterior.

Se a fonte estiver com deduplicação ativa, registros considerados repetidos são reduzidos antes da gravação. Essa configuração deve ser usada com critério, principalmente quando o CSV bruto possui multiplas linhas válidas para a mesma OP.

4.1 Campo logico x Coluna do CSV

Campo logico e o nome interno usado pelo sistema (ex.: numero_op, processo, setor). Coluna de origem e o nome real da coluna no CSV.

O mapeamento conecta esses dois mundos. Exemplo: campo logico setor pode apontar para a coluna Origem Economica da OP em uma fonte e para outra coluna em outra fonte.

4.2 Como mapear corretamente

Passo 1: abra Fontes de Dados e entre em Mapeamentos da fonte certa.

Passo 2: informe o campo logico.

Passo 3: selecione a coluna de origem do CSV.

Passo 4: salve o mapeamento.

Passo 5: execute Sincronizar para recarregar os registros com a nova regra.

4.3 Renomear campo logico existente

Na lista de mapeamentos da fonte, clique em Editar. Você pode alterar o campo logico sem remover e recriar a linha.

Importante: se o nome informado ja existir para a mesma fonte, o sistema bloqueia para evitar duplicidade de chave lógica.

4.4 Criar campo logico novo

O campo logico aceita digitação livre. Entao você pode criar campos técnicos novos como data_impressao_op, grupo_planejamento ou linha_fabril.

O sistema normaliza automaticamente para snake_case. Exemplo: Data Impressao OP vira data_impressao_op.

Esse dado customizado fica disponivel no payload_json dos registros importados.

4.5 Lista automatica de colunas do CSV

Na tela de mapeamento, o campo Coluna de Origem lista automaticamente o cabeçalho do CSV, para o usuário apenas selecionar.

Se o arquivo estiver indisponivel (caminho invalido, rede fora, permissão), o sistema volta para digitação manual e exibe a mensagem de motivo.

4.6 Regras auxiliares do mapeamento

Transformação: ajuste de formato (ex.: data e decimal) antes de gravar.

Obrigatorio: indica coluna crítica para governança de dados.

Visivel: controla exibição de referencia nas telas administrativas.

4.7 O que muda no dashboard depois do mapeamento

O dashboard não le o CSV em tempo real. Ele le o banco ja sincronizado. Por isso, mapear sem sincronizar não altera KPI imédiatamente.

Regra prática: Mapear -> Sincronizar -> Validar no Dashboard. Se um KPI ficar zerado, primeiro confirme se o campo esta mapeado na fonte filtrada e se esse campo veio preenchido após a carga.

5. Importações e Validação

A tela de Importações registra cada carga executada, com status, quantidade de linhas e horário. Ela e o melhor lugar para responder perguntas como: "a importação rodou?", "quantas linhas entraram?" e "houve falha?".

Boa prática operacional: antes de discutir um número do dashboard, confirme a última importação da fonte ligada a esse indicador. Se a importação falhou, ficou parcial ou usou uma regra de deduplicação forte, o KPI herdara essa diferença.

6. Alertas e Insights

Os menus Alertas e Insights trabalham em cima dos dados ja consolidados. Alertas ajudam a detectar situações críticas; insights ajudam a interpretar padrões operacionais.

Esses módulos não substituem a leitura da base, mas ajudam o usuário a chegar mais rápido ao que importa: atrasos, gargalos, desvios de eficiencia e excesso de carga em processos e recursos.

7. Relatórios, Usuários e Logs

Relatórios servem para distribuição e evidências. Usuários definem quem pode acessar o que. Logs são a trilha de auditoria para entender eventos, falhas e execuções.

Sempre que uma configuração importante mudar, especialmente em fontes, regras de status ou KPIs, vale registrar a intenção da mudança e depois verificar os logs caso algum número saia do esperado.

8. Editor de KPIs do Dashboard

O editor fica em Configurações, na seção Mapeamento dos Cards do Dashboard. E nessa tela que você controla quantos cards o dashboard vai exibir e como cada card sera calculado.

O editor agora permite criar quantos KPIs você quiser. Cada linha da grade representa um card. Você pode adicionar novos cards, remover cards que não fazem mais sentido e mudar a ordem de exibição.

8.1 Campos do editor

Título: e o texto mostrado no card. Você pode escrever um nome fixo, como Total de OPs Críticas, ou usar os placeholders {field_label} e {field}.

Campo: define o campo base do card. Quando a fórmula usa field, esse valor e substituido automaticamente pelo campo escolhido aqui.

Importante sobre campos customizados: campos logicos novos criados no mapeamento são importados, mas o seletor padrão de campo do editor de KPI segue os campos nativos da tela. Se precisar usar campo customizado em KPI, valide antes o comportamento esperado com a equipe técnica.

Valor Fixo: e um valor auxiliar digitado manualmente no proprio editor. Ele pode ser usado dentro da fórmula como fixed_value ou valor_fixo. Esse campo aceita número, texto e data, como 100, ABERTA ou 05/05/2026.

Fórmula: define o calculo. Pode usar valores fixos, agregações, condições e fórmulas estilo Excel.

Formato: controla como o valor sera exibido no card, por exemplo número inteiro, decimal ou percentual.

Ícone: recebe um nome de ícone Bootstrap Icons, como bi-activity, bi-speedometer2 ou bi-exclamation-triangle.

Link: opcional. Quando preenchido, o card fica clicável e pode levar o usuário para outra tela, como /programacao?status=ABERTA.

Tom: define o estilo visual do card. Use normal para leitura neutra e alerta quando quer destacar uma situação crítica.

Cor Texto: permite trocar a cor do texto do card. Pode usar valores como #e5eefb, #67e8f9 ou var(--text-main).

8.2 Ações disponiveis no editor

Adicionar KPI: cria uma nova linha para um novo card.

Mover para cima / baixo: altera a ordem de exibição dos cards no dashboard.

Remover KPI: exclui a linha do editor antes de salvar.

Salvar Mapeamento dos Cards: grava a configuração atual no sistema. O dashboard passa a usar a nova grade a partir da próxima carga da página.

8.3 Como criar um KPI simples

Exemplo: você quer um card com total de OPs distintas. Crie um novo KPI, use o título Total de OPs, selecione o campo numero_op, informe a fórmula distinct(field), formato Numero e um ícone como bi-list-task.

8.4 Como criar um KPI com valor fixo

Se você quiser um card com meta ou referencia fixa, isso também e suportado. Exemplo: título Meta de Eficiencia, fórmula 95, formato Percentual. O card vai mostrar 95.0%.

Agora existe também um uso mais poderoso: o campo Valor Fixo pode servir como apoio para comparações. Exemplo: no campo Valor Fixo você digita 05/05/2026 e, na fórmula, usa =SE(MAX(data_programacao)>fixed_value;1;0). Nesse caso, o sistema compara a maior data encontrada com a data digitada manualmente.

Regra prática: use fórmula fixa, como 95, quando o proprio resultado do card deve ser constante. Use Valor Fixo quando você precisa de um parametro de comparação, corte, meta, data limite ou texto auxiliar dentro de uma regra.

8.5 Como criar um KPI combinando varios campos

Exemplo: você quer mostrar saldo pendente de produção. Use a fórmula sum(quantidade_programada) - sum(quantidade_produzida). Mesmo que o campo base seja quantidade_programada, a fórmula pode ler outros campos livremente.

8.6 Como criar um KPI condicional

Exemplo: você quer mostrar 1 quando houver OPs em aberto e 0 quando não houver. Use =SE(open_ops()>0;1;0). Isso e útil para semaforos, bandeiras e estados de alerta.

Outro exemplo muito útil: comparar um campo do sistema com um valor digitado por você. Se o KPI precisa responder algo como "ha programação depois da data de corte?" você pode usar Valor Fixo = 05/05/2026 e fórmula =SE(MAX(data_programacao)>fixed_value;1;0).

Se a comparação for numerica, funciona da mesma forma. Exemplo: Valor Fixo = 1000 e fórmula =SE(SOMA(quantidade_programada)>fixed_value;1;0).

8.7 Como pensar na fórmula certa

Uma boa forma de montar o KPI e responder quatro perguntas: o que quero medir, em qual campo isso mora, preciso somar ou contar, e preciso comparar com outra coisa? A resposta dessas perguntas normalmente ja aponta para a fórmula.

Exemplo mental: "quero medir atraso medio por registro" leva a avg(atraso_minutos). "quero medir percentual produzido" leva a sum(quantidade_produzida) / sum(quantidade_programada) * 100.

Se a última pergunta for "preciso comparar com uma meta, uma data ou um texto fixo?", provavelmente vale preencher Valor Fixo e usar esse apoio na fórmula com fixed_value.

9. Fórmulas Prontas e Exemplos

Dica importante: fixed_value e valor_fixo são equivalentes. Você pode usar qualquer um dos dois nomes na fórmula.

10. Boas Práticas e Erros Comuns

Revise a fonte antes do KPI. Se a importação estiver parcial ou a deduplicação estiver agressiva, o card vai refletir esse recorte.

Comece simples. Primeiro faca o KPI funcionar com uma fórmula curta. Depois evolua para condições ou combinações maiores.

Use nomes claros. Títulos como Saldo Pendente, Média de Atraso e Meta de Eficiencia ajudam muito o usuário final.

Evite sobrecarregar o dashboard. Ter muitos cards e bom quando eles contam histórias diferentes. Se varios cards repetem a mesma leitura, o painel perde clareza.

Quando algo parecer errado: confira a fonte, a última importação, os filtros ativos do dashboard, a fórmula do card e os logs da aplicação.

11. Checklist de Diagnóstico Rápido

Use este roteiro quando um KPI não bater com o esperado:

1. Confirme a fonte certa no filtro do dashboard.
2. Valide a data/hora da última sincronização da fonte usada.
3. Abra os mapeamentos da mesma fonte e confira o campo logico.
4. Verifique se a coluna escolhida existe no CSV atual.
5. Sincronize novamente e confira quantidade de linhas em Importações.
6. Revise fórmula do KPI e formato de exibição.
7. Cheque Logs para erro de importação, encoding ou parse.

Caso clássico: mapeamento correto em uma fonte, mas dashboard filtrado em outra fonte. Nesse cenario o KPI pode ficar zerado.

Padrão de segurança operacional: antes de discutir indicador, valide sempre fonte + mapeamento + sincronização + filtro.

12. Governança de Dados e Padrões

Para operação profissional, padronize nomenclatura, ownership e critério de atualização. Cada fonte deve ter responsavel definido, finalidade documentada e regra clara de sincronização.

12.1 Convencao recomendada para campo logico

Formato: use snake_case, sem espacos e sem caracteres especiais.

Objetividade: prefira nomes semanticos, como data_impressao_op em vez de nomes genericos.

Estabilidade: evite renomeações frequentes sem controle de impacto em dashboards e relatórios.

12.2 Matriz de responsabilidade (RACI simplificada)

PCP/Operação: define necessidade de negocio e valida valor final dos indicadores.

Gestão: aprova KPI oficial e critério de leitura.

TI/Dados: garante conectividade, mapeamento técnico, confiabilidade de carga e rastreabilidade.

12.3 Controle de mudança

Antes da mudança: registre objetivo, fonte afetada e impacto esperado.

Durante: aplique mapeamento, sincronize e valide amostra.

Depois: monitore dashboard, importações e logs por pelo menos um ciclo completo da operação.

13. Rotina Operacional Recomendada

Adote uma cadencia fixa para reduzir risco de indicador inconsistente e retrabalho.

13.1 Rotina diaria

Abertura do turno: validar status das fontes críticas e última sincronização.

Meio do turno: revisar alertas, desvios de atraso e capacidade.

Fechamento: confirmar importação final e registrar ocorrencias relevantes.

13.2 Rotina semanal

Qualidade dos dados: revisar campos vazios em KPIs críticos.

Performance: analisar tempo de carga e crescimento de volume.

Revisão de KPI: confirmar aderencia entre definicao funcional e fórmula técnica.

13.3 Rotina mensal

Governança: revisar mapeamentos obsoletos e padrões de nomenclatura.

Segurança: revisar perfis de acesso e usuários inativos.

Evidencias: exportar relatórios consolidados e arquivar trilha de auditoria.

14. Gestão de Incidentes e Contingência

Quando houver falha, trate com fluxo padrão para reduzir tempo de indisponibilidade e garantir rastreabilidade.

14.1 Classificação sugerida

Severidade alta: dashboard sem dados, importação travada ou fonte crítica fora.

Severidade média: KPI com divergencia parcial e impacto setorial.

Severidade baixa: erro visual, ajuste pontual de mapeamento ou melhoria de fórmula.

14.2 Fluxo de resposta

Passo 1: identificar fonte, horário e escopo impactado.

Passo 2: validar conectividade e cabeçalho do arquivo/endpoint.

Passo 3: revisar mapeamentos e última carga em Importações.

Passo 4: executar sincronização controlada e validar resultado.

Passo 5: registrar causa, ação corretiva e ação preventiva em Logs/processo interno.

14.3 Plano de contingência mínimo

Fallback de leitura: manter ao menos uma fonte secundaria para indicadores críticos.

Janela de sincronização manual: definir horário de recuperação prioritaria.

Comunicação: informar operação e gestão com prazo estimado de normalização.

15. Glossário Técnico Rápido

Fonte: origem dos dados (CSV, API, banco, JSON).

Mapeamento: regra que liga coluna de origem ao campo logico interno.

Campo logico: chave padrão usada pelo sistema para importar e calcular.

Sincronização: processo de carga da fonte para a base local do sistema.

Deduplicação: remocao de registros considerados repetidos pela regra de ingestão.

KPI: indicador numerico exibido em card, calculado por fórmula.

Payload JSON: estrutura com dados complementares importados do registro.

Tabela de produção: base operacional usada pelo dashboard para consultas.

16. Cobertura Completa por Módulo

Resumo de todo o sistema com escopo funcional de cada menu principal.

17. Programação: Uso Completo

O módulo Programação aprofunda a leitura do dashboard com foco em analise operacional detalhada.

17.1 Subpáginas operacionais

Ordens: analise por OP, atraso e prioridade.

Processos: gargalos por etapa e média de atraso.

Recursos: carga planejada vs realizada por recurso.

Produtos: comportamento por SKU/código.

17.2 Boas práticas de uso

Filtre primeiro: fonte, status e período antes de comparar números.

Valide coerência: atraso em dashboard e detalhe em ordens devem ser consistentes.

Exporte evidências: use relatórios quando precisar formalizar decisão.

18. Central Analítica (BI)

A Central Analítica e a camada self-service para analise modelada, com governança de dataset, metrica e publicação de dashboard BI.

18.1 Fluxo recomendado de construcao

Passo 1: definir fonte analítica em /bi/fontes.

Passo 2: criar dataset e schema em /bi/datasets.

Passo 3: configurar relacionamentos e transformações.

Passo 4: criar métricas, fórmulas e KPIs.

Passo 5: montar visualização, pivot e dashboard no builder.

Passo 6: publicar e monitorar auditoria BI.

18.2 Módulos BI disponiveis

Fontes: conectividade e refresh policy.

Datasets: modelo de dados e preview.

Relacionamentos: join entre datasets.

Transformações: pipeline de limpeza/enriquecimento.

Métricas e Fórmulas: lógica de calculo reutilizável.

KPIs e Metas: acompanhamento com threshold.

Visualizações/Pivot: analise exploratoria.

Dashboards: builder drag-and-drop e exportação.

Auditoria: rastreio de execuções e erros BI.

19. Visões Personalizadas

Em Visões, você cria recortes prontos por público, turno ou área. Isso reduz ambiguidade e acelera tomada de decisão.

19.1 Quando usar visão

PCP: foco em atraso e sequenciamento.

Gestão: foco em produtividade e risco operacional.

Supervisão: foco em carga por recurso/processo.

19.2 Ações chave

Aplicar: carrega filtros da visão na consulta.

Dashboard da visão: abre painel contextualizado.

Duplicar: cria variante sem perder original.

Definir padrão: ativa a visão automaticamente para o usuário.

20. API e Webhooks: Manual Completo

O módulo API e Webhooks centraliza integrações externas com autenticação, ingestão e eventos de saida.

20.1 API REST

Base: /api/v1.

Uso típico: consultar OPS/KPIs, sincronizar fonte, criar mapeamento e exportar dados.

Recomendação: versionar contratos e monitorar resposta para evitar regressão de integração.

20.2 Webhooks de entrada

Objetivo: receber eventos de sistemas externos.

Padrão: validar endpoint_key, token e payload antes de processar.

20.3 Webhooks de saida

Objetivo: notificar outros sistemas sobre sucesso/falha de importação e eventos operacionais.

Governança: manter timeout, retries e logs de entrega revisados periodicamente.

Segurança: usar segredo, HTTPS e lista minima de eventos.

21. Configurações e Administração

A área de Configurações concentra parametrização crítica do ambiente.

21.1 Blocos principais

Identidade visual: nome, subtítulo, cores e marca.

Regras de status: normalização de status com fórmulas por campo.

Mapeamento de cards: editor de KPI do dashboard operacional.

Referência de campos por fonte: rastreio entre campo logico e coluna real do CSV.

21.2 Usuários e perfis

Em Usuários, defina quem pode alterar fonte, KPI, BI e integração. Use princípio do menor privilegio.

21.3 Auditoria administrativa

Sempre acompanhe Logs após mudanças de configuração para confirmar estabilidade e detectar regressão cedo.

22. FAQ Operacional

1) KPI zerado, mas CSV tem dado. O que fazer? Validar fonte filtrada, mapeamento da fonte correta e sincronização mais recente.

2) Coluna sumiu do mapeamento automático. Conferir cabeçalho do CSV atual, permissão no caminho de rede e encoding/delimitador.

3) Renomeei campo logico e KPI parou. Atualizar fórmula/campo no editor de KPI e sincronizar novamente.

4) Dashboard diferente da Programação. Verificar filtros ativos, janela de datas e fonte selecionada em cada tela.

5) Importação executou com menos linhas. Revisar deduplicação, critério de chave e mudança de layout no CSV.

6) API externa com erro intermitente. Testar endpoint, token, timeout e consultar logs de integração.

7) Qual rotina mínima diária recomendada? Validar fonte, importar, revisar alertas, confirmar KPIs críticos e registrar exceções.

8) Como operar em tela de fábrica? Usar Modo TV com refresh automático e alto contraste quando necessário.

9) Onde encontro evidências para auditoria? Em Importações, Relatórios e Logs, com cruzamento por horário e fonte.