💰 Lista de Preços¶

1. O que é este módulo?¶

O módulo de Lista de Preços é a ferramenta central do time de Pricing para gerenciar as tabelas de preços de toda a companhia. Ele permite o upload de novas tabelas de preços, consulta de preços ativos e rastreamento de todo o histórico de submissões, garantindo que o ecossistema de precificação esteja sempre atualizado e validado.

A validação deste módulo é uma das mais rigorosas do portal, pois envolve a verificação de hierarquia comercial tripla (Empresa → Escritório de Vendas → Loja), existência de produtos no cadastro e conformidade com as condições de venda.

Exemplo prático: O analista de Pricing precisa inserir uma nova tabela de preços para a safra 2026 da empresa "Agrícola Alvorada". Ele baixa o template (que já vem com dropdowns de empresas, escritórios e lojas), preenche os preços por produto, faz o upload, e o sistema valida toda a hierarquia comercial, verifica se os SKUs existem e carrega os dados na camada Gold para consumo pelos dashboards.

2. Telas Disponíveis¶

Aba	Finalidade
📤 Upload Lista	Upload padrão de tabelas de preços com validação completa
📤 Upload MVP	Versão simplificada do upload para cargas rápidas
🔍 Consulta	Busca de preços ativos, enriquecimento de dados e histórico de uploads

3. Como Usar — Passo a Passo¶

📤 Aba Upload Lista — Enviando tabelas de preços¶

Passo a passo:

Acesse o módulo "Lista de Preços" no Dashboard
Baixe o template clicando no botão de download:
O arquivo .xlsx gerado inclui abas de referência com:
- Lista de empresas com IDs e nomes
- Escritórios de vendas válidos por empresa
- Lojas válidas por escritório
As células possuem dropdowns nativos (Data Validation) para facilitar o preenchimento
Preencha a planilha com os dados de pricing:
empresa — Nome da empresa (investida)
escritorio_vendas — Escritório de vendas vinculado
loja_id — Código da loja
codigo_produto — Código do SKU do produto
preco — Preço de venda unitário (deve ser positivo)
custo — Custo do produto (deve ser positivo)
nome_lista — Nome identificador da lista de preços (máx. 100 caracteres)
tipo_lista — Código de condição de venda
inicio_vigencia — Data de início da validade do preço
final_vigencia — Data de fim da validade (deve ser ≥ inicio_vigencia)
safra — Ano safra de referência
Faça o upload do arquivo no portal
Aguarde a validação completa — o sistema verificará em múltiplas camadas (veja seção de Validações)
Se houver erros, um relatório detalhado será exibido com a linha exata do Excel, a coluna e o motivo
Revise a pré-visualização dos dados — confira se valores, datas e produtos estão corretos
Marque o checkbox de revisão — o botão de envio permanece desabilitado até que você confirme que revisou os dados
Clique em "Processar" para enviar ao BigQuery:
Uma barra de progresso multifase acompanha o upload e o processamento
Primeiro os dados são carregados na Silver
Em seguida, o SQL fato_pricing.sql é executado para consolidar na Gold

Bloqueio de duplicidade: Se um arquivo com o mesmo nome já existir no BigQuery, o sistema bloqueará o upload para evitar sobreposições acidentais.

🔍 Aba Consulta — Buscando preços ativos e histórico¶

A tela de consulta oferece dois caminhos:

1. Motor de Busca de Preços Ativos¶

Diferente de uma consulta simples, este motor realiza cruzamentos em tempo real entre tabelas de fatos e dimensões:

Filtros combinatórios:
Código do Produto — Busca parcial (aceita parte do código)
Loja — Autocomplete dinâmico que traz ID - Nome da Loja
Safra — Ano safra de referência
Empresa (Regional) — Filtro por investida
Tipo de Lista — Código da condição de venda
Enriquecimento automático: Os resultados exibem não apenas os dados brutos, mas informações cruzadas:
Nomes de regionais e unidades de negócio (da estrutura comercial)
Descrições de SKUs, segmentos e agrupamentos de produtos
Sufixos GCP por investida para garantir o produto_id correto
Filtro de status: Apenas registros com status_preco = TRUE são exibidos (preços válidos)
Exportação: Botão dedicado (estilizado em verde) permite exportar até 1.000 registros para Excel

