O bug de estoque mais comum na distribuição é o mesmo, em toda empresa, independente do tamanho: tratar reservado como se ainda estivesse disponível. É a raiz por trás de venda a descoberto, de desconfiança do almoxarifado no comercial, das ligações frenéticas de sábado de manhã quando o motorista chega para buscar produto que não está lá.
A armadilha de um campo só
Se a sua tabela de estoque tem uma coluna — quantidade — você só consegue subtrair. Quando a cotação fecha, subtrai. Quando cancela, soma de novo. Qualquer entrega concorrente envia a quantidade errada.
A causa raiz é que um campo só não distingue entre estoque fisicamente presente e estoque prometido. Os dois estados colapsam no mesmo inteiro. Funciona num sistema de um usuário onde a pessoa que subtrai é a mesma que sabe o que está prometido. Quebra no momento em que duas pessoas tocam o sistema — e quebra silenciosamente. Nada lança erro quando você sobrevende. O número simplesmente fica negativo, ou pior, fica positivo mas representa uma promessa que você não pode cumprir.
Dois campos, uma propriedade
O Quotery usa dois campos — on_hand e reserved — com available = on_hand − reserved. Fechar cotação aumenta reserved; cancelar diminui. Só uma nota de entrega postada reduz on_hand. A conta fecha em qualquer cenário concorrente.
A separação é o que torna seguro. on_hand responde 'o que está fisicamente no armazém?' reserved responde 'o que está comprometido com cotação fechada?' available responde 'o que ainda posso prometer para o próximo cliente?' Cada campo tem exatamente um escritor — on_hand muda só por documentos de fulfillment postados; reserved muda só por transições de estado da cotação. Nenhum campo é tocado por dois fluxos diferentes, então não tem condição de corrida.
Esse design também possibilita a super-reserva como escolha deliberada. Quando uma cotação fecha com estoque disponível insuficiente, reserved pode exceder on_hand — available fica negativo, o que é um sinal visível, não uma falha silenciosa. O time comercial vê e age. A restrição é imposta na entrega, não na cotação. Veja mais no nosso post sobre por que super-reserva é feature.
Ledger, não conta
Todo movimento vira uma linha em StockMovement. Os números no item de estoque são cache; o ledger é a verdade. Reconstruir qualquer ponto no tempo é uma query, não uma oração.
O ledger significa que você responde perguntas que sistemas de campo único nem conseguem fazer. Qual era o estoque disponível da SKU X na terça passada às 15h? Quais cotações estavam segurando reserva contra este produto quando o recebimento chegou? Se o on_hand cacheado algum dia divergir da soma das entradas do ledger, o ledger é o árbitro. Você reconstrói o cache a partir do log — nunca edita o log para bater com o cache.