Todo sistema de estoque confiável compartilha uma propriedade: a fonte da verdade é um log do que aconteceu, não um saldo corrente. Banco faz assim. Software contábil faz assim. Maioria dos ERPs faz — e esconde atrás de uma interface que finge o contrário.
O modelo de saldo corrente é sedutor porque é rápido. Uma linha por produto, um inteiro para atualizar, uma leitura para responder 'quantos a gente tem?' Também é frágil, porque aquele inteiro único é um valor derivado sem proveniência. Quando está errado — e uma hora vai estar errado — não tem como saber por que, quando, ou por quem. Você só pode corrigir sobrescrevendo, o que destrói a evidência do erro.
Por que append-only Se toda mudança vira uma linha e nenhuma linha é editada, a trilha de auditoria é trivial. 'Qual era o estoque da SKU AB-001 em 14 de março?' vira um SUM de SQL. 'Quem moveu isso?' vira um JOIN simples.
A diferença operacional é enorme. Num sistema mutável, responder uma pergunta histórica exige confiança — confiança que ninguém editou o histórico, que o backup está correto, que a pessoa que fez a mudança lembrou de registrar em outro lugar. Num sistema append-only, responder uma pergunta histórica exige uma query. A resposta é determinística, reprodutível, e admissível numa disputa com cliente ou auditor.
Sem botão de delete
O admin do StockMovement desabilita add/change/delete explicitamente — até para superuser. Correções passam por POST /api/stock/{id}/adjust/, que grava uma linha ADJUSTMENT com nota obrigatória. O ledger continua honesto.
Essa é a disciplina que faz o append-only funcionar. Se existe uma porta dos fundos — um DBA que pode UPDATE stock_movement SET quantity = 5 WHERE id = 1234 — então o ledger é só um log com asterisco. Ao desabilitar toda operação mutante no admin do Django e prover um único caminho de correção auditável, a gente garante que todo número no ledger tem rastro. Até as correções têm rastro — a nota de ajuste é obrigatória, timestamped, e atribuída ao admin que a fez.
Cache, não verdade
StockItem.on_hand e StockItem.reserved são cache, atualizados na mesma transação que a escrita do ledger. Se divergirem, o ledger reconstrói.
O cache existe por performance — você não quer SUM de seis anos de movimentação de estoque toda vez que renderiza a página de inventário. Mas o cache é descartável por design. Um comando de management pode zerar todo StockItem e reconstruir do ledger numa única passada. Esse padrão de design — cache como otimização, ledger como verdade — é emprestado dos sistemas contábeis e aplicado ao estoque. Não é novidade, mas é correto, e correção em estoque vale mais que novidade.