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 BudgetBalance — uma linha por tupla concreta (empresa, centro de custo, conta, balde, estágio), atualizada na mesma transação do movimento e só quando o movimento de fato entrou (RN-O34). O saldo de uma BudgetLine não é gravado em lugar nenhum: é a soma, lida na hora, das tuplas que caem sob ela. A projeção é 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

POST /evaluate:budget-state é 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 a trava das linhas de orçamento que podem recusar ou exigir aprovação (RN-O47). 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.

O grupo do ato e o saldo aberto

Todo movimento que nasce de um mesmo ato carrega o mesmo postingGroupId. No pedido do exemplo, o grupo tem duas entradas: E2 · Obligation +660 e E3 · Commitment −600, esta com liquidatesEntryId = E1 (a requisição, Commitment +1.000). O saldo aberto de uma entrada positiva é o valor dela, mais todo negativo que a aponta — por liquidatesEntryId ou reversalOfEntryId —, mais os estornos desses negativos que não carregam pairedEntryId, mais os estornos que a apontam em pairedEntryId — a restituição desviada para a entrada mais recente da cadeia quando o alvo do negativo estornado foi levado pela virada ou relançado pela correção de taxa (RN-O43). É a definição da RN-O42, a única do módulo. Depois do pedido, o aberto de E1 é 1.000 − 600 = 400, e o de E2 é 660.

Nenhum negativo passa do aberto do alvo. Liquidação, liberação de resíduo, remanejamento e virada consomem no máximo o saldo aberto da entrada que apontam; o que o ato tiver além disso é consumo novo, não liquidação. Quando a linha de origem tem mais de uma entrada aberta, consome-se a mais antiga primeiro — a ordem é determinística —, e a entrada levada pela virada ou relançada pela correção de taxa nunca é escolhida: responde por ela a mais recente da cadeia (RN-O42).

Estorno é sobre o grupo — e é isso que restitui

Estornar um ato é estornar o grupo inteiro: cada entrada ganha uma de sinal contrário, na mesma tupla e no mesmo balde — salvo o que alcança entrada de exercício com a janela tardia vencida, levada ou não, ou entrada relançada pela correção de taxa, que segue a RN-O43 —, com reversalOfEntryId. O positivo sai; o negativo de liquidação vira positivo e restitui o que o ato havia liquidado. Procurar só quem aponta para a entrada estornada não basta: E3 aponta para E1, não para E2, e cancelar o pedido deixaria a requisição com 400 comprometidos em vez de 1.000 — o saldo pareceria maior do que é.

entryReason é DocumentCancelled, Return ou ReceiptReversal no estorno das entradas positivas do grupo — o fato que aconteceu no mundo — e Reverse no estorno dos negativos, que restituem por consequência. Estorno parcial é proporcional: desfazer a fração f do ato (quantidade cancelada ÷ quantidade do ato; em serviço, valor ÷ valor) estorna f de cada entrada do grupo, arredondado à menor unidade da moeda (minorUnits) por HALF_UP e limitado ao aberto — o estorno que zera o ato leva exatamente o que sobrou, sem centavo órfão (RN-O43).

Cancelar pedido: a requisição volta, ou vai junto

Cancelar pedido tem uma opção explícita, “cancelar também a requisição”. Sem ela, o grupo do pedido é estornado e a requisição volta a ficar disponível para outro pedido, com o comprometido restituído. Com ela, nada é restituído: os negativos do grupo não são estornados, e as linhas de requisição atendidas pelo pedido são canceladas no mesmo ato, estornando o saldo aberto delas. Nos dois casos o empenho do pedido sai.

A restituição é consumo que volta, e passa pela avaliação como qualquer delta positivo (RN-O46). Pedido para maio sobre requisição de março: cancelar sem a opção põe R$ 600 de volta em março, e março com Block e sem folga recusa o cancelamento com BUDGET_EXCEEDED_UNPROCESSABLE. A mensagem oferece a opção, que não restitui nada, só tem deltas negativos e por isso passa sempre (RN-O44).

Requisição já encerrada. Requisição de 1.000, pedido de 660 que liquidou 600, requisição encerrada com resíduo (Commitment −400, ResidueRelease). Cancelar o pedido sem a opção grava só Obligation −660: o Commitment −600 não é estornado, porque a requisição não tem mais intenção viva. Saldo final: tudo zero (RN-O43). Vale igual quando o encerramento não grava nada. Requisição de 1.000 atendida por dois pedidos — PO1 de 660 que liquidou 600 e PO2 de 440 que liquidou 400 — tem aberto zero e é encerrada sem lançamento; cancelar PO1 sem a opção grava só Obligation −660, e o comprometido fica em zero com PO2 em 440 empenhados. O que decide é o estado da linha de requisição, lido do módulo dono sob a trava, não a existência de um ResidueRelease. Se o cancelamento e o encerramento chegam juntos, os dois travam as entradas da origem antes de ler — o encerramento trava mesmo sem aberto a liberar (RN-O47) — e o segundo vê o que o primeiro gravou: encerrada antes, o cancelamento não restitui; cancelado antes, o encerramento libera os 600 que o cancelamento restituiu.

Pedido que consolida duas requisições

Requisição A: 50 un × R$ 10 em /TI/INFRA/ (EA · Commitment +500). Requisição B: 30 un × R$ 10 em /TI/DEV/ (EB · Commitment +300), mesma conta, mesmo mês. Um pedido de 80 un × R$ 11 atende as duas, com as fatias herdadas na proporção 50/80 e 30/80 — o grupo tem quatro pernas:

