🎯 Metas Lavoro¶

1. O que é este módulo?¶

O módulo de Metas Lavoro é o motor de planejamento comercial e financeiro da companhia. Ele permite que as equipes de gestão comercial e planejamento carreguem metas detalhadas e orçamentos (Budget e Forecast) no Datalake, onde são processados e disponibilizados nos dashboards de acompanhamento.

O módulo é dividido em 5 eixos estratégicos, cada um com seu próprio template e conjunto de validações:

Tipo de Meta	O que representa
Vendedor	Meta individual atribuída a cada vendedor/RTV, por loja e segmento de produto
Loja	Meta consolidada por unidade de negócio (filial), por segmento
Ritual de Gestão	Metas vinculadas aos rituais gerenciais da companhia
Desafio	Metas de desafio comercial (programas de incentivo)
Despesas	Metas de controle de despesas por centro de custo

Cada tipo de meta possui um ciclo de planejamento que reflete a realidade do agronegócio:

Ciclo	Descrição
Budget	Orçamento anual estático, definido no início do ano safra
Forecast +3	Revisão trimestral após 3 meses
Forecast +6	Revisão semestral após 6 meses
Forecast +9	Revisão após 9 meses

2. Telas Disponíveis¶

Aba	Finalidade
📤 Upload Arquivo	Envio de planilhas de metas com seleção do tipo e ciclo
🔍 Consulta	Busca de metas cadastradas, histórico de uploads e recuperação de arquivos

3. Como Usar — Passo a Passo¶

📤 Aba Upload — Carregando metas no sistema¶

Passo a passo:

Acesse o módulo "Metas Lavoro" no Dashboard
Selecione o tipo de meta no dropdown (Vendedor, Loja, Ritual, Desafio ou Despesas)
A seleção define o template e as validações que serão aplicadas
Selecione o ciclo de planejamento (Budget, Forecast +3, +6, +9)
Baixe o template clicando no botão de download:
O arquivo .xlsx gerado contém abas de referência com listas de empresas e lojas válidas
As listas são obtidas em tempo real do BigQuery, garantindo dados atualizados
Preencha a planilha seguindo o template:
Para Vendedor: Informe loja_id, empresa_id, segmento, dados do vendedor (CPF ou RTV), valores de meta (meta_rol, lucro_bruto) e data
Para Loja: Informe empresa_id, loja_id, segmento, valores de meta e data
Para Ritual de Gestão: Informe empresa_id, loja_id, valor e data
Para Desafio: Informe empresa_id, loja_id, meta_rol, lucro_bruto, segmento e data
Para Despesas: Informe empresa_id, loja_id, conta_id (centro de custo), valor e data
Faça o upload do arquivo no portal
Aguarde a validação completa — o sistema verificará todos os campos (veja seção de Validações)
Se houver erros, o sistema exibirá um relatório detalhado com a linha exata do Excel e o motivo do problema
Revise a pré-visualização dos dados antes de confirmar
Clique em "Processar" para enviar ao BigQuery

Dica sobre mapeamento: O sistema aceita diversas variações de nomes de colunas. Por exemplo, unidade, filial, store são automaticamente interpretados como loja_id. Isso facilita o reaproveitamento de planilhas já existentes no time.

🔍 Aba Consulta — Visualizando e recuperando metas¶

A consulta é segmentada pelos mesmos 5 eixos estratégicos e oferece dois caminhos:

1. Buscar Metas (Dados Ativos)¶

Ao utilizar o botão "Buscar metas", o sistema consulta a camada Gold para exibir os dados já processados:

Visualização em Cards: Os resultados são exibidos em componentes expansíveis (expander), agrupados por Empresa e Loja
Dados Consolidados: Exibição clara de META_ROL, LUCRO_BRUTO ou VALOR (no caso de despesas), junto com a data de competência
Rastreabilidade: Cada card indica a data exata em que aquele registro foi enviado ao portal
Filtros por Contexto: O sistema adapta automaticamente as colunas. Para "Despesas", o foco é Centro de Custo; para "Vendedor", foco em Segmento e RTV

Limite de resultados: A consulta retorna os 1.000 registros mais recentes para garantir fluidez da interface.

2. Meus Uploads (Histórico de Carga)¶

Filtro por Usuário: Visualize apenas os arquivos que você enviou ou, como Admin, acesse o histórico completo de todos os usuários
Download de Origem: O sistema gera dinamicamente um Excel com os dados exatos de um upload específico
Contagem de Linhas: Verifique rapidamente o volume de dados processados em cada carga

4. Validações¶

O sistema executa uma bateria de testes automáticos rigorosos, específicos para cada tipo de meta:

Validações Comuns (todos os tipos)¶

Regra	Descrição
Colunas obrigatórias	Cada tipo de meta exige um conjunto diferente de colunas. Se alguma estiver ausente, o upload é bloqueado com indicação das colunas faltantes.
Valores nulos	Células vazias em colunas críticas (como `meta_rol` ou `loja_id`) geram erro com indicação da linha e coluna exatas.
empresa_id	O ID da empresa deve existir na estrutura comercial oficial do Datalake.
loja_id	A loja informada deve pertencer à rede cadastrada na estrutura comercial.
Formato de datas	Conversão automática de formatos brasileiros (DD/MM/AAAA) e tratamento de números para preservar zeros à esquerda.

Validações Específicas — Vendedor¶

Regra	Descrição
CPF/CNPJ	O campo é limpo de caracteres especiais (pontos, traços) e validado: CPF deve ter 11 dígitos, CNPJ deve ter 14 dígitos.
Vínculo Comercial	Ao menos um dos campos posição ou rtv_id deve estar preenchido por linha.

Validações Específicas — Segmento¶

Regra	Descrição
Lista de segmentos	Para todas as metas (exceto Despesas), o segmento informado deve pertencer à lista oficial: Defensivos, Fertilizantes, Sementes, Especialidades, entre outros.

5. Dados e Integrações¶

Tabelas do BigQuery¶

Camada	Tabela	Tipo de Meta
Silver	`lavoro_portal_metas_vendedor`	Vendedor
Silver	`lavoro_portal_metas_loja`	Loja
Silver	`lavoro_portal_metas_ritual_gestao`	Ritual de Gestão
Silver	`lavoro_portal_metas_desafio`	Desafio
Silver	`lavoro_portal_metas_despesas`	Despesas
Gold	`fato_metas_*` (correspondente)	Tabela processada para dashboards

Campos de Auditoria¶

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

6. Controle de Acesso¶

Role	Permissões
admin	Acesso completo — Upload e Consulta de todos os tipos
comercial	Acesso a Upload e Consulta conforme configuração

7. Tratamento de Erros¶

Cenário	Como o sistema reage
Coluna ausente	Erro crítico com lista de campos faltantes por tipo de meta
Erro de validação	Relatório detalhado com agrupamento de erros por coluna e regra (ex: "12 ocorrências em 'loja_id' — Loja inexistente")
CPF/CNPJ inválido	Indica a linha exata e o motivo (dígitos insuficientes)
Segmento não reconhecido	Lista os segmentos válidos aceitos pelo sistema
Falha de conexão	Captura com mensagem de erro amigável

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