Glossário do projeto

Vocabulário do domínio comercial de combustíveis (OnPetro) que este app usa. Termos da plataforma X-Adm (Forgejo, Coolify, Garage…) não são redefinidos aqui — linkam para o glossário da plataforma.

Tipos de arquivo

Cada envio é um .zip com um ou mais .xlsx; o ArquivoDetector reconhece o tipo de cada planilha pelo conteúdo (abas e cabeçalhos) e pelo nome, sem o operador informar nada. Ordem de prioridade e critérios em Detecção do tipo.

RELATORIO18

Relatório principal de vendas. Alimenta o fato bi_movimento e, de passagem, garante os cadastros relacionados (bi_filial, bi_cliente, bi_vendedor, bi_produto). Faz DELETE seletivo do período antes do UPSERT. Detectado pelo nome do arquivo (relatorio, relatório ou rel 18).

MARGEM_CONSOLIDADA

Relatório de custo/inventário do período. Alimenta bi_custo_inventario e complementa bi_movimento do período. Detectado pelo nome (margem consolidada / margem_consolidada).

MARGEM_DIA

Variante diária da margem. Complementa bi_movimento. Detectado pelo nome no padrão margem - (espaço-hífen-espaço, convenção da equipe).

META

Metas de litros/margem por vendedor e período. Alimenta bi_meta (upsert por vendedor + data). Detectado pelo nome (meta, quando nenhum tipo mais específico bateu).

META_FERNANDO

Variante de meta por vendedor, numa aba específica (Meta por vendedor ou coluna Tipo de meta). Também alimenta bi_meta. Tem a prioridade mais alta na detecção.

POSTOS

Cadastro de postos revendedores (com vinculação a distribuidor). Alimenta bi_posto (upsert por CNPJ). Detectado pela coluna Vinculação a Distribuidor.

TRR

Cadastro de Transportadores-Revendedores-Retalhistas. Alimenta bi_trr (upsert por CNPJ). Detectado pela coluna Tipo de Instalação ou Qualificação da Empresa (a ANP renomeou a coluna ~2026).

COMPRAS

Relação de compras de combustível (itens de NF). Alimenta bi_fornecedor (upsert por CNPJ) e bi_compra (sem chave natural: substitui o período do arquivo). Só entram linhas de combustível (produto ONU …). Detectado por uma aba chamada Compras, antes de qualquer regra por nome.

COTA_PETROBRAS

Cota mensal de volume (m³) por polo e produto, uma aba por ano. Alimenta bi_cota_petrobras por full-replace (a planilha é a matriz inteira). Detectado por uma aba com nome de ano cujo cabeçalho começa com POLO/PRODUTO/JANEIRO.

Domínio comercial

Movimento

Fato central de vendas (bi_movimento): uma linha por NF × produto × cliente × filial. Carrega quantidade, preço, margem, frete, taxa administrativa, prazo, além de UF/município de destino da venda (não da filial).

Filial

Unidade da OnPetro que originou a venda (bi_filial, chave cod_filial). Os relatórios XLSX só trazem o código da filial — município/UF da própria filial são cadastrados à parte (docs/privado/seed-filiais.sql); as colunas UF/ Município dos relatórios referem-se ao destino, e vão para bi_movimento.

Vendedor

Vendedor responsável pela venda e alvo das metas (bi_vendedor, chave cod_vendedor). Ligado a bi_movimento e a bi_meta.

Meta

Objetivo de litros e margem por vendedor num período (bi_meta, chave natural cod_vendedor + data).

custo_inventario

Custo de carregar estoque no período (bi_custo_inventario, chave data): valor, taxa de aplicação, juros totais, venda simulada e total. Origem: MARGEM_CONSOLIDADA.

Chave natural

Combinação de colunas que identifica um fato de forma estável, independente da posição na planilha (ex.: nf, cod_produto, cod_cliente, cod_filial em bi_movimento). Vira UNIQUE (uq_*) e é a chave do UPSERT diff-aware — é o que permite reprocessar o mesmo período sem duplicar.

Período

Intervalo de datas coberto por um envio. Vem do conteúdo do arquivo (não do upload — ao contrário do projeto irmão Transporte); é o que delimita o DELETE seletivo do diff-aware.

Conjunto (lote)

Pacote de N arquivos enviados juntos: é o próprio .zip recebido no POST. O cliente não declara nada — o identificador do lote e o total de arquivos são derivados do conteúdo pelo servidor (o id é zip-<sha256 do zip>; o total, o número de entradas .xlsx). Quando todas as entradas terminam, sai uma notificação de resumo no Telegram (ConjuntoLoteService).

Checksum

SHA-256 do conteúdo binário do .xlsx; chave de idempotência de upload — evita reprocessar o mesmo arquivo após sucesso.

Diff-aware (UPSERT)

INSERT … ON CONFLICT (chave natural) DO UPDATE … WHERE … IS DISTINCT FROM: só grava a linha que realmente mudou. Linhas inalteradas preservam id UUID e xmin — não re-propagam pelo PowerSync. Métricas agregadas por envio: linhas_efetivas (INSERT/UPDATE que escreveram) e linhas_removidas (DELETE seletivo).

Segmento

Classificação do produto em combustivel, lubrificante ou vazio (Arla/Ureia), derivada do nome e gravada em bi_produto e, denormalizada, em bi_movimento. É o corte que o PowerSync usa para mandar a cada perfil de usuário só o seu segmento.

Infraestrutura específica

PowerSync

Serviço de sincronização que replica as tabelas bi_* do PostgreSQL para os clientes móveis (SQLite). Aqui sincronizam todas as bi_* (fatos, dimensões e bi_configuracao); as xls_* são locais por design. Exige PK de coluna única TEXT/UUID — por isso os bi_* usam id UUID DEFAULT uuidv7().

bi_configuracao

Tabela KV global (id TEXT) sincronizada via PowerSync. Guarda ultimo_nuke (sinal de reset lido pelo cliente Flutter) e parâmetros como slow_query_timeout_ms. Rows sistema=TRUE são editáveis só pelo backend.

Nuke da replicação

Operação destrutiva que zera o estado replicado (slot lógico do PostgreSQL + MongoDB do PowerSync) e força o re-sync dos clientes. No código, NukeReplicationService; auditada em xls_nuke_replication. Procedimento no runbook de operação.