Funções Utilitárias¶

📋 Visão Geral¶

O diretório utils/ contém 18 funções utilitárias reutilizáveis que abstraem lógicas comuns entre as páginas do Motor de Pricing.

📦 Catálogo¶

Autenticação e Permissões¶

Arquivo	Função	Descrição
`auth.py`	Autenticação auxiliar	Funções complementares de autenticação
`user_has_permission_to_edit.py`	`user_has_permission_to_edit()`	Verifica se o usuário tem permissão de edição na tabela

Cálculos¶

Arquivo	Função	Descrição
`calculate_totals_from_config.py`	`calculate_totals_from_config()`	Calcula totalizações com base em configuração de cards. Recebe dados e config, retorna valores formatados

Configuração de Tabelas¶

Arquivo	Função	Descrição
`create_column_configs.py`	`create_column_configs()`	Gera configurações de colunas para AG Grid a partir de definições simplificadas

Serialização¶

Arquivo	Função	Descrição
`serialize_to_json.py`	`serialize_to_json()`	Serializa dados para JSON (preparação para stores)
`deserialize_json.py`	`deserialize_json()`	Deserializa JSON recuperado dos stores para DataFrames

Formatação Numérica¶

Arquivo	Função	Descrição
`format_number.py`	`format_number()`	Formatação básica de número (separador de milhar e decimal)
`format_number_color.py`	`format_number_color()`	Formatação numérica com cor condicional (verde/vermelho)
`format_number_decimal.py`	`format_number_decimal()`	Formatação com controle de casas decimais
`format_card_value.py`	`format_card_value()`	Formatação específica para valores exibidos em cards de totalização

Tratamento de Dados¶

Arquivo	Função	Descrição
`handle_data.py`	`handle_data()`	Tratamento genérico de dados vindos da API
`handle_no_data_to_show.py`	`handle_no_data_to_show()`	Retorna componente visual de "sem dados" quando tabela está vazia
`get_unique_values.py`	`get_unique_values()`	Extrai valores únicos de uma coluna para popular filtros

Filtros e Tabelas¶

Arquivo	Função	Descrição
`handle_table_filter.py`	`handle_table_filter()`	Lógica padrão de filtragem de tabela com múltiplos filtros simultâneos
`table_change_handler.py`	`table_change_handler()`	Tratamento de mudanças em células editáveis da tabela

Transformações¶

Arquivo	Função	Descrição
`transform_percentage_values.py`	`transform_percentage_values()`	Converte valores percentuais entre formatos (ex: 0.4 ↔ 40%)
`validate_input_range.py`	`validate_input_range()`	Valida se um valor está dentro de um intervalo permitido

🔑 Funções Mais Utilizadas¶

`create_column_configs()`¶

Usada em todas as páginas com tabela. Converte definições simplificadas de colunas em configurações completas do AG Grid:

from utils.create_column_configs import create_column_configs

columns = [
    {"field": "preco_final", "headerName": "Preço Final", "editable": True},
    {"field": "mb_final", "headerName": "MB Final", "type": "percentage"},
]

ag_columns = create_column_configs(columns)

`handle_table_filter()`¶

Padrão centralizado de filtragem utilizado em todas as páginas:

Recebe dados e valores selecionados nos filtros
Aplica todos os filtros simultaneamente
Retorna dados filtrados

`format_card_value()`¶

Formatação padronizada para cards de totalização — garante consistência visual entre todas as páginas.

Última atualização: Março 2026 | Versão 1.0