Fechar uma cotação é a transição de vendas para fulfillment. Também é a transição mais perigosa de qualquer sistema de distribuição quando é feita errado.
Num sistema caseiro, 'fechar' pode ser mudar uma célula de status na planilha. Num ERP, pode disparar uma cascata de efeitos colaterais não documentados. No Quotery, são cinco passos explícitos dentro de uma única transação de banco, e cada um deles deixa rastro no ledger. Aqui está a sequência exata.
Os cinco passos, atômicos
1. Lock na linha da cotação com select_for_update(). Isso serializa fechamentos concorrentes na mesma cotação — só um chamador prossegue, o resto faz fila.
2. Para cada linha, lock no StockItem com select_for_update() ordenado por (product_id, location_id). A ordenação é crítica — garante que duas cotações concorrentes fechando contra conjuntos sobrepostos de produtos adquiram locks na mesma ordem, prevenindo deadlock.
3. Incrementa reserved em cada StockItem e grava uma linha RESERVE no ledger StockMovement para cada linha. Cada RESERVE carrega o id da cotação, id do produto, id da localização, quantidade e timestamp.
4. Monta lista de shortages para cada linha que não deu para reservar completamente. Isso é informativo — a cotação fecha igual. O chamador recebe um array shortages com ids de produto e a diferença entre solicitado e disponível.
5. Transiciona o status da cotação para closed e comita a transação.
Shortage é informação, não falha
Por design, close_quote não 409 em estoque baixo. Você recebe um array shortages com números exatos. O comercial decide o que fazer — reservar assim mesmo, ajustar, ou negociar.
Essa é a inversão deliberada descrita no post sobre super-reserva. A maioria dos sistemas trata falta de estoque como erro bloqueante. A gente trata como sinal. O comercial conhece o pipeline melhor que o sistema. Sabe o que está chegando na semana que vem, quais clientes são flexíveis, e quais linhas podem ser divididas em entregas. O trabalho da ferramenta é dar os números — não tomar a decisão.
O que roda rollback Tudo. A transação é atômica. Um erro de DB no passo 3 faz rollback dos 1 e 2. Você nunca termina com metade da reserva.
Na prática, o principal modo de falha é problema de conectividade com o banco ou deadlock (resolvido pela ordenação de lock no passo 2). O chamador tenta de novo e a transação roda limpa. Não existe 'cotação travada', não existe 'status diz fechada mas estoque não foi reservado', não existe job de limpeza que conserta estado quebrado de madrugada. Atomicidade significa que a máquina de estados tem exatamente dois resultados: a transação comitou e tudo está consistente, ou não comitou e nada mudou.