O saldo de /TI/ vai de 800 comprometidos a 880 empenhados: o delta líquido é +80, a diferença de preço. Cancelar 20 das 80 un (f = 1/4) estorna Obligation −137,50 e −82,50 e restitui Commitment +125 a A e +75 a B — cada requisição recupera um quarto do que o pedido liquidou dela. As pernas 3 e 4 só não colidem na chave de idempotência por causa do alvo; as pernas 1 e 2 levam o par — pairedEntryId = EA e EB, o alvo do negativo de cada par —, e com as duas requisições na mesma fatia é só ele que as separa (RN-O34).

Devolução e recebimento acima do pedido

Os dois primeiros atos partem do recebimento de 55 un do exemplo — grupo Actual +605 e Obligation −605 com alvo E2; aberto de E2 = 55. Os dois últimos partem do recebimento de mais 8 un, cada um no lugar do outro.

A devolução estorna a fração do grupo do recebimento: o realizado sai e o empenho volta ao pedido, que fica com 15 un em aberto — o fornecedor repõe, ou o pedido é encerrado com resíduo. O recebimento acima grava um Actual por par — R$ 55 com par em E2, que liquida só o que o pedido tinha aberto — e um sem par, os R$ 33 além disso, consumo real que nunca é recusado (RN-O33, RN-O48). A devolução desfaz primeiro o excedente: 3 das 8 un saem só do Actual sem par, e o pedido, que continua todo recebido, não recupera empenho; só o que passa do excedente restitui, na proporção da perna com par — 5 das 8 un devolvem 2 un, R$ 22, ao pedido (RN-O45). O excedente é achado pelo vínculo que todo Actual de recebimento ou aceite grava — sourceLineId e allocationId da linha de pedido e da fatia recebidas —, entre os Actual sem pairedEntryId; a variação da nota (InvoicePriceVariance, ExchangeVariance) também não tem par e fica fora da busca. Com o pedido já encerrado, a devolução tira o realizado e não restitui: 5 das 8 un gravam Actual −33 e Actual −22, e nada volta ao empenho. Aceitar ou não a quantidade a mais é regra do recebimento; o razão só registra o que entrou (RN-O45).

Reabrir requisição com pedido vivo

Editar uma requisição aprovada grava só a diferença da parte ainda não pedida. Se a edição é ajuste para o motor — valor que não subiu, nenhum critério mudou, cadeia igual —, a diferença grava na hora, sem reabrir (Fluxo de Aprovação, RN-AP-71); se reabre, a reabertura não grava nada — o comprometido aberto continua preso enquanto ela está em edição — e a diferença grava na reaprovação, que é o caso da tabela abaixo. A parte já pedida conserva a data e o rateio do ato que a pediu, e a edição não reduz a quantidade abaixo do que já foi pedido (RN-O45). Exemplo: requisição de 100 un × R$ 10 para março, pedido vivo de 60 un; a pessoa reabre, muda para 80 un e para abril, e reaprova — o aberto passa de 40 para 20 un.

Na reaprovação só abril é avaliado: março tem delta −400 e nunca recusa (RN-O46). Na última linha as 60 un voltam a março, a data do ato que as pediu; para levá-las a abril, a requisição é editada de novo e grava o próprio DateChange, avaliado como qualquer delta positivo.

O resíduo tem dono, idade e aviso

O resíduo só sai por ação humana, e a ação humana precisa de ferramenta: sem consulta, envelhecimento, aviso e critério de encerramento, resíduo de intenção morta come o disponível ao longo do ano — o problema que o produto existe para resolver, com o sinal invertido. Sem entidade nova, quatro peças fecham isso:

• Consulta. GET /budget-entries/residues devolve, por documento de origem e por fatia, o saldo aberto de Commitment e Obligation com a idade em dias desde o último movimento da cadeia, filtrável por nó, período e faixa de idade. É uma leitura sobre o razão e a projeção — nenhuma tabela nova.
• Dono nomeado. O responsável pelo resíduo é o dono do nó de centro de custo da fatia, resolvido por effectiveOwners com rollup. Não se inventa papel: é quem já responde pelo dinheiro daquele ramo.
• Aviso periódico. Uma vez por semana, uma rotina de sistema lê a consulta acima e avisa o dono de cada nó que tem resíduo mais velho que residueAlertAfterDays — campo da BudgetPolicy, resolvido para o nó da fatia como os demais, com padrão de fábrica de 60 dias. Um aviso por dono e por nó, com a lista dos documentos, a idade de cada um e o link para a consulta. Sem valor: o saldo preso fica do outro lado do link (RN-O22). O slug é nexio.budget-residue.aged, na Notificação.
• Critério de encerramento por completude. Gancho declarado, não regra da v1: quando Requisition e PurchaseOrder forem especificados, o documento cuja quantidade recebida iguala a pedida pode ser proposto para encerramento automático — a decisão continua sendo do dono, e a proposta só existe para que ele não precise procurar. Enquanto os dois documentos não existem, não há o que automatizar e a consulta acima já é a ferramenta que faltava.

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.

Vale igual no three-way match, e é por isso que Adjustment não entra aqui. Nota R$ 500 acima do recebido, com a diferença aceita por uma pessoa, grava Actual adicional de R$ 500, sem alvo, com entryReason = InvoicePriceVariance e o reasonCode do uso PriceVarianceAccept; nota abaixo grava o negativo. Adjustment aumenta a verba: uma nota mais cara criaria orçamento sem BudgetChangeRequest, pelo caminho de maior volume do sistema (RN-O28, RN-O51).

Idempotência é chave natural, não tentativa

