🔄 Realocação de Vendedor¶

1. O que é este módulo?¶

O módulo de Realocação de Vendedor permite que a equipe comercial importe movimentações de vendedores entre lojas, garantindo que os indicadores gerenciais (como comissão, metas e faturamento) reflitam a alocação correta de cada vendedor. Quando um vendedor é transferido de uma loja para outra, os valores de faturamento históricos precisam ser redistribuídos — e é esse processo que o módulo automatiza.

Sem este módulo, uma transferência de vendedor poderia fazer com que o faturamento atribuído a ele continuasse aparecendo na loja antiga nos dashboards, gerando distorções nas análises de performance e no pagamento de comissões.

Exemplo prático: O vendedor João (código 12345) atuava na loja "Qualicitrus Centro" e foi transferido para "Qualicitrus Norte". A equipe comercial utiliza este módulo para informar a movimentação, indicando loja de origem e loja de destino. O sistema valida se João realmente tem faturamento na loja de origem e processa a realocação.

2. Telas Disponíveis¶

Aba	Finalidade
📤 Upload Arquivo	Envio de planilhas com movimentações de vendedores entre lojas
🔍 Consulta	Busca de realocações processadas e histórico de uploads

3. Como Usar — Passo a Passo¶

📤 Aba Upload — Enviando realocações de vendedores¶

Passo a passo:

Acesse o módulo "Realocação de Vendedor" no Dashboard
Baixe o template clicando no botão de download:
O arquivo .xlsx gerado contém:
- Aba de preenchimento com campos estruturados
- Aba de exemplos mostrando como preencher corretamente
- Aba de consulta de IDs com dados reais do BigQuery (empresas, lojas, códigos)
As células de empresa possuem dropdowns nativos (Data Validation)
Preencha a planilha com os dados de cada movimentação:
cod_vendedor — Código do vendedor no sistema
nome_vendedor — Nome completo do vendedor
empresa_origem — Empresa (investida) de onde o vendedor está saindo
loja_origem — Código da loja de origem
empresa_destino — Empresa de destino (pode ser a mesma ou diferente)
loja_destino — Código da loja de destino
data_inicio — Data de início da realocação
data_fim — Data de fim da realocação (se aplicável)
Faça o upload do arquivo no portal
Aguarde a validação completa — o sistema verificará:
Se o vendedor existe no cadastro (dim_vendedor)
Se as lojas de origem e destino existem na estrutura comercial
Se o vendedor possui faturamento na loja de origem
Se não há duplicatas ou conflitos lógicos
Se houver erros, um relatório detalhado será exibido com:
A linha exata do Excel
A coluna com problema
A regra violada (ex: "Vendedor inexistente na dim_vendedor")
Revise os dados na pré-visualização
Clique em "Processar" para enviar ao BigQuery

🔍 Aba Consulta — Buscando realocações e histórico¶

A tela de consulta oferece duas funcionalidades:

1. Busca de Realocações¶

Permite localizar movimentações já processadas utilizando filtros dinâmicos:

Por Empresa — Filtro pela investida
Por Código do Vendedor — Busca direta pelo código
Por Nome do Vendedor — Busca por nome

Os resultados são apresentados em cards estilizados que exibem claramente: - Dados do vendedor (código, nome) - Origem: Empresa e loja de onde saiu - Destino: Empresa e loja para onde foi - Período da realocação

2. Gestão de Histórico (Meus Uploads)¶

Usuário comum: Visualiza apenas os arquivos que ele mesmo enviou
Administrador: Seletor para alternar entre "Meus uploads" e "Todos os uploads" para auditoria global
Download: Gera um Excel com os dados exatos de cada upload, reconstituído a partir do BigQuery
Contagem de linhas: Informação rápida do volume de registros em cada carga

4. Validações¶

O módulo aplica validações em três níveis para garantir a integridade dos dados:

Nível 1 — Estrutura do Arquivo¶

Regra	Descrição
8 colunas obrigatórias	O arquivo deve conter todas as colunas exigidas pelo template. Se alguma estiver ausente, o upload é bloqueado com lista dos campos faltantes.
Campos mandatórios (Non-Null)	Células vazias em colunas críticas geram erro com indicação da linha exata.

Nível 2 — Regras de Negócio (Consultas ao BigQuery)¶

Regra	Descrição
Existência do Vendedor	O `cod_vendedor` é validado contra a `dim_vendedor` do BigQuery. Se não existir, o upload daquela linha é rejeitado.
Estrutura Comercial	As lojas de origem e destino devem existir na `dim_estrutura_comercial` (Gold CDP).
Histórico de Faturamento	O sistema verifica se o vendedor possui registros de faturamento na `fato_faturamento` da loja de origem. Se não houver nenhum registro, a realocação é bloqueada — não é possível "realocar" faturamento que não existe.

Nível 3 — Integridade e Lógica¶

Regra	Descrição
Anti-Duplicidade	Linhas idênticas no mesmo lote são bloqueadas. O sistema detecta duplicatas e informa quais linhas são repetidas.
Conflito Lógico (Loop)	Se o mesmo par Vendedor/Loja aparecer como origem e destino simultaneamente, o sistema bloqueia a operação. Isso evita loops circulares que poderiam corromper os dados de faturamento.

Validações de Formato¶

Regra	Descrição
Preservação de Zeros	Códigos como `03101` são tratados como texto (string), preservando zeros à esquerda
Normalização de Colunas	Variações como `cod_vend`, `cod vendedor`, `codigo_vendedor` são mapeadas automaticamente para `cod_vendedor`
Datas	Conversão automática de formatos brasileiros para o padrão ISO aceito pelo BigQuery

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Finalidade
Silver	`lavoro_portal_realocacao_vendedor`	Armazena o histórico completo de todas as realocações com metadados de auditoria
Dimensional	`dim_vendedor`	Cadastro de vendedores para validação de existência
Dimensional	`dim_estrutura_comercial`	Estrutura comercial para validação de lojas e empresas
Fato	`fato_faturamento`	Dados de faturamento para validação de histórico na loja de origem

Configurações de Carga¶

Parâmetro	Valor
Método de escrita	`WRITE_APPEND` — mantém o histórico de todas as cargas
Schema	Tipagem estrita via `SchemaField`, com foco em `STRING` para IDs
Metadados	Injeção automática de `uploaded_at` (UTC) e `uploaded_by` (e-mail)

Campos de Auditoria¶

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

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo — Upload e Consulta
comercial	Acesso ao Upload e Consulta de realocações

7. Tratamento de Erros¶

Cenário	Como o sistema reage
Coluna ausente	Erro crítico com lista de campos obrigatórios faltantes
Erro de validação por linha	Tabela detalhada: Linha do Excel, Coluna e Regra Violada
Vendedor inexistente	Indica a linha e o código informado que não foi encontrado na `dim_vendedor`
Sem faturamento na origem	Bloqueio com explicação: "Vendedor não possui histórico de faturamento nesta loja"
Conflito lógico (loop)	Bloqueio com indicação do par vendedor/loja que aparece como origem e destino
Falha de conexão	Alerta informativo via `st.warning`
Sucesso	Toast de notificação com confirmação de quantas linhas foram inseridas

Dica do sistema: O módulo de rastreamento (Tracker) registra falhas de validação para identificar padrões de erro recorrentes e orientar treinamentos para o time que preenche as planilhas.

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