Orçamento

O desenho ingênuo quebra em silêncio

A implementação óbvia é BudgetLine(amount, consumedAmount) com UPDATE consumed = consumed + x em cada aprovação. Ela funciona no caminho feliz e quebra em quatro lugares previsíveis: a requisição devolvida (quanto estornar, se o valor mudou na rodada?), o pedido cancelado parcialmente, a nota que chega com preço diferente do pedido, e o reprocessamento de uma mensagem duplicada. Em nenhum desses casos o sistema acusa erro — ele passa a mostrar um saldo errado, e ninguém descobre até a conversa com a controladoria em que os números não batem.

O que o razão dá de graça: resposta linha a linha para "quem comeu minha verba", reversão correta por construção, idempotência por chave natural, e reconstrução completa do saldo a partir dos fatos quando alguém desconfiar do número.

Saldo é projeção, com uma tabela materializada por desempenho

A verdade é BudgetEntry. Para não somar milhões de linhas a cada digitação de requisição, existe BudgetLineBalance — uma linha por budgetLineId × estágio, atualizada por upsert na mesma transação do movimento. Ela é cache, não fonte: um comando administrativo a reconstrói inteira a partir do razão, e a divergência entre as duas é o teste de integridade que roda em ambiente de homologação.

A consulta informa; o servidor decide

budgetStateFor é leitura sem trava, serve para pintar a tela enquanto a pessoa digita e pode estar desatualizada no instante seguinte. O bloqueio real acontece dentro da transação que grava o movimento, sob trava da linha de saldo. Nenhuma decisão de bloqueio confia numa consulta anterior — dois pedidos simultâneos contra a última fatia de verba não podem passar os dois, e essa é a única forma de garantir isso.

A regra, em uma frase

Cada estágio liquida o anterior na proporção do que avançou. O resíduo só é liberado no encerramento explícito do documento de origem. O pedido de 60 das 100 unidades liquida 600 do comprometido e deixa 400 presos — porque as outras 40 unidades ainda são uma intenção viva. Elas só voltam para o saldo quando alguém encerra a requisição, e esse encerramento é ação de domínio com dono, não faxina automática.

Diferença de preço é consumo real, não erro

O pedido saiu a R$ 11 e a requisição tinha estimado R$ 10. O razão mostra 60 unidades liquidando 600 de comprometido e criando 660 de empenhado — os R$ 60 de diferença aparecem como consumo adicional, que é exatamente o que aconteceu no mundo. Nenhuma conta é "corrigida" para trás.

Idempotência é chave natural, não tentativa

Todo movimento carrega idempotencyKey único, derivado de (sourceType, sourceId, sourceLineId, allocationId, stage, sequence). Reprocessar a mesma mensagem — reentrega de fila, duplo clique, retry de integração — colide no índice único e é descartado sem efeito. Não existe "verificar se já lancei"; existe deixar o banco recusar.

Rateio: a fatia é a unidade, sempre

Uma linha de documento com CostAllocation de 70% / 30% gera dois conjuntos de movimentos, contra duas combinações de dimensões que podem cair em verbas diferentes, com políticas diferentes, e uma pode bloquear enquanto a outra passa. O bloqueio é do documento: se qualquer fatia bloqueia, a operação inteira é recusada — não existe gravar meia linha. O resíduo de arredondamento segue a regra já fechada no Centro de Custo: vai para a maior fatia, empate pelo menor order.

1 · O exercício

O Budget da empresa, com status Approved ou Closed, cujo intervalo contém a data de necessidade. Não pode haver dois — a sobreposição de períodos entre exercícios aprovados da mesma empresa é recusada no banco, por EXCLUDE com btree_gist, mesma mecânica de ApprovalPolicy e CostCenterAssignment. Se não houver exercício, o resultado é NotControlled e acabou.

2 · A política efetiva

BudgetPolicy resolvida para o nó de centro de custo, subindo o path, campo a campo: requiresBudget pode vir do nó, overBudgetPolicy do avô e carryForwardMode do padrão do tenant. Se requiresBudget resolver como falso, o resultado é NotControlled — o movimento ainda é gravado, mas nada é consultado nem bloqueado.

3 · A linha, pela especificidade

