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.

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.

O contrato dos sinais, e o que cada um obriga — novo em v1.8

BudgetSignal tem cinco valores. NotControlled é a ausência de controle e não é critério de nada: nem o motor nem o serviço de lançamento fazem qualquer coisa com ele. Os outros quatro são o contrato que evaluate:budget-states publica, e cada um obriga a exatamente uma coisa:

Uncovered significa ausência de exercício apto ou linha em escopo controlado. Impede novo compromisso sem passar por tolerância. Actual ocorrido é registrado com pendência de classificação; a mensagem indica o que falta corrigir e a classificação posterior é balanceada.

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.

E quando há linha no pai e no filho, o extrato do pai enxerga o filho — corrigido em 09/09/2026. A consulta devolve dois números por nó: consumedOwn, o que foi resolvido para aquela linha, e consumedSubtree, que soma também o consumo resolvido para linhas de descendentes, por prefixo de path. Até a v1.7 o extrato de /TI/ mostrava o gasto de /TI/INFRA/ como zero, e as duas verbas somavam poder de gasto em vez de se conterem — o contrário do que a metáfora "caixas dentro de caixas" promete e do que Oracle Budgetary Control e SAP FM fazem, que é aplicar o controle em vários níveis ao mesmo tempo. O disponível de cada nó continua sendo o dele: consumedSubtree é o que a política do ancestral avalia (RN-O31).

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 — chamado pelo contrato de desfecho do processo, na mesma transação da decisão (RN-AP-38). A dependência é num sentido só, como já é com centro de custo.

A competência é a data de necessidade

O estágio define a competência, conforme RN-O11. Requisição de dezembro para necessidade de janeiro reserva janeiro; recebimento em outra data registra seu fato e liquida a imputação vigente da obrigação. Contabilização e competência original permanecem identificadas.

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 entryReason = 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 de virada — negativo e positivo nos próprios estágios, com entryReason = YearEndRollover, que é a mesma mecânica da virada de exercício (RN-O13).

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 movimento negativo no próprio estágio no exercício que fecha e um positivo no mesmo estágio no exercício novo, os dois com entryReason = YearEndRollover e sourceType = Rollover, 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.

Corrigido em 09/09/2026 — e é o que faz a Decisão 8 ser verdade. Até a v1.7 a virada usava dois estágios próprios, CarryOut e CarryIn, que não entravam no somatório de consumed e não tinham campo em amounts: o compromisso "carregado" era invisível, janeiro abria com a verba integral e o aperto de dezembro simplesmente sumia — o oposto exato de "aperto vira estouro em janeiro". Gravando nos próprios estágios, o carregado consome desde o primeiro dia, sem enum novo e sem campo novo na consulta de saldo (RN-O13).

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 movimento positivo do estágio no exercício novo, um Adjustment de mesmo valor na linha desse exercício, e um Adjustment negativo no exercício que fecha — os dois com origem Rollover, que é a terceira e última porta de entrada de Adjustment junto com BudgetChangeRequest e Import (RN-O28). É 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 encerra somente parcelas cujo cancelamento de negócio seja válido. Requisição sem obrigação efetiva pode voltar para redecisão; pedido emitido e mínimo contratual permanecem vigentes até alteração ou rescisão válida. Parcelas ainda devidas atravessam a virada por reclassificação balanceada, nunca por apagamento automático da obrigação.

Nota atrasada de dezembro

Fato tardio permanece registrável. Até lateActualsUntil, lançamento na competência original pode ser autorizado; depois, período aberto com originalCompetenceDate e referência ao recebimento/aceite e à imputação vigente da obrigação. Não exigir obrigação ainda aberta no exercício antigo nem cobrar novamente saldo já transportado.

Documento em aprovação na virada

Requisição em aprovação não tem Commitment. Se a competência planejada fechar antes da conclusão, devolver para corrigir a revisão e reavaliar período, política e verba. Não mover silenciosamente para o primeiro balde aberto preservando assinaturas sobre conteúdo diferente.

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 qualquer ISO 4217 já na v1 — a restrição "só BRL na v1" saiu em 09/09/2026: um grupo com uma empresa em USD e outra em BRL é o caso que o produto declara atender, e a restrição fazia quatro páginas discordarem entre si. O que continua valendo é a ressalva de fonte: o boletim do Banco Central publica moeda contra real e mais nada, então par sem cotação vigente recusa, e não se estima taxa cruzada. 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, na submissão do documento, e o razão herda — corrigido em v1.8

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.

Quem escolhe o número é a submissão, não o lançamento. Até a v1.7 esta spec dizia que a conversão acontecia "no movimento", com resolução própria que podia até recusar o lançamento — e o Fluxo dizia que a taxa é a da submissão, "o único momento de conversão na vida do documento". Como o Commitment nasce dias depois, na conclusão da cadeia, as duas regras davam números diferentes para o mesmo dinheiro. Vence a submissão: todo movimento originado por documento copia exchangeRate, quoteUnit, rateType e rateDate do documento; o negativo de liquidação copia da entrada que liquida (RN-O30). A resolução própria de taxa desta spec passa a valer só para movimento sem documento de origem — Manual e Import (RN-O41). Cada documento seguinte da cadeia converte na sua própria submissão, e é dessa diferença que nasce a variação cambial abaixo.

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_UNPROCESSABLE 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-rates 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.