📦 Custo de Reposição¶

1. O que é este módulo?¶

O módulo de Custo de Reposição permite que a equipe de operações envie tabelas com os custos de reposição de produtos que estão em situação de ruptura (falta de estoque para atender a demanda) ou de faturamento. Esses custos são utilizados nos cálculos de margem e projeções financeiras da companhia.

O grande diferencial deste módulo é a replicação automática: quando o usuário informa os dados consolidados por Empresa, o sistema automaticamente propaga os valores para todas as lojas vinculadas àquela empresa na estrutura comercial. Isso significa que uma única linha no Excel pode gerar dezenas de registros no BigQuery, eliminando trabalho manual repetitivo.

Exemplo prático: O operador informa que o custo de reposição do produto "Glifosato 480 SL" na empresa "Qualicitrus" é R$ 45,00/L. O sistema consulta a estrutura comercial, identifica que a Qualicitrus tem 15 lojas ativas, e replica automaticamente o custo para todas elas.

2. Telas Disponíveis¶

Aba	Finalidade
📤 Upload Arquivo	Envio de planilhas com custos de reposição — inclui template inteligente e validação completa
🔍 Consulta	Busca de custos ativos, visualização em cards estilizados e histórico de uploads

3. Como Usar — Passo a Passo¶

📤 Aba Upload — Enviando custos de reposição¶

Passo a passo:

Acesse o módulo "Custo de Reposição" no Dashboard
Baixe o template inteligente clicando no botão de download:
O sistema gera um arquivo .xlsx dinâmico via SQL que já traz os produtos identificados com saldo negativo ou necessidade de reposição
O template inclui abas de referência com as empresas, clusters e lojas válidas
Preencha a planilha com os dados de custo de reposição:
Cluster — Agrupamento regional da empresa
Empresa — Nome da empresa (investida)
Código do Produto (SKU) — Código do produto no sistema
Tipo de Ruptura — Deve ser um dos três valores aceitos (veja seção de Validações)
Valor do Custo de Reposição — Preço unitário de reposição
Faça o upload do arquivo no portal
Aguarde a validação automática — o sistema verificará:
Se o SKU existe no cadastro de produtos
Se a combinação Empresa/Cluster está correta
Se o tipo de ruptura é válido
Se o arquivo já não foi enviado anteriormente
Se algum SKU estiver incorreto, o sistema irá sugerir o código correto mais próximo do que você digitou
Revise os dados na pré-visualização — confira se os valores estão corretos
Clique em "Processar" — o sistema irá:
Replicar os dados para todas as lojas da empresa (automaticamente)
Carregar na camada Silver do BigQuery
Executar o SQL de transformação para a camada Gold

Dica: Após o processamento, a interface fica bloqueada com um aviso de "Processamento em Andamento", evitando envios duplicados. Aguarde até que o processamento termine.

🔍 Aba Consulta — Buscando custos ativos e histórico¶

A tela de consulta possui duas funcionalidades:

1. Busca de Custos Ativos¶

Permite localizar custos de reposição já processados, utilizando filtros dinâmicos:

Por Produto: Busca pelo código SKU do produto
Por Empresa: Filtro por empresa/investida

Os resultados são exibidos em cards estilizados (não em tabela), facilitando a leitura rápida de: - Identificadores: SKU, Produto Agrupado, Empresa/Cluster - Dados Técnicos: Fornecedor, Princípio Ativo, Marca Comercial - Métricas: Valor do custo de reposição e tipo de ruptura

Nota: O sistema ajusta automaticamente os filtros e colunas dependendo do ambiente (DEV/QA vs. PROD).

2. Meus Uploads (Histórico)¶

Usuário comum: Visualiza apenas os arquivos que ele mesmo enviou
Administrador: Possui um seletor para alternar entre "Meus uploads" e "Todos os uploads", permitindo auditar toda a equipe
Download: Para cada item no histórico, é possível baixar o arquivo original reconstruído a partir do BigQuery

4. Validações¶

Validações de Negócio¶

Regra	Descrição
Domínio de Ruptura	O campo "Tipo de Ruptura" aceita somente três valores: `RUPTURA DE CARTEIRA`, `RUPTURA DE PLANEJAMENTO` ou `FATURAMENTO`. Qualquer outro valor gera erro de validação.
Integridade de SKU	O código do produto é validado contra a `dim_produto` do BigQuery, usando o `sufixo_gcp` da empresa para compor o ID correto.
Sugestão de Produto	Se o SKU informado não existir, o sistema utiliza um algoritmo de busca para sugerir o código mais próximo, ajudando o usuário a corrigir erros de digitação.
Hierarquia Comercial	A combinação Empresa + Cluster deve existir na estrutura comercial oficial.
Existência de Empresa	A empresa informada deve estar cadastrada na `vw_dim_estrutura_comercial`.

Validações de Formato¶

Regra	Descrição
Moeda brasileira	Valores como `R$ 1.000,50` são convertidos automaticamente para formato numérico
Preservação de códigos	Colunas como `cod_loja` e `cod_produto` preservam zeros à esquerda
Normalização de colunas	Variações de nomes de colunas (ex: "Org. Venda" → "empresa") são mapeadas automaticamente

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_custo_reposicao`	Staging de entrada — armazena o histórico bruto de todos os uploads com metadados
Gold	`fato_custo_reposicao`	Tabela final processada — contém os custos consolidados para consumo em dashboards
Dimensional	`vw_dim_estrutura_comercial`	Fornece a lista de empresas, lojas e clusters válidos, além do `sufixo_gcp` de cada empresa
Dimensional	`dim_produto`	Cadastro de produtos para validação de SKUs

Fluxo de Replicação¶

graph TD
    A[📄 Planilha: 1 linha por empresa] --> B[Upload no Portal]
    B --> C{Validação}
    C -->|✅ OK| D[Consulta Estrutura Comercial]
    D --> E[Replicação: empresa → N lojas]
    E --> F[Silver BigQuery - N linhas]
    F --> G[SQL Transformação]
    G --> H[Gold BigQuery]
    H --> I[📊 Dashboards BI]

Campos de Auditoria¶

uploaded_by — E-mail do usuário que fez o upload
uploaded_at — Data e hora UTC exata da operação
arquivo_origem — Nome do arquivo original

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo — Upload e Consulta
custo de reposição	Acesso completo — Upload e Consulta

7. Tratamento de Erros¶

Cenário	Como o sistema reage
SKU não encontrado	Exibe erro detalhado e sugere o código de produto mais próximo
Formato de moeda inválido	Funções de limpeza tratam formatos brasileiros (`R$ 1.000,00`) automaticamente
Arquivo duplicado	Informa quem já enviou o arquivo e quando
Falha de conexão	`try/except` em todas as chamadas ao BigQuery com log detalhado via `st.error`
Interface bloqueada	Enquanto o processamento está rodando, a UI fica bloqueada para evitar envios duplicados

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