2. Meus Uploads (Histórico)¶

Rastreabilidade por usuário: Lista os últimos 30 uploads do seu e-mail
Visão administrativa: Admins podem alternar para ver os uploads de toda a companhia
Download on-the-fly: Ao clicar em "Baixar", o sistema reconstrói o arquivo original a partir do BigQuery

4. Validações¶

O sistema executa validações em três camadas antes de habilitar o envio:

Camada 1 — Normalização e Tipagem¶

Regra	Descrição
Preservação de códigos	Zeros à esquerda em `loja_id` e `codigo_produto` são preservados
Moedas	Limpeza de símbolos (`R$`, `$`) e tratamento de separadores brasileiros (ponto para milhar, vírgula para decimal)
Datas flexíveis	Aceita `DD/MM/AAAA` e `AAAA-MM-DD`

Camada 2 — Validação de Hierarquia Comercial¶

Regra	Descrição
Empresa	Deve existir no cadastro da estrutura comercial
Escritório	Deve pertencer à empresa informada (validação de pares)
Loja	Deve pertencer ao escritório informado (validação de triplas: Empresa → Escritório → Loja)

Camada 3 — Integridade de Produtos e Regras de Negócio¶

Regra	Descrição
Montagem do ID	O sistema usa o `sufixo_gcp` da empresa para compor o ID único do produto
Existência de produto	Cruzamento em tempo real com a `dim_produto` do BigQuery
Sugestão inteligente	Se o código estiver incorreto, o sistema sugere os códigos mais próximos
tipo_lista	Validado contra a tabela `dim_condicao_de_venda`
Preço e Custo	Devem ser estritamente positivos
Vigência	`inicio_vigencia` deve ser ≤ `final_vigencia`
Nome da Lista	Limite de 100 caracteres para compatibilidade com sistemas legados
Duplicidade de Arquivo	Bloqueio de upload se já existir arquivo com mesmo nome

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_lista_precos`	Destino imediato do upload (Append). Armazena histórico bruto com metadados de quem enviou e quando
Gold	`fato_pricing`	Tabela final de consumo — atualizada via SQL após cada upload bem-sucedido. Alimenta dashboards
Dimensional	`dim_estrutura_comercial`	Hierarquia comercial (empresas, escritórios, lojas)
Dimensional	`dim_produto`	Cadastro de produtos para validação de SKUs
Dimensional	`dim_condicao_de_venda`	Tipos de lista válidos

Fluxo de Dados¶

graph LR
    A[📄 Planilha Excel] --> B[Upload no Portal]
    B --> C{Validação 3 Camadas}
    C -->|✅ OK| D[Silver BigQuery]
    C -->|❌ Erro| E[Relatório Detalhado]
    D --> F[SQL fato_pricing]
    F --> G[Gold BigQuery]
    G --> H[📊 Dashboards BI]

Campos de Auditoria¶

uploaded_by — E-mail do usuário
uploaded_at — Data e hora UTC
arquivo_origem — Nome do arquivo original

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo — Upload, Upload MVP e Consulta
pricing	Acesso ao Upload e Consulta de Lista de Preços

7. Tratamento de Erros¶

Cenário	Como o sistema reage
Erro de negócio	`st.error` com tabela detalhada: Linha do Excel, Coluna e Motivo (ex: "Valor negativo")
Erro de infraestrutura	Captura de exceção com `st.expander` contendo log técnico para suporte
Produto inexistente	Sugere o código mais próximo existente na `dim_produto`
Arquivo duplicado	Bloqueio preventivo com informação de quem já enviou e quando
Botão de envio	Permanece desabilitado até que o checkbox de revisão da pré-visualização seja marcado
Barra de progresso	Feedback visual em tempo real durante upload e processamento SQL

📅 Documentação atualizada em Março 2026.