Transferências entre CDs — análise de rede
Aplicativo web que planeja transferências de estoque entre todos os CDs da
rede: cada CD pode ser origem (pelo que sobra) e destino (pelo que
falta), na sequência que o planejador escolher — mostrando o benefício e o
impacto fiscal (ICMS) por rota ao lado.
Mudança de conceito (v2). Antes eram três bases e uma origem fixa (CD10 →
demais CDs). Agora são duas bases e a rede inteira em uma análise só.
🧠 O conceito em uma tela
BASE ÚNICA DE CDs BASE DE PEDIDOS (opcional)
(todos os CDs empilhados) ano_mês · CD · produto
↓ o que sobra ↓ o que falta ↓
EXCESSO NECESSIDADE ←—— modo "saldo ideal" ou "pedidos"
Sequência de ORIGENS → Ordem de DESTINOS
CD10 → CD9 → CD8 CD1 → CD2 → CD7 → CD8
│ │
└── cada origem, na sua vez, olha TODOS os destinos na ordem
- Uma base só, com todos os CDs. Mesmo layout da antiga base de origem —
agora com todos os depósitos empilhados. Dela saem as duas pontas:
- excesso (o CD como origem):
disponível + pendente − venda média 3m − estoque objetivo
- falta (o CD como destino):
estoque objetivo − disponível − pendente
- Uma base de pedidos. Você escolhe, por análise, o que o destino precisa:
- Só o saldo ideal → a falta calculada acima (não usa a base de pedidos);
- Consumir os pedidos futuros → os pedidos projetados mês a mês (DRP puro).
- Você define as duas sequências. Primeiro a ordem das origens (quem
escoa primeiro), depois a ordem dos destinos (quem é atendido primeiro).
A demanda é um saldo compartilhado: o que a origem 1 atende some da fila
da origem 2 — por isso a ordem muda o resultado.
- Aprovou, ficou valendo. A linha aprovada vira uma sugestão em carteira
e passa a descontar o excesso da origem e a entrar como trânsito no destino
nas próximas análises — até você importar a base de faturamento, que dá
baixa nela (a partir daí as bases atualizadas já refletem a movimentação).
Um CD pode estar nas duas listas. A única regra absoluta: nenhum CD transfere
para si mesmo.
🧮 Motor de cálculo (lib/engine/)
Puro, sem estado e testado (35 casos). Nenhum número de negócio é fixado em
código — tudo vem de ParametrosRede.
| # | Regra | Como o motor calcula |
|---|
| 1 | Preço | custo de reposição; se 0, preço de lista |
| 2 | Excesso (origem) | MAX(disp + pendente − venda média 3m − objetivo, 0). Com excesso físico ligado, o pendente sai da conta: só o que já está no CD é oferecido |
| 3 | Necessidade (destino) | modo saldo ideal: MAX(objetivo − disp − pendente, 0); modo pedidos: pedido projetado por (mês × CD) |
| 3b | Teto e piso de cobertura | necessidade limitada a venda_dia × dias − (disp + pendente + trânsito). Teto corta demanda inflada; piso garante o mínimo antirruptura. SKU sem giro no destino ignora os dois |
| 4 | Repartição | prioridade estrita (cascata gulosa) ou nivelar dias de cobertura (water-filling: enche primeiro quem está mais descoberto) |
| 5 | Ordem dos baldes | modo pedidos: mês → destino (mês 1 de todos os destinos antes do mês 2); modo saldo ideal: destino a destino |
| 6 | Embarque | opção de caixa fechada (múltiplos da embalagem, ROUNDDOWN), mínimo por linha (un e R$) e carga mínima por rota |
| 7 | Transferência imediata | MIN(transf, disp − venda média × fator), rateada entre os destinos na ordem, em caixa fechada |
| 8 | Cobertura | (disp + pendente) × 30 / venda média, na visão do CD de origem |
| 9 | Impacto fiscal | valor transferido × alíquota da ROTA (origem → destino) |
| 10 | Capacidade operacional | cada alocação consome três orçamentos ao mesmo tempo — expedição da origem, recebimento do destino e transporte da rota. O menor é o gargalo |
| 11 | Materialidade | só entram no plano rotas × SKU com transferência > 0 |
Invariantes verificados a cada análise (reconciliacao):
- nenhuma origem envia mais que o próprio excesso;
- nenhum destino recebe mais que a própria necessidade;
- nenhuma auto-transferência (origem = destino).
Desempenho: rede de 6 CDs × 20 mil produtos (120 mil linhas de base) em
menos de 1 s — teste de performance em lib/engine/calc.test.ts.
Qualidade da sugestão — o que dá para ajustar
Todas essas regras vêm desligadas por padrão (o resultado sai igual à regra
crua da base) e ficam na tela Nova análise. Cada grupo tem uma chave geral
na barra do topo — Teto/piso de cobertura, Caixa fechada e mínimos e
Capacidade operacional — mais um botão Desligar todas as restrições.
Desligar não apaga nada: os valores continuam guardados e voltam a valer quando
a chave é religada, o que torna barato comparar o plano com e sem restrição.
| Regra | Para que serve | Sugestão |
|---|
| Teto de cobertura (dias) | Um estoque objetivo inflado — ou 3 meses de pedido — puxa volume demais para um CD e trava capital do outro lado. O teto converte a demanda em dias de venda. | 60–90 dias |
| Piso de cobertura (dias) | Objetivo defasado ou zerado esconde uma ruptura real: sem piso, o CD em falta não aparece como destino. | 15–30 dias |
| Excesso físico | O pendente ainda não chegou; sugerir a transferência dele gera ordem que o WMS não consegue executar. | ligar quando o plano for executado no curto prazo |
| Nivelar dias de cobertura | Na prioridade estrita, o excesso escasso vai todo para o primeiro CD e o último fica em ruptura. O nivelamento reparte pelo giro. | usar quando os destinos têm importância parecida |
| Caixa fechada | Transferência quebrada não embarca no WMS. | ligar quando a operação exige caixa fechada |
| Mínimo por linha / carga mínima por rota | Cauda longa de 3 unidades e rotas de R$ 200 custam mais em frete e conferência do que o benefício. | mínimo por linha em R$ e carga mínima por rota |
O dashboard mostra a necessidade bruta → considerada por destino sempre que
o teto ou o piso mudou o número, e o plano exporta a coluna não enviado por
caixa fechada.
Capacidade operacional — o plano cabe na operação?
Um plano que sugere mais do que a rede consegue mover não é um plano, é uma
lista de desejos. A análise aceita três limites, válidos ao mesmo tempo:
| Limite | O que representa |
|---|
| Expedição por origem | separação, embalagem e embarque que o CD consegue produzir na janela |
| Recebimento por destino | docas, conferência e endereços livres no CD que recebe |
| Transporte por rota | frota/viagens disponíveis entre aquele par de CDs |
Cada alocação consome os três — o menor é o gargalo. A capacidade é medida
na unidade que faz sentido para a operação, e o motor converte cada unidade
transferida usando dados do próprio SKU:
| Métrica | Fator por unidade | Coluna da base |
|---|
| Unidades | 1 | — |
| Caixas | 1 / embalagem de compra | Qt_Emb_Compra |
| Paletes | 1 / unidades por palete | unidades_por_palete |
| Peso (kg) | peso unitário | peso_unitario |
| Volume (m³) | cubagem unitária | cubagem_unitaria |
| Valor (R$) | preço unitário | custo/preço |
As três últimas colunas são opcionais — a validação da importação lista
quais métricas a sua base sustenta. SKU sem o dado da métrica escolhida não
consome capacidade, e o resultado diz quantos ficaram nessa situação.
Dois detalhes que fecham o ciclo:
- Sugestões aprovadas e não faturadas já ocupam capacidade. A doca e a frota
estão comprometidas com elas; a análise seguinte só distribui o que sobra.
- Com capacidade escassa, a ordem dos SKUs passa a importar. Você escolhe:
carregar primeiro o de maior valor (maximiza R$ escoado) ou o mais
urgente (menor cobertura no destino, reduz risco de ruptura).
O dashboard traz um painel com limite, comprometido, usado, % de utilização e
quanto ficou barrado em cada ponto — e nomeia o gargalo da rede, que é onde
ampliar capacidade libera mais transferência do que remexer prioridades.
npm test
📄 As duas bases (e a terceira, do faturamento)
A base anexada não precisa de nenhuma coluna de fórmula: o app lê só as
colunas cruas e recalcula tudo (mapa em CAMPOS_CALCULADOS, lib/data/schema.ts).
Os cabeçalhos aceitam variações e formato pt-BR (1.234,56); CSV em UTF-8 ou
latin1 é detectado automaticamente.
Base grande? Mande CSV. O CSV é lido em um passe direto (300 mil linhas em
~1,6 s, pico de ~270 MB). XLSX e XLSB passam pelo SheetJS, que carrega a
planilha inteira: as mesmas 300 mil linhas levam ~18 s e passam de 1 GB de
memória — perto do limite de uma função serverless.
1. Base de CDs — origem e destino (obrigatória)
Na importação, informe a data da posição de estoque — é ela que evita
contar duas vezes (ou deixar de contar) uma transferência já faturada.
| Coluna | Campo | Obrigatória |
|---|
| CD / Depósito | cd | ✅ |
Código do produto (CodsemDv) | codigoProduto | ✅ |
| Estoque disponível | estoqueDisponivel | ✅ |
| Estoque objetivo | estoqueObjetivo | ✅ |
| Venda média 3 meses (média mensal) | vendaMedia3m | ✅ |
| Quantidade pendente | quantidadePendente | — |
Custo de reposição (custo, custo_reposicao…) / Preço de lista | custoReposicao / precoLista | — |
Embalagem de compra (embalagem, emb_compra…) | embCompra | — |
Descrição do produto (produto, descricao, descricao_produto) | produto | ✅ |
Categoria N3 (categoria_n3, CAT_NÍVEL_3, categoria) | categoriaN3 | ✅ — é a categoria exibida e filtrada no plano |
| Fornecedor · comprador · analista · categorias N1, N2, N4 | — | — |
| Unidades por palete | unidadesPorPalete | — (só para capacidade em paletes) |
| Peso unitário (kg) | pesoUnitario | — (só para capacidade em peso) |
| Cubagem unitária (m³) | cubagemUnitaria | — (só para capacidade em volume) |
Uma linha por (CD, produto). Chave repetida bloqueia a importação.
2. Base de pedidos (usada no modo pedidos)
ano_mês (aceita 2026_07, 2026-07, 07/2026) · CD destino ·
código do produto · pedido.
3. Base de faturamento (importada na tela Carteira)
CD origem · CD destino · código do produto · quantidade faturada ·
(opcional) documento/NF e data. O casamento é por rota + produto, na ordem
de aprovação, com baixa parcial quando a quantidade faturada é menor que a
aprovada. Linhas sem sugestão correspondente são listadas, e não alteram nada.
A data aceita dd/mm/aaaa (também com - ou .), aaaa-mm-dd, aaaammdd e
a célula de data do Excel (que chega como número, ex.: 46280). Data que
não é reconhecida usa a data do processamento e aparece como aviso na prévia.
A baixa grava tudo numa transação: ou entram todas as baixas e o registro da
importação, ou nada entra.
🔁 O ciclo periódico — nada se perde, nada duplica
Você sobe a base a cada rodada. Entre uma rodada e outra, transferências são
aprovadas, faturadas (ou não), e a base muda. Duas invariantes sustentam isso:
1. A data da posição de estoque decide o que já está refletido.
Ao importar, você informa quando a base foi extraída (não quando está
subindo). O app compara essa data com a data de cada faturamento:
| Situação da sugestão | A base reflete? | O app… |
|---|
| Aprovada, não faturada | não — o estoque não saiu | desconta da origem, trata como trânsito no destino |
| Faturada antes da data da base | sim — a base já mostra a saída | não desconta (contar de novo seria descontar duas vezes) |
| Faturada depois da data da base | não — a base é anterior | continua descontando até a próxima base chegar |
É esse terceiro caso que evita o pior erro possível: importar uma base extraída
antes do faturamento e o app sugerir de novo o que já saiu do CD.
2. Aprovar duas vezes a mesma rota + produto não soma volume inexistente.
- Análise que considerou a carteira: o número que ela sugere já é o
incremento — as aprovações somam, como devem.
- Análise que ignorou a carteira (chave considerar aprovadas desligada):
o número é o total bruto. Somar duplicaria, então o app grava só a diferença
— ou ignora a linha — e avisa exatamente o que fez.
Nenhum dos dois casos exige disciplina do operador: a trava é do app.
Outras proteções do ciclo:
- O mesmo arquivo de faturamento importado duas vezes é recusado (impressão
digital do conteúdo), e uma NF já lançada naquela rota + produto não baixa de
novo, mesmo vindo em outro arquivo.
- Cada baixa guarda quantidade, data e documento — o histórico permite
reconstruir a conciliação, não só o saldo.
- Envelhecimento: sugestões em aberto há mais de 30 dias aparecem em
destaque. Enquanto estão lá, reservam estoque; se a transferência não vai
acontecer, cancelar devolve o volume à próxima análise.
- O armazenamento limpa o que sai da janela (datasets e planos antigos), em
vez de crescer para sempre.
- A carteira não tem teto no cálculo. Compromissos, resumo, baixa por NF e
ordem de transferência usam todas as sugestões em aberto — só a lista da tela
é paginada. Aprovação e baixa gravam em lote (60 mil linhas: ~2 s para aprovar,
~4 s para baixar, medido em Postgres).
🔄 Como uma sugestão caminha
análise → aprova linha → SUGESTÃO EM ABERTO ──(desconta origem e destino)──┐
│ │
│ importa faturamento │ próxima análise
▼ │
FATURADA (bases atualizadas já refletem) ───────┘
- Em aberto: desconta o excesso da origem e entra como trânsito no destino
(no modo pedidos, o trânsito abate os meses mais próximos primeiro).
- Faturada: sai dos compromissos — o estoque já saiu da origem e já aparece
como pendência no destino nas bases atualizadas.
- Cancelada: libera de volta o excesso e a necessidade.
A caixa "Considerar sugestões já aprovadas" permite rodar uma análise do
cenário cheio, ignorando a carteira, sem apagar nada.
🖥️ Telas
-
Dashboard executivo — KPIs (excesso disponível, transferências, cobertura
da necessidade, impacto fiscal), matriz origem × destino (heatmap na
sequência escolhida), aproveitamento por origem, cobertura por destino,
painel de capacidade com o gargalo da rede, maiores rotas e detalhe por
rota (com quebra mensal no modo pedidos).
-
Nova análise — upload das duas bases com validação, escolha do modo de
demanda, sequência de origens, ordem de destinos (cada CD mostra
quanto tem de excesso/falta e o que já está comprometido), alíquotas por rota,
regras de necessidade/materialidade e capacidade operacional. Um clique
roda a análise.
-
Plano de transferência — uma linha por rota × SKU, filtros (origem,
destino, categoria, comprador, cobertura, só imediata), busca, ordenação,
exportação CSV/Excel e aprovação (selecionadas ou todas do filtro).
-
Carteira — sugestões em aberto e faturadas, cancelamento, modal de
importação do faturamento (com prévia) e geração da ordem de
transferência para ERP/WMS com o saldo em aberto.
No dashboard, o histórico de análises permite excluir uma ou várias
(seleção em lote). A confirmação lista o que sai, avisa se é a análise
aberta e mostra quantas sugestões em aberto cada uma ainda tem na carteira —
com a opção de cancelá-las junto (desligada por padrão). Excluir apaga o
resultado e o plano guardado; faturamento já registrado nunca é apagado.
-
Acompanhamento — o que foi aprovado virou NF, e em quanto tempo:
- aprovado × faturado por rota, por CD de origem e por CD de destino, em
R$ ou unidades:
aprovado = faturado + em aberto + cancelado, e o
atendimento é faturado ÷ (aprovado − cancelado);
- tempo da aprovação até a NF: mediana, média e P90, com o volume em
faixas (até 7, 8–15, 16–30, mais de 30 dias). Cada NF pesa pela quantidade
faturada — a mediana diz "metade do volume faturou em até N dias";
- saldo em aberto por idade, com alerta para o que passou de 30 dias.
O período (30, 90, 180 dias ou tudo) filtra pela data de aprovação.
🗄️ O que o app guarda (e o que é descartável)
A decisão de arquitetura é simples: o app guarda resultado, não base.
A base pesada entra, é analisada e sai. O que fica é o resultado.
| Camada | O que é | Onde vive | Sobrevive a deploy/instância? |
|---|
| Carteira | sugestões aprovadas e baixas por faturamento | Postgres (Neon) | ✅ |
| Resultado das análises | parâmetros, KPIs, resumos por rota/origem/destino, o que foi aprovado | Postgres, ou o armazenamento quando não há banco | ✅ |
| Plano | as linhas origem × destino × SKU, só com o que o app usa | Armazenamento, em TSV com dicionário | ✅ |
| Insumo (base + pedidos) | a planilha normalizada | Armazenamento, em TSV comprimido | ✅ |
| Base crua de 900 mil linhas | o arquivo que você sobe | — | descartada após a importação |
O ponto: o plano é pequeno. A base tem 900 mil linhas com dezenas de colunas;
o plano tem as linhas que interessam, com os campos que o app de fato mostra —
e os campos deriváveis (valor, caixas, impacto fiscal, status de cobertura) nem
são gravados, são recalculados na leitura.
Medido na escala real — 11 CDs × 80 mil produtos:
| Etapa | Tempo | Tamanho |
|---|
| Importar a base (880 mil linhas, CSV de 156 MB) | 18 s | insumo guardado: 7,6 MB |
| Rodar a análise (1 origem → 10 destinos) | 2 s (motor: 0,5 s) | 238.800 linhas de plano |
| Guardar o plano | — | 2,2 MB |
| Instância fria: abrir o dashboard | 16 ms | — |
| Instância fria: abrir o plano completo | 948 ms | 325 MB de RSS |
| Filtrar de novo (já em cache) | 54 ms | — |
Visualizar, filtrar, exportar e aprovar não dependem da base: só de rodar uma
análise nova. Enquanto a base estava carregada, o processo usava 1,9 GB; depois
que ela sai de cena, o app trabalha com 325 MB.
Upload de arquivo grande
O corpo de uma função serverless no Vercel não passa de 4,5 MB, e a base real
tem dezenas de MB. Com um Blob store conectado ao projeto, a tela envia o
arquivo direto do navegador para o Vercel Blob e a importação recebe só a
URL — o arquivo nunca atravessa a função. Sem o token, o app cai no upload
tradicional (que funciona local e para arquivos pequenos) e a tela avisa qual
caminho está ativo.
Vale para as três planilhas — base, pedidos e faturamento. Detalhes:
- o arquivo sobe uma vez — Validar e depois Importar reaproveitam o envio;
- acima de 32 MB o envio vai em partes paralelas, com nova tentativa por parte;
- CSV, XLSX e XLSB são aceitos (o tipo é reconhecido pelo conteúdo);
- o arquivo cru é apagado depois da importação; o que foi validado e nunca
importado é apagado em 24 h;
- a importação só aceita URL do próprio Blob, na pasta
upload/.
Números medidos com 300 mil linhas (CSV de 54 MB): importação em ~4 s, e o
insumo normalizado ocupa 2,1 MB no armazenamento.
🚀 Deploy no Vercel
npm install
npm run dev # http://localhost:3000
-
Importe o repositório no Vercel (framework Next.js detectado
automaticamente; vercel.json ajusta o timeout das rotas pesadas).
-
Banco (Vercel Neon / Postgres): crie um banco Neon no painel do Vercel e
conecte ao projeto — POSTGRES_URL (ou DATABASE_URL) é injetada
automaticamente. Opcionalmente aplique o esquema completo:
npm run seed:pg
Guarda a carteira (sugestao_transferencia, faturamento_evento) e o
resultado das análises (analise_resultado) — as tabelas são criadas sob
demanda.
-
Armazenamento de arquivos (Vercel Blob): crie um Blob store com acesso
Private e conecte ao projeto. Lojas novas autenticam por OIDC: o
Vercel injeta só BLOB_STORE_ID, e o upload direto usa URL pré-assinada
emitida pelo servidor. Lojas antigas, com BLOB_READ_WRITE_TOKEN, seguem
funcionando pelo token de cliente. É o que habilita o upload direto (arquivos acima de
4,5 MB) e o que faz o insumo sobreviver à troca de instância. Sem ele, o app
grava em .data/ no disco local — bom para desenvolvimento, efêmero no
serverless.
Por que privado. A base traz estoque e custo de todos os CDs. Numa loja
pública, qualquer pessoa com a URL de um arquivo lê o conteúdo. Na privada,
toda leitura exige o token, que só o servidor tem. O acesso é escolhido na
criação da loja e não muda depois; o app usa privado por padrão. Uma loja
pública já existente só funciona com BLOB_ACESSO=public — prefira criar
outra, privada.
Sem banco e sem Blob, tudo roda em memória: útil para avaliar, mas a tela
sinaliza o estado e nada sobrevive a um novo deploy.
Variáveis de ambiente
| Variável | Para quê |
|---|
POSTGRES_URL / DATABASE_URL | carteira e resultados das análises |
BLOB_STORE_ID | loja do Blob conectada por OIDC (lojas novas) |
BLOB_READ_WRITE_TOKEN | loja do Blob com token fixo (lojas antigas) |
BLOB_ACESSO | public só para uma loja pública antiga (padrão: privada) |
|
Pipeline: PR aprovado → app publicado
- No Vercel, Settings → Git: Production Branch =
main.
- Merge em
main dispara o deploy de produção; cada PR ganha um Preview.
- Para exigir aprovação, ative no GitHub Settings → Branches → Branch
protection em
main: PR obrigatório + aprovação + status check
CI / test-build (.github/workflows/ci.yml, roda npm test e
npm run build).
Autenticação (SSO): lib/auth.ts é um stub pronto para o SSO corporativo
(lê x-user-email). Em produção, plugue o provedor (ex.: Azure AD via
NextAuth) mantendo a trilha de auditoria já existente.
📁 Estrutura
app/ Telas + rotas de API
analise/ Nova análise (bases, sequências, parâmetros)
plano/ Plano de transferência + aprovação
carteira/ Sugestões aprovadas + faturamento + ordem ERP
acompanhamento/ Aprovado × faturado e prazo até a NF
api/ status · cds · params · import · importlog · analise ·
dashboard · plano[/export] · carteira[/ordem] · faturamento ·
acompanhamento
lib/engine/ Motor de rede (puro) + tipos + testes
lib/data/ Esquemas, parsing, validação, leitura de planilha, seed
lib/query/ Filtro/paginação/agregação server-side
lib/store/ Estado da instância, carteira, resultados das análises,
plano persistido, repositório do insumo e armazenamento
lib/export.ts CSV/Excel do plano e ordem de transferência
components/ Nav, UI e o seletor ordenado de CDs
⚠️ Limites conhecidos do modelo
Explícitos de propósito — o motor é guloso e determinístico, não um otimizador:
- Sem custo de frete nem distância. A decisão pesa benefício e ICMS; uma
rota longa e barata em imposto pode não compensar. Hoje isso é compensado na
mão pela ordem dos destinos e pela carga mínima por rota.
- Sem validade (shelf life). Nada impede mandar um lote perto do vencimento
para um CD de giro baixo. A base ainda não traz a data.
- Lead time não entra na conta. A coluna existe na base, mas o motor não usa
para decidir a partir de qual mês a transferência atende — no modo pedidos, o
trânsito abate sempre o mês mais próximo.
- Guloso por produto, não ótimo global. Cada SKU é resolvido isoladamente,
sem consolidar carga por rota nem trocar volume entre SKUs para fechar um
caminhão.
- Capacidade é um teto, não uma agenda. Os limites valem para a janela
inteira da análise: o motor não distribui a carga ao longo dos dias nem
respeita janelas de recebimento por dia da semana.
- Um preço por SKU/origem. A necessidade em R$ é valorizada pelo preço da
primeira origem com custo — se os CDs têm custos muito diferentes, o KPI de
necessidade fica aproximado (o plano, não: cada linha usa o preço da origem).
- Venda média tratada como mensal.
venda_media_3m é lida como média
mensal dos 3 meses. Se a base trouxer a soma do trimestre, o excesso e a
cobertura saem distorcidos — divida por 3 antes de importar.
🔭 Próximos passos previstos
Frete por rota e consolidação
de carga, validade (shelf life) e lead time no horizonte, capacidade por janela
diária, solver de otimização global como modo avançado (a cascata gulosa segue
como padrão) e integração direta com o ERP para dispensar a importação manual
do faturamento.