Todo movimento carrega idempotencyKey único: o hash de (sourceType, sourceId, sourceLineId, allocationId, documentVersion, stage, entryReason, alvo, perna). Reprocessar o mesmo ato — reentrega de fila, duplo clique, retry de integração — produz as mesmas chaves e é descartado sem efeito. Não existe "verificar se já lancei"; existe deixar o índice único recusar.

Cada peça da chave existe para não descartar o que precisa entrar. documentVersion separa dois atos do mesmo documento — cancelar 20 un hoje e mais 20 amanhã são versões diferentes do pedido. entryReason separa fatos que compartilham fatia, estágio e alvo — na reaprovação de requisição reaberta, QuantityChange −200 e DateChange −200 em março, com o mesmo alvo, só não colidem por ele; a operation, mais grossa, os confundiria. allocationId é a identidade estável da fatia, não o order, que é reusado quando o rateio vai de 70/30 para 50/50. O alvo separa as duas liquidações do pedido que consolida duas requisições. O positivo não tem alvo, e no lugar dele entra a entrada do par (pairedEntryId; none quando não há par): sem ela colidiriam os dois positivos do pedido que liquida duas entradas da mesma fatia, os dois positivos da virada de uma linha com duas entradas abertas, os dois relançamentos da RateCorrection e os dois positivos do DateChange sobre duas entradas abertas da mesma fatia e, no recebimento acima do pedido, o Actual com par e o excedente. Por isso todo positivo que nasce em par com um negativo aponta em pairedEntryId o alvo do negativo do par. E o alvo entra na chave com o nome da coluna, não só com o id: o relançamento da RateCorrection aponta por pairedEntryId a mesma entrada que o estorno dele aponta por reversalOfEntryId, no mesmo estágio, motivo e balde. A perna separa as duas metades de um par: o negativo no balde velho e o positivo no novo do DateChange, as duas linhas do Transfer, as duas pontas da virada.

O grupo entra inteiro ou não entra. A repetição é detectada primeiro pelo postingGroupId, que é determinístico por ato, antes de recalcular alvos — refazer o cálculo pela ordem das entradas abertas daria outros alvos se o estado mudou entre as tentativas. Se o grupo já existe, o ato já foi gravado: nada é inserido, nenhum saldo é tocado, e a resposta é a do registro existente. Chave presente para parte do grupo e ausente para outra é falha de integridade — erro 500 e rollback —, porque o grupo sempre é gravado numa transação só. BudgetBalance só é atualizada pelas entradas que de fato entraram (RN-O34).

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 o balde aplicado — o mês da data de necessidade, salvo as regras de virada (RN-O48). Não pode haver dois — a sobreposição de períodos entre exercícios Approved ou Closed da mesma empresa é recusada como exclusão de faixas, excluída só a versão que o exercício substitui (RN-O54). EXCLUDE com btree_gist é um exemplo de implementação, com verificação sob trava na aplicação onde o banco não oferecer equivalente — a mesma mecânica de ApprovalPolicy e CostCenterAssignment. Se não houver exercício, o resultado é NotControlled e acabou.

2 · A política efetiva

requiresBudget é resolvido para o nó da fatia, subindo o path. Se resolver como falso, o resultado é NotControlled — o movimento ainda é gravado, e nada é consultado nem bloqueado. Os demais campos — overBudgetPolicy, tolerancePercent, toleranceAmount e carryForwardMode — são resolvidos para o nó de cada linha candidata, campo a campo: overBudgetPolicy pode vir do nó, a tolerância do avô e carryForwardMode do padrão. Linha de centro de custo nulo usa a política de costCenterId nulo (a da empresa, se houver; senão a do tenant).

A política é da linha; a decisão é do pior sinal. Cada candidata calcula o próprio sinal com a própria verba, a própria tolerância e a própria política, e a fatia fica com o pior desfecho entre elas: Exceeded sob Block > Exceeded sob RequireApproval > Exceeded sob Warn > Warning > Ok. Verba de R$ 300 mil em /TI/INFRA/ com Warn, dentro de R$ 1 milhão em /TI/ com Block, não abre uma porta de R$ 1,3 milhão: estourar TI recusa o documento mesmo que INFRA ainda tenha folga (RN-O31).

3 · As linhas candidatas

São candidatas as linhas do exercício cujo período contém o balde e em que costCenterId é nulo ou é ancestral-ou-igual do nó da fatia, e glAccountId é nulo ou é ancestral-ou-igual da conta da fatia — as duas comparações pelo path da árvore vigente (RN-O50). Não existe linha vencedora: toda candidata é avaliada, e o conjunto é determinístico porque depende só das duas árvores e das linhas do exercício.

Nenhuma candidata recebe o movimento. O razão grava uma entrada só, com a tupla concreta; cada candidata enxerga esse consumo porque a tupla cai sob ela nas duas dimensões (RN-O31). Gravar N entradas, uma por linha, daria o mesmo saldo e multiplicaria por N o custo do estorno (RN-O43); gravar a entrada numa linha escolhida faria a linha nova, a versão nova do exercício e o orçamento aprovado com o ano já começado não enxergarem o que foi gasto antes deles (RN-O32).

4 · Nenhuma linha cobre

Escopo controlado e nenhuma candidata: sinal Uncovered. Commitment e Obligation são recusados com BUDGET_UNCOVERED_ALLOCATION_UNPROCESSABLE, nomeando a combinação; Actual nunca é recusado — grava, marca o documento como fora do orçamento e notifica os donos do nó (RN-O33). O positivo da virada da rotina e o da virada sob demanda disparada por liquidação também não são recusados: eles gravam marcados e notificam, como o Actual (RN-O13, RN-O46, RN-O48). 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), e nela nulo colide com nulo: duas linhas coringa com as mesmas dimensões nulas no mesmo período são a mesma linha, e a segunda é recusada com BUDGET_LINE_ALREADY_EXISTS. É requisito, não recurso de banco: índice único simples em banco que trata nulos como distintos não o cumpre, e a implementação escolhida precisa passar no teste das duas coringas idênticas (RN-O54).

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 e redução não podem deixar a origem negativa