Entre as linhas do exercício cujo período contém a data de necessidade, ficam as candidatas em que costCenterId é nulo ou é ancestral-ou-igual do nó da fatia (prefixo de path), e glAccountId é nulo ou é ancestral-ou-igual da conta da fatia. Vence, nesta ordem: maior especificidade (2 = as duas dimensões preenchidas, 1 = uma, 0 = coringa), depois maior depth do centro de custo, depois maior depth da conta. O critério é total e determinístico — não existe empate.

4 · Nenhuma linha cobre

Escopo controlado e nenhuma candidata: resultado Uncovered, e a operação é recusada com 422 nomeando a combinação. A saída para o cliente não é afrouxar a regra — é cadastrar a linha coringa daquele centro de custo, que cobre toda conta que ninguém previu.

Unicidade com duas colunas anuláveis

A chave lógica é (budgetId, costCenterId, glAccountId, periodKey), mas no Postgres dois nulos não colidem — um índice único simples deixaria criar duas linhas coringa idênticas. Como já foi feito em UserCompanyScope, a unicidade sai em quatro índices parciais: ambos preenchidos, só centro de custo, só conta, e nenhum dos dois. É verboso e é a única forma correta.

Linha só muda por documento, depois de aprovada

Enquanto o exercício está em Draft, editar linha é edição comum. Depois de Approved, amount não é mais editável: a mudança vem de BudgetChangeRequest aprovado, que grava movimento de Adjustment. O valor efetivo de uma linha passa a ser amount + Σ Adjustment — e o histórico de por que a verba cresceu fica no razão, com justificativa e aprovador, em vez de sumir num UPDATE.

Herança campo a campo, e a API devolve de onde veio

Cada campo sobe o path por conta própria: requiresBudget pode vir do nó "Obra Guarulhos", overBudgetPolicy de "Operações" e carryForwardMode do padrão do tenant. É mais flexível e é mais difícil de explicar em tela — por isso GET /budget-policies/effective devolve, para cada campo, o valor e o nó de onde ele veio, exatamente como effectiveOwners devolve inheritedFrom. A tela mostra "herdado de Operações" ao lado de cada linha, e ninguém precisa adivinhar.

Remanejamento não pode deixar a origem negativa

Na aprovação, o servidor revalida o saldo da linha de origem naquele instante, sob trava — não no momento em que o pedido foi feito. Verba pode ter sido consumida durante a aprovação. Se não couber, a aprovação falha com 422 e o documento volta ao solicitante com o número atual, em vez de deixar a origem estourada.

Movimento, não versão

Movimento ajusta o orçado; versão substitui o exercício. Suplementar R$ 80 mil em março é um Adjustment — a linha original continua visível, e a diferença tem autor, data e justificativa. Refazer o plano inteiro no meio do ano é Budget versão 2, com o razão do anterior preservado e reapontado. Confundir os dois é como confundir commit com force push.

available depende do modo de leitura

Com PeriodOnly, é budgeted(março) − consumed(março). Com Cumulative (acumulado), é Σ budgeted(janeiro..março) − Σ consumed(janeiro..março). Mesmo razão, mesma linha, janela diferente — e é por isso que o modo aparece na resposta: a tela precisa poder dizer "R$ 18.400 disponíveis no acumulado do ano", que é uma frase diferente de "R$ 18.400 disponíveis em março".

O rollup do centro de custo é do lado da verba, não do consumo

Uma verba em "Operações" cobre "Operações › Manutenção › Elétrica". O consumo daquela fatia é gravado com o nó folha e resolvido para a linha de "Operações" — então o extrato da verba mostra o gasto das três folhas somado, e cada movimento continua sabendo de qual folha veio. Não existe verba "consolidada" calculada por cima: existe uma linha, com consumo de vários nós.

O motor de aprovação usa isto como critério, e nada mais

O motor lê signal e wouldExceedBy como critérios de política — "estourou a verba" acrescenta um nível com a controladoria, exatamente como "valor acima de X" acrescenta um diretor. O motor não conhece verba e não grava movimento; quem grava é o agregado do documento, na transição. A dependência é num sentido só, como já é com centro de custo.

A competência é a data de necessidade

O balde de um movimento é escolhido pela data de necessidade da linha do documento — quando a coisa precisa existir — e não pela data em que o documento foi criado ou aprovado. A requisição feita em 20 de dezembro para entrega em 15 de janeiro consome janeiro desde o primeiro movimento.

Por quê: é a leitura econômica correta e mata a corrida de fim de ano, em que todo mundo empurra pedido em dezembro para não perder verba. E resolve de graça o problema mais chato da virada — o compromisso que atravessa o ano já nasce no ano certo.