Na decisão final de Transfer e de Reduction, o contrato de desfecho trava a linha de origem — qualquer que seja a política dela — e confere naquele instante, não no pedido, que o disponível da origem cobre o valor: orçado mais ajustes menos o consumo lido pela tupla, no período da linha; no Cumulative, o menor acumulado desse período ao fim do exercício. Verba pode ter sido consumida durante a aprovação. Se não cobrir, Refused(BUDGET_CHANGE_INSUFFICIENT_UNPROCESSABLE): nada é gravado, a tarefa continua ativa e o aprovador vê o número atual (RN-O49). Linha de março com R$ 10.000 e R$ 9.200 consumidos: redução de R$ 1.000 é recusada (disponível 800); a de R$ 800 passa e deixa disponível zero (RN-O19).

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: só os valores das linhas mudam, e o razão — que guarda a tupla, não a linha — passa a ser lido contra as linhas novas sem movimento nenhum. Confundir os dois é como confundir commit com force push.

O contrato dos sinais, e o que cada um obriga

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 POST /evaluate:budget-state publica, e cada um obriga a exatamente uma coisa:

O que Uncovered significa, escrito de uma vez: o escopo é controlado (requiresBudget verdadeiro) e nenhuma linha do exercício cobre a combinação — não é "estourou", é "a dimensão não existe no plano". Por isso ele não passa por tolerância nem por política de estouro: não há verba contra a qual medir. A saída é cadastrar a linha coringa daquele centro de custo, e é isso que a mensagem diz. Ver RN-O39.

available depende do modo de leitura

Com PeriodOnly, é budgeted(março) − consumed(março). Com Cumulative (acumulado), é Σ budgeted(periodStart..março) − Σ consumed(periodStart..março) — de janeiro a março num exercício que começa em janeiro, de abril a março num que começa em abril. 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".

No Cumulative, o lançamento num balde é avaliado contra todos os acumulados que ele altera — o do próprio balde e os dos baldes seguintes do exercício —, e decide o menor disponível. Janeiro com R$ 100 orçados e nada consumido, fevereiro com R$ 100 orçados e R$ 190 consumidos: lançar R$ 90 em janeiro cabe no acumulado de janeiro (disponível 100) e estoura o de fevereiro (200 − 190 = 10). Sob Block e sem folga é recusado, e signalFrom aponta a linha de fevereiro (RN-O46).

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 movimento daquela fatia grava o nó folha e a conta folha, e a linha de "Operações" lê o consumo de toda tupla que cai sob ela — 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, lendo o consumo de vários nós.

Linha no pai e linha no filho enxergam o mesmo gasto, cada uma contra a sua verba. R$ 1 milhão em /TI/ e R$ 300 mil em /TI/INFRA/: R$ 250 mil gastos em INFRA são consumo das duas linhas, e o disponível de TI desconta esses R$ 250 mil mais o resto de TI. As verbas se contêm em vez de somar poder de gasto — como Oracle Budgetary Control e SAP FM, que aplicam o controle em vários níveis ao mesmo tempo (RN-O31). A leitura não pergunta se o escopo que gravou era controlado: fatia de nó com requiresBudget falso não é avaliada, mas o gasto dela conta em toda linha que a cobre.

Documento em aprovação aparece, e não conta

Documento em aprovação não grava movimento, então três requisições submetidas contra a mesma verba veriam Ok cada uma. A consulta devolve, por linha, pendingApproval — a soma das fatias de documentos submetidos e ainda não concluídos que caem sob a linha, excluído o próprio documento — dentro de amounts, e o aviso pendingOverrun fora dele: verdadeiro quando consumo + em aprovação + delta do ato passa do orçado + folga. É informação, nunca critério: não muda o sinal, não trava, não recusa, e o motor não o lê. Quem soma é o documento: cada módulo de documento com aprovação publica, no seu .Contracts, a leitura das fatias em aprovação por tupla e balde, e o Orçamento só agrega por linha; enquanto Requisição e Pedido não existem, os dois campos voltam nulos (RN-O56).

Com números. Verba de março R$ 50.000, consumo 40.000, R$ 7.000 em requisições em aprovação. Requisição nova de R$ 5.000: sinal Ok (5.000 ≤ 10.000), pendingApproval = 7.000, pendingOverrun = verdadeiro (40.000 + 7.000 + 5.000 = 52.000 > 50.000). A tela diz: cabe hoje; com o que está em aprovação, não cabe.

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 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 entryReason = DateChange, negativo no balde velho e positivo no novo, e se o novo balde não couber, vale a política das linhas dele. Nunca um UPDATE em competencePeriodKey.

Com números. Requisição de R$ 1.000 para março (E1), data mudada para abril: um grupo com Commitment −1.000 em março, alvo E1, e Commitment +1.000 em abril, os dois DateChange. Março tem delta −1.000 e nunca recusa. Linha de abril com R$ 5.000 orçados, R$ 4.300 consumidos, Block e tolerância de 5% limitada a R$ 200: disponível 700 + folga 200 = 900 < 1.000 → a mudança de data é recusada com BUDGET_EXCEEDED_UNPROCESSABLE (wouldExceedBy = 100) e a requisição continua em março, intacta (RN-O46).

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. No periodStart do exercício seguinte ela reinicia, sempre, qualquer que seja a política — 1º de abril, num exercício de abril a março. 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