O que custa: mudar a data de entrega remaneja consumo entre baldes. O tratamento é o mesmo de sempre: dois movimentos com reasonCode = DateChange, negativo no balde velho e positivo no novo, e se o novo balde não couber, vale a política de estouro daquele nó. Nunca um UPDATE em competencePeriodKey.

PeriodOnly × Cumulative — e por que nenhum dos dois transporta nada

O desenho óbvio de carry-forward é transportar: no fechamento de março, movimento negativo em março e positivo em abril. Funciona e arrasta duas coisas pesadas — fechamento mensal vira operação obrigatória (alguém precisa declarar que março acabou) e a nota atrasada quebra o fechamento (reabrir período, recalcular transporte, reescrever abril). Todo ERP que faz assim tem uma tela de reabertura de período e um chamado por mês por causa dela.

Aqui é modo de leitura. O razão é idêntico nos dois casos; muda a janela do somatório. Cumulative é carry-forward, exato, sem linha de transporte, sem fechamento e sem reabertura: a nota de março que chega em 8 de abril entra na soma e o disponível de abril se corrige sozinho — que é o comportamento certo, e no modelo de transporte seria um incidente.

O que se perde: o registro formal "em 31/03 foram transportados R$ 12.400". Isso vira consulta, renderizada na tela de acompanhamento, e não um fato gravado. Se algum cliente de setor regulado exigir o registro imutável, o fechamento formal nasce depois como opt-in — o razão já suporta, bastam os movimentos CarryOut/CarryIn que a virada de exercício já usa.

Cumulative nunca atravessa exercício

A janela do acumulado é periodStart do exercício até o balde consultado. Em 1º de janeiro ela reinicia, sempre, qualquer que seja a política. O que sobrou de 2026 morre em 2026. Atravessar a virada é assunto da seção seguinte, tem regra própria e exige decisão explícita — não pode ser efeito colateral de um modo de leitura.

A convergência

Os três produtos privados fazem a mesma coisa e discordam só num ponto. Iguais: o compromisso aberto atravessa a virada — é revertido no exercício que fecha e recriado no novo, sem que ninguém redigite documento. Diferentes: se a verba vai junto — e nos três isso é opção do cliente, não do produto.

A recomendação · CarryCommitmentOnly como padrão

Ao fechar o exercício, cada saldo aberto de Commitment e Obligation gera um CarryOut negativo no exercício que fecha e um CarryIn positivo no novo, mantendo a mesma cadeia de documento, com competenceDate remapeada para o primeiro balde aberto e a taxa de câmbio preservada. A verba não vai junto.

Na visão do sócio. O número de 2027 foi decidido para 2027. Se o compromisso trouxesse verba automaticamente, o ano começaria comprometido por um valor que ninguém aprovou — e no primeiro mês o controle vira ficção: quanto mais atraso houve em dezembro, mais orçamento aparece do nada em janeiro, o que premia exatamente o comportamento que ele quer evitar. Com o padrão, o que sobrou de 2026 morre em 2026 e qualquer aperto aparece como estouro em janeiro — que é o momento em que ele quer ser consultado, com nome, valor e documento na frente.

Na visão do requisitante. O documento não morre, não precisa ser redigitado e não volta para a fila de aprovação: a cadeia já cumprida é preservada, pela mesma regra do motor de que continuidade e redução não reavaliam. Ele só descobre que houve virada se houver aperto real — e nesse caso o que ele vê é a política de estouro do nó dele, um caminho que ele já conhece, e não uma mensagem de erro sobre exercício encerrado.

As duas outras opções, e quando fazem sentido

CarryCommitmentAndBudget emite, junto com o CarryIn, um Adjustment de mesmo valor na linha do novo exercício, e um Adjustment negativo no exercício que fecha. É o caso de obra e projeto plurianual, em que a verba foi aprovada para o projeto e não para o calendário. Ressalva registrada: para esses casos a resposta melhor é um Budget com periodStart/periodEnd cobrindo o projeto inteiro — a opção existe como saída para quem já tem o orçamento partido por ano e não quer remodelar.

CancelOpen estorna os compromissos abertos e devolve os documentos ao estado anterior, forçando redecisão no ano novo. Existe porque algumas empresas querem exatamente isso na virada, e não é o padrão porque a maioria só quer que a compra de janeiro aconteça.