Passada a janela de lançamento tardio, cada saldo aberto de Commitment e Obligation do exercício gera, num grupo por entrada, um negativo no próprio estágio, no balde dela e com ela como alvo, e um positivo no mesmo estágio no primeiro mês depois de periodEnd — os dois com entryReason = YearEndRollover, a origem do documento, a tupla e a taxa de câmbio preservadas — Rollover identifica só a chave de idempotência e o grupo da virada (RN-O34). A verba não vai junto. São movimentos de sistema, isentos de Block e de Uncovered: o compromisso já foi aprovado e o documento não volta à fila, e o positivo da virada da rotina grava marcado como fora do orçamento e notifica os donos do nó, como o Actual (RN-O33), mesmo que nenhuma linha cubra a tupla no balde de destino — o exercício novo pode estar aprovado e mesmo assim não ter linha que cubra aquela combinação, e a rotina não pode ficar travada num balde que só a linha coringa destrava (RN-O13, RN-O39). A isenção é da rotina, e a virada sob demanda que um ato provoca depois dela segue o gatilho: disparada por liquidação, entra na parcela isenta e é isenta dos dois sinais, como a da rotina; disparada por restituição, é avaliada com o ato e continua podendo ser recusada com BUDGET_UNCOVERED_ALLOCATION_UNPROCESSABLE (RN-O46, RN-O48).

É o que faz a Decisão 8 ser verdade. Gravado nos próprios estágios, o compromisso levado consome desde o primeiro dia do exercício novo, sem enum novo e sem campo novo na consulta de saldo: o aperto de dezembro aparece como estouro em janeiro (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 força redecisão no ano novo. O orçamento não conhece o documento, então não o devolve nem o cancela: a virada chama, por documento de origem com saldo aberto, o contrato de virada que o módulo dono registra para aquele sourceType no seu .Contracts. O documento encerra ou devolve a linha dele e grava o próprio estorno de grupo (RN-O43), na mesma transação; o que o contrato devolver como Failed fica aberto e visível no relatório da virada, que não arquiva o exercício enquanto houver pendência. Publicar BudgetPolicy com CancelOpen é recusado com BUDGET_POLICY_YEAR_END_UNSUPPORTED_UNPROCESSABLE enquanto algum tipo de documento que grava no razão não tiver o contrato (RN-O57). 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.

A janela tardia e a virada, com números

A janela existe para que o fato de dezembro que chega em janeiro caia em 2026 — sem ela, o recebimento de uma entrega orçada e empenhada em 2026 consumiria verba de 2027 e estouraria o ano novo por um fato do ano velho. E a virada espera a janela acabar para que as duas coisas não se anulem: levar o empenho para 2027 enquanto 2026 ainda aceita o recebimento dele deixaria o mesmo dinheiro nos dois anos. Exercício 2026 de janeiro a dezembro, lateActualsUntil = 01/03/2027, CarryCommitmentOnly, requisição de 100 un × R$ 10 com necessidade em 20/12/2026 (E1 · Commitment +1.000, dezembro de 2026):

2026 fecha com exatamente o que foi realizado nele, R$ 605, e nenhum ato foi recusado por exercício fechado. 2027 carrega o que ainda estava vivo e enxerga o aperto desde janeiro. A entrega de 30/12/2026 não parte a cadeia: o realizado fica em 2027, junto do empenho que liquidou, e a data real continua no movimento para relatório. O pedido de 15/03 herda a necessidade de 20/12/2026 e mesmo assim não cai num exercício arquivado: o par liquida a entrada recriada pela virada e vai ao balde dela (RN-O48). Nada disso depende de alguém fechar o exercício: 2026 passa a Closed em 01/01/2027 e a virada roda em 02/03/2027 sozinhos. E o que anda para trás depois da virada também fica em 2027: a devolução de 20/03 e o cancelamento da variante alcançam entradas levadas e gravam as duas pernas no balde das recriadas — 2026, arquivado, continua em 605, e o pedido volta a ter 10 un, ou nenhuma, por receber. Na variante 2 a requisição não tinha aberto a levar, e a restituição vai a 2027 assim mesmo: gravada só em dezembro de 2026, onde nada é controlado, o cancelamento liberaria os R$ 440 do empenho em 2027 sem trazer os R$ 400 da requisição, que o pedido seguinte traria depois (RN-O43). E o que anda para trás sem par não devolve verba nenhuma ao ano novo: na variante 3 a devolução do excedente baixa os R$ 33 do realizado de 2026, onde ele foi consumido, e o disponível de 2027 fica igual — com o negativo em janeiro de 2027, 2027 ganharia R$ 33 de folga que ninguém orçou. O excedente dessa variante só existe acima do aberto da entrada: 63 un × R$ 11 = R$ 693 contra os R$ 660 de E2 deixam R$ 33 sem par, enquanto 58 un × R$ 11 = R$ 638 ainda caberiam nos R$ 660 e liquidariam sem sobra nenhuma (RN-O45, RN-O51). E, com E2 zerada, a virada de 02/03 não a leva e não há mais nada a receber do pedido de 60 un — o que resta em 2027 é o empenho das 40 un de 15/03 e o realizado de 20/01. Em nenhum dos dois casos, com par ou sem par, o disponível do exercício novo muda. Nada disso depende do estado Archived: o que aciona as regras é a janela tardia ter vencido, e entre o fim dela e o arquivamento a rotina já pulou a entrada de aberto zero e já levou os empenhos (RN-O43, RN-O48).

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 necessidade em dezembro, o positivo não tem entrada a liquidar e vai ao primeiro mês do exercício seguinte, com aviso na tela e no evento — é a linha de 12/01 da tabela acima. A cadeia não é reavaliada por isso; se as linhas de janeiro recusarem sob a trava, vale o desfecho da decisão final (RN-O49).

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

Company.functionalCurrency, da spec de Empresa, define em que moeda a pessoa jurídica orça e presta contas. Na v1 é sempre BRL: o campo existe e fica imutável depois do primeiro Budget da empresa. Documentos, preços, limites de alçada e cotações continuam em qualquer ISO 4217 — o que a v1 fixa é só a moeda em que a pessoa jurídica orça, que é a do CNPJ e do SPED. Com funcional em real, toda conversão é moeda estrangeira contra real, que é o que o boletim do Banco Central publica; 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 na submissão do documento — e de novo só em rodada nova —, e o razão herda

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. O Commitment nasce dias depois da submissão, na conclusão da cadeia, e converter de novo ali daria outro número para o mesmo dinheiro. Vale 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 vale só para movimento sem documento de origem — Manual e Import (RN-O41). Requisição, pedido e nota convertem cada um na sua submissão; recebimento e aceite não convertem — gravam pela taxa do pedido. A variação entre a requisição e o pedido aparece no próprio grupo do pedido, como a diferença de preço; a variação entre o pedido e a nota entra pela nota, como ExchangeVariance (RN-O51, 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.

O realizado é o custo incorrido; a nota traz só a diferença, com nome próprio

O Actual é gravado no recebimento da mercadoria ou no aceite do serviço, pela taxa que o pedido congelou; a nota não liquida empenho nem regrava o realizado. O que a nota traz de novo entra como Actual sem alvo, com entryReason próprio: a diferença de preço aceita (InvoicePriceVariance), valorizada pela taxa do pedido, e a variação cambial (ExchangeVariance), que é o resto. Pedido de 100 un × US$ 100, taxa congelada 5,20:

O realizado termina igual ao faturado convertido — R$ 56.040 — e o extrato separa quanto foi preço e quanto foi câmbio. Nota abaixo do recebido, ou dólar em queda, grava os mesmos movimentos com sinal negativo. Serviço segue igual, com o aceite no lugar do recebimento. Nota sem pedido — conta de consumo, serviço contratado sem pedido — é o próprio documento que incorre o custo: grava Actual sem alvo, pela taxa da submissão dela e sem liquidação, no ato que a spec da Nota definir — aprovação no motor ou ato do próprio documento. Faturado e liberado para pagamento são leitura fornecida pela Nota por fatia, fora do razão — não consomem verba, porque o custo já foi incorrido; enquanto a Nota não existir, a consulta os devolve nulos (RN-O51).

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 e o comportamento em fim de semana e feriado são de CurrencySettings, da spec de Moeda e Câmbio. O tipo de taxa do documento vem de processRateTypes, por processo, e quem pede, prepara ou submete não escolhe; defaultRateType vale só para movimento sem documento de origem — o Manual e o Import deste razão. A Moeda é a dona da regra; aqui ela só é citada. 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 de informar taxa no documento 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. Taxa informada aciona a controladoria: o documento recebe no motor o passo complementar da controladoria, porque a taxa decide a alçada; e a taxa informada nunca vira cotação do tenant. E o autor da taxa não decide: o capturedBy de toda taxa do tenant usada na conversão entra em excludedUsers com a razão RateOverrider — com ou sem a flag, e qualquer que seja o papel dele no documento —, e quem registrou o override entra com a mesma razão: o overriddenBy, com taxa informada ou só com o tipo. A regra é do Fluxo de Aprovação e de Moeda e Câmbio, que nomeia os dois campos; aqui ela só é citada.

Corrigir uma taxa não mexe na verba

RateCorrection tem um gatilho só: a cotação do tenant que o documento usou foi substituída — a linha nova aponta supersededById na antiga, e o motivo é o supersedeReasonCode dela, sem código novo. A regra é de Moeda e Câmbio, que é a dona; aqui ela só é citada. Nesse caso o razão se corrige com um grupo que estorna o saldo aberto de cada entrada afetada e relança o mesmo saldo pela taxa certa, no próprio estágio, as duas pernas com entryReason = RateCorrection. Nunca Adjustment, que muda a verba (RN-O28). A parte já liquidada não se corrige para trás: ela virou realizado, e a diferença aparece na nota como ExchangeVariance. A correção é isenta de Block, passa marcada e notifica os donos do nó: recusá-la manteria o número errado — no sentido perigoso, quando a taxa certa é maior.

Taxa informada errada não se corrige no razão. O exchangeRateOverride é do documento, e documento se corrige por versão nova: outro exchangeRateOverride, com a permissão de informar taxa no documento, que deriva de novo exchangeRateOverridden e traz o passo complementar da controladoria, e com os dois autores que Moeda e Câmbio nomeia em excludedUsers como RateOverrider: o capturedBy, autor da linha de taxa efetivamente usada, e o overriddenBy, quem registrou o override — que é o único dos dois preenchido quando a taxa vem informada. E informar ou trocar a taxa depois de aprovado abre rodada nova, para cima ou para baixo: qualquer mudança de taxa recomeça a rodada do zero, com as decisões anteriores Obsolete — a flag exchangeRateOverridden, que informar ou trocar a taxa deriva de novo, está no retrato dos atributos de critério (RN-AP-21), e a regra é do Fluxo de Aprovação (RN-AP-70), que é a dona; aqui ela só é citada. Sem isso, quem tem a permissão de informar taxa no documento baixava a taxa depois de aprovado e liberava R$ 1.080 de empenho (US$ 6.000 de 5,20 para 5,02) sem rota, sem autor declarado, sem segunda pessoa e sem redecisão — a regra que só olhava o valor subir deixava passar exatamente a taxa que desce, que é o sentido em que a verba se libera —, ou a subia e punha o valor acima da alçada sem rodada nova.

Com números. Empenho de US$ 10.000 convertido pela cotação de 5,20, substituída depois por 5,02, com 40 un já recebidas (R$ 20.800 realizados). O grupo grava Obligation −31.200, alvo o empenho, e Obligation +30.120 (US$ 6.000 × 5,02): empenhado aberto de 31.200 para 30.120, realizado intacto. O recebimento das 60 un restantes liquida a entrada nova, a 5,02 (RN-O53).

Devolução depois da correção. Devolver 10 das 40 un grava Actual −5.200 (Return), pela taxa com que o realizado foi gravado, e Obligation +5.020 (Reverse, pairedEntryId = a entrada nova), US$ 1.000 pela taxa dela: o empenho aberto fica em 35.140, as 70 un a 5,02. Restituir à entrada original, a 5,20, deixaria 35.320, e a entrega seguinte a liquidaria pela taxa errada. No sentido inverso — gravada a 5,02, corrigida para 5,20 — a restituição é Obligation +5.200 contra Actual −5.020: os R$ 180 de diferença são correção de taxa, isentos de Block — parcela isenta R$ 180, parcela avaliada zero (RN-O46) —, e sem a regra o empenho ficaria R$ 180 abaixo (RN-O43).

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.

Block não recusa mercadoria na doca

Bloquear é dizer "não compre". Aplicado a Actual, viraria "não registre o que já chegou": a mercadoria está na doca, o caminhão foi embora, e recusar o recebimento não devolve o dinheiro — só apaga o fato do razão, que é a única coisa que o produto não pode deixar acontecer. O caso mais frequente é o da própria spec: o pedido empenhou US$ 10.000 a 5,20 e a nota chega a 5,60, e os R$ 4.000 de variação "consumiram caixa" por definição. Por isso Block avalia Commitment e Obligation e deixa passar Actual, marcando o documento como fora do orçamento e notificando os donos do nó, exatamente como Warn (RN-O33).

E quando o empenho estoura na decisão final

Entre a submissão e a conclusão da cadeia passam dias, e outro documento pode ter comido a verba no intervalo. O Commitment é gravado pelo contrato de desfecho do processo, na transação da decisão e sob a trava (RN-O47), e o desfecho tem três resultados (RN-O49):

• Applied — decisão, transição e Commitment gravados na mesma transação.
• Refused(BUDGET_EXCEEDED_UNPROCESSABLE) — sob a trava, uma linha candidata está em Exceeded sob Block, ou sob RequireApproval com sinal pior que o da rodada em que a cadeia foi montada. Nada é gravado pela transação da decisão — nem a decisão, nem a transição, nem o movimento — e a tarefa continua ativa. O motor registra a tentativa em transação própria; o aprovador vê a linha, o disponível e quanto faltou, e escolhe devolver com motivo (a rodada nova nasce com o sinal novo) ou aguardar remanejamento e decidir de novo. O requisitante e os donos do nó da linha que recusou são avisados. O mesmo vale para Refused(BUDGET_UNCOVERED_ALLOCATION_UNPROCESSABLE) — fatia sem linha — e para Refused(BUDGET_CHANGE_INSUFFICIENT_UNPROCESSABLE), na decisão final do BUDGET_CHANGE que deixaria a origem negativa.
• Failed — falha técnica: rollback total e nada gravado; repetir é seguro pelo expectedVersion e pela chave de idempotência.

O efeito que precisa ser atômico com o ato acontece na mesma transação — pelo próprio caso de uso, por chamada síncrona declarada entre contextos (.Contracts) ou pelo contrato de desfecho do motor; o evento de domínio é publicado depois do commit e serve para notificar, medir e integrar — nunca para produzir efeito de que o ato dependa. Por isso o Commitment é gravado pelo contrato de desfecho, e não por quem escuta o evento de aprovação.

Com números. /TI/ com Block, sem folga, R$ 50.000 orçados em março. A requisição X, de R$ 8.000, foi submetida com R$ 12.000 disponíveis e subiu pela cadeia; enquanto aguardava a última assinatura, outra requisição consumiu R$ 6.000. Na decisão final o disponível é 6.000 < 8.000: Refused, a assinatura não é gravada e a tarefa segue com o diretor. Aprovado um BudgetChangeRequest de R$ 2.000 em /TI/, a nova decisão encontra 8.000 disponíveis e dá Applied.

Materialidade é roteamento; o orçamento vê a decomposição integral

allocationMaterialityPercent afeta apenas a montagem da cadeia de aprovação. O orçamento sempre vê a decomposição integral do rateio, e Block numa fatia absorvida recusa a submissão do mesmo jeito. Um pedido de R$ 400 mil com 3% em /MARKETING/ não gera aprovador de Marketing — e consome a verba de Marketing pelos R$ 12 mil, com a política de Marketing valendo inteira.

Por quê: controle de verba não é roteamento de alçada. A alternativa — deixar passar porque o motor ignorou a fatia — cria a marca que dispara no funcionamento normal, e controladoria que vê marca todo dia aprende a ignorá-la. Esta é a mesma frase que o Fluxo de Aprovação escreve do lado dele, de propósito: "a mesma fatia que a alçada avalia é a que o orçamento consome" continua verdadeira para o consumo; o que a materialidade dispensa é o aprovador daquela fatia, nunca o lançamento (RN-O38, e RN-CC-24 do lado do rateio).

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. Controla desde o primeiro dia do período: o que foi gravado antes da carga é lido contra as linhas importadas no instante em que o exercício existe (RN-O32).

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 BUDGET no motor. Devolver reabre a edição sem matar a instância, como em qualquer outro documento.

Aprovar em março o orçamento que começou em janeiro — o caso normal, não a exceção. Nenhum movimento novo é gravado na aprovação. Os movimentos de janeiro e fevereiro foram gravados com a tupla concreta e sem linha; no instante em que o exercício vai a Approved, as linhas dele passam a ler esse consumo, e a tela de março mostra a verba já descontada do que foi gasto — em vez da verba intacta, que é o "a verba acabou em setembro" que esta spec existe para eliminar. Linha que janeiro e fevereiro já estouraram nasce Exceeded: nada é desfeito, e o próximo compromisso sob Block nela é recusado (RN-O32).

É 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 BUDGET, e ao ser aprovada arquiva a anterior. O razão não é tocado: a versão nova só troca os valores das linhas. Os movimentos guardam a tupla e não a linha, e no instante da aprovação passam a ser lidos contra as linhas novas — o consumido até ali continua descontado, o disponível não pula, e refazer o plano nunca apaga o que já foi gasto. Adjustment aponta para a linha da versão em que foi aprovado; a cópia em Draft parte de amount + Σ Adjustment de cada linha (RN-O32).

A trava é a entrada e a linha de orçamento, e é curta

A transação de gravação segue sempre a mesma ordem: (1) derivar o postingGroupId do ato e parar se o grupo já existe (RN-O34); (2) travar, ordenadas por id, as entradas de que o ato depende — todas as entradas positivas de cada origem que ele vai liquidar, (sourceType, sourceId, sourceLineId, allocationId, stage), abertas ou não — a recriada pela virada tem a mesma origem da levada —, porque só sob a trava se sabe o aberto (RN-O42); no estorno, as positivas da origem de cada entrada estornada e das que ela aponta como alvo ou par (RN-O43); na devolução, também os Actual sem par da mesma linha de pedido e fatia, candidatos a excedente (RN-O45); (3) conferir de novo o postingGroupId, agora sob a trava; (4) ler o aberto das entradas travadas, escolher a mais antiga e limitar cada negativo — e, se a escolhida é de exercício com a janela tardia vencida que a rotina ainda não levou, montar antes a virada sob demanda dela, no grupo do ato e com os movimentos dela na parcela isenta, e liquidar a recriada (RN-O42, RN-O46, RN-O48); no estorno, ler do módulo dono o estado da linha de origem e achar a entrada mais recente da cadeia do alvo levado ou relançado — ou, se o alvo é de exercício com a janela tardia vencida e não foi levado, montar a virada sob demanda do valor restituído, no grupo do ato e na parcela avaliada (RN-O43, RN-O46); (5) montar as pernas, somadas pelas colunas da chave — dois lotes da mesma linha de pedido, fatia e par são uma perna só (RN-O51) —, e resolver as linhas candidatas; (6) travar por id as que têm Block ou RequireApproval (RN-O47); (7) ler as somas das tuplas sob cada uma e avaliar pelo delta líquido (RN-O46); (8) inserir os movimentos, atualizar BudgetBalance com as entradas que entraram e confirmar. Nada que decide é lido antes de a trava que o protege estar obtida. Toda transação trava entradas antes de linhas e, dentro de cada classe, por id — é o que evita deadlock entre dois atos que tocam as mesmas entradas ou as mesmas verbas em ordem inversa.

As duas travas são requisito, não recurso de banco. A da linha é exclusiva sobre a BudgetLine e dura até o fim da transação — SELECT … FOR UPDATE é um exemplo, e qualquer equivalente serve. A da entrada é lógica, por id da entrada: BudgetEntry não aceita UPDATE (é grant), e a trava de linha de alguns bancos exige esse privilégio — no PostgreSQL, por exemplo. O requisito é exclusão mútua por id, com escopo de transação e liberada no commit ou no rollback; trava consultiva de transação com chave derivada do id (pg_advisory_xact_lock no PostgreSQL, sp_getapplock no SQL Server) ou uma linha de trava por entrada em tabela própria servem igual. Colisão da chave derivada só serializa a mais, nunca a menos.

Sem /TI/ no conjunto de trava, os dois leriam 10.000 disponíveis e /TI/ terminaria com 56.000 consumidos — R$ 6.000 acima de uma verba sob Block.

Índices que precisam existir desde o primeiro dia

Em BudgetEntry: (tenantId, postingGroupId) para o estorno do grupo; (tenantId, liquidatesEntryId) e (tenantId, reversalOfEntryId) para o saldo aberto; (tenantId, sourceType, sourceId) para o extrato por documento; (tenantId, budgetLineId) para o Adjustment; único em (tenantId, idempotencyKey). Em BudgetBalance: único na tupla (tenantId, companyId, competencePeriodKey, stage, costCenterId, glAccountId), que atende a leitura por empresa e mês antes do filtro de prefixo das duas árvores. Em BudgetLine: (budgetId, periodKey), mais a unicidade da chave lógica com nulo colidindo com nulo. Em BudgetPolicy: exclusão de vigência por (tenantId, costCenterId, companyId), nulo colidindo com nulo. Em Budget: exclusão de período por (tenantId, companyId) entre Approved e Closed.

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 qualquer banco relacional e não justifica particionamento no lançamento. O particionamento por empresa e ano de competência fica declarado como gancho para quando o primeiro cliente grande aparecer, e não antes.

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

POST /evaluate:budget-state lê BudgetBalance, as linhas candidatas 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 leitura indexada — as tuplas da empresa no mês, filtradas pelo prefixo das duas árvores, agregadas por linha candidata — — e é por isso que a projeção materializada existe, mesmo o razão sendo a verdade.