Nota atrasada de dezembro

Actual com competência num exercício Closed é aceito até lateActualsUntil, desde que liquide um Obligation daquele mesmo exercício. Sem isso, a nota de dezembro que chega em janeiro cairia em 2027 — consumindo verba nova por uma entrega que já tinha sido orçada e empenhada em 2026, o que estoura o ano novo por um fato do ano velho. Passada a janela, o exercício vai a Archived e a nota tardia é lançada em 2027 com reasonCode próprio, aparecendo no relatório de despesa de exercício anterior.

Documento em aprovação na virada

Requisição ainda em aprovação não tem movimento nenhum — o Commitment nasce na conclusão da cadeia. Se ela conclui em janeiro com data de necessidade em dezembro, o balde de destino está num exercício fechado: a competência é reapontada para o primeiro balde aberto, com aviso na tela e no evento. Como valor, centro de custo e rateio não mudaram, a cadeia de aprovação não é reavaliada.

O exercício tem uma moeda; os documentos têm a que tiverem

Company.functionalCurrency — que já existia na spec de Empresa como metadado informativo e passa a ter consequência a partir daqui — define em que moeda a pessoa jurídica orça e presta contas. Padrão BRL, e só BRL na v1, por decisão registrada na spec de Moeda e Câmbio: o boletim do Banco Central publica moeda contra real e mais nada, e conversão cruzada sem fonte produz número plausível e errado. Budget.currency é copiada dali na criação e congelada.

Um exercício não tem duas moedas. Empresa que quer acompanhar o mesmo orçamento em real e em dólar está pedindo relatório com conversão de apresentação, não um segundo orçamento — e dois orçamentos concorrentes para o mesmo período colidiriam com a regra de não-sobreposição, que existe justamente para não haver duas verdades.

A conversão acontece uma vez, no movimento, e nunca é refeita

Cada BudgetEntry guarda amountDocument e currencyDocument como estão no documento, mais exchangeRate, quoteUnit, rateType e rateDate, e o amount já convertido para a moeda do exercício. Como valores, não como chave estrangeira — se a cotação for substituída depois por retificação de boletim, o movimento gravado não muda.

Reavaliação retroativa não existe. Se a taxa de ontem mudasse o consumo de hoje, o saldo mudaria sozinho durante a noite e ninguém conseguiria explicar para o gestor por que a verba encolheu sem ninguém ter comprado nada.

A variação cambial aparece sozinha, e é consumo de verdade

Pedido de US$ 10.000 a 5,20 grava Obligation de R$ 52.000. A nota chega com o dólar a 5,60: a liquidação estorna o empenho pela taxa dele (−52.000) e lança Actual pela taxa nova (+56.000). Os R$ 4.000 de diferença consomem verba, porque consumiram caixa. Nenhum tratamento especial, nenhuma conta de ajuste — e o relatório de variação cambial é a soma dos deltas das cadeias cuja currencyDocument difere da moeda do exercício.

Converte-se a fatia, e a taxa que faltou recusa o documento inteiro

O rateio acontece na moeda do documento e cada CostAllocation converte separadamente — converter o total e depois ratear faz a soma das linhas do extrato não bater com o total do documento. Sem cotação para o par, o tipo e a janela, o lançamento é recusado com EXCHANGE_RATE_MISSING 422 e a atomicidade por documento vale igual: nada é gravado. O sistema nunca estima taxa.

A janela de tolerância para trás, o tipo padrão e o comportamento em fim de semana e feriado são de CurrencySettings — a entidade que rascunhos anteriores desta spec chamavam de BudgetSettings. A rateDate efetivamente usada e a idade em dias voltam na conversão, são gravadas no movimento e aparecem no extrato: "US$ 10.000 × 5,2013 · PTAX venda de 29/12 (2 dias)".

Taxa contratada

Compra com câmbio travado usa a taxa do contrato, não a do dia: o documento carrega exchangeRateOverride com rateType = Contracted, exige a permissão override:exchange_rate e registra quem informou e com que referência. É a única forma de a taxa não vir da resolução, e ela fica visível no extrato da verba.

Tolerância é o menor dos dois

tolerancePercent aplicado sobre o orçado da linha, toleranceAmount em valor absoluto; quando os dois existem, vale o menor. Cinco por cento é razoável numa verba de R$ 200 mil e é meio milhão de folga invisível numa de R$ 10 milhões — e é sempre a verba grande que ninguém revisou. Dentro da tolerância o sinal é Warning e a política não dispara; passou dela, é Exceeded e a política manda.

Não existe furar bloqueio

Não há permissão de override de bloqueio orçamentário, e isso é decisão, não esquecimento. Toda porta de fuga vira o caminho normal em três meses: quem tem a permissão passa a ser chamado para toda compra apertada, e o controle deixa de existir sem que ninguém tenha decidido desligá-lo. O caminho sancionado para gastar mais do que se orçou é pedir mais verba — BudgetChangeRequest, com justificativa e aprovação — ou mudar a política do nó para RequireApproval, o que é uma decisão registrada com vigência e autor.

A avaliação é sobre a fatia, e o bloqueio é do documento

Cada fatia é avaliada contra a sua própria verba, com a sua própria política — 70% em Operações com Block e 30% em Marketing com Warn é uma combinação normal. Mas gravar é atômico: se qualquer fatia bloqueia, nada é gravado. O erro devolve a lista das fatias que falharam, não a primeira.

Importado — o caminho da maioria

O número aprovado já existe, em planilha ou no ERP. Entra por carga em lote, o exercício nasce direto em Approved e ninguém dentro do Nexio decide valor nenhum. É o caminho esperado do primeiro cliente e o único que precisa estar pronto no dia um.

Planejado — coleta e aprovação, sem motor novo

O exercício nasce em Draft. Cada dono de nó — os mesmos CostCenterAssignment que já respondem pela alçada — preenche as linhas da sua subárvore; ninguém enxerga nem edita o que não é seu, pela mesma regra de recorte da visibilidade de valores. Fechada a coleta, o exercício vai a InReview e abre instância do processo ORCAMENTO no motor que já existe. Devolver reabre a edição sem matar a instância, como em qualquer outro documento.

É uma máquina de estados e duas telas. Não é um módulo — e é por isso que dá para oferecer sem virar concorrente de FP&A.

Revisar — movimento ou versão, e a diferença importa

Movimento (BudgetChangeRequest) para o ajuste pontual: suplementar março, remanejar de Marketing para TI, devolver verba. A linha original continua visível e a diferença tem autor, data e justificativa.

Versão quando o plano inteiro é refeito — reorçamento de meio de ano, mudança de estrutura societária, obra replanejada. Nasce como cópia em Draft, passa pelo mesmo processo ORCAMENTO, e ao ser aprovada arquiva a anterior. O razão não é reescrito: os movimentos do exercício antigo continuam apontando para as linhas antigas, e a versão nova recebe movimentos de CarryIn equivalentes ao consumido até ali, para que o disponível não pule. Refazer o plano nunca apaga o que já foi gasto.

A trava é a linha de saldo, e é curta

A transação de gravação segue sempre a mesma ordem: resolver as linhas de todas as fatias, ordenar os budgetLineId por id, travar nessa ordem com FOR UPDATE, reavaliar, inserir os movimentos, atualizar os saldos, confirmar. Ordenar antes de travar é o que evita deadlock entre dois documentos que tocam as mesmas duas verbas em ordem inversa — e é a única forma que sobrevive a produção.

Índices que precisam existir desde o primeiro dia

Em BudgetEntry: (tenantId, budgetLineId, stage) para a projeção; (tenantId, sourceType, sourceId) para o estorno e o extrato por documento; (tenantId, costCenterId, competencePeriodKey) para o consumo fora de verba; único em idempotencyKey. Em BudgetLine: (budgetId, periodKey, specificity DESC), mais os quatro índices parciais de unicidade. Em BudgetPolicy: (tenantId, costCenterId) com EXCLUDE de vigência.

Ordem de grandeza

Um cliente de mil requisições por mês, três linhas cada, duas fatias por linha, gera cerca de seis mil movimentos por estágio e por mês — algumas centenas de milhares de linhas ao ano. É pequeno para o Postgres e não justifica particionamento no lançamento. O particionamento por budgetId fica declarado como gancho para quando o primeiro cliente grande aparecer, e não antes.

A consulta de digitação é barata de propósito

budget-state:evaluate lê BudgetLineBalance e a política resolvida, sem trava e sem tocar o razão. Ela é chamada a cada mudança de linha na tela do requisitante, então precisa ser dois selects indexados — e é por isso que a projeção materializada existe, mesmo o razão sendo a verdade.