Declare Papéis de Fluxo de Caixa no Seu Livro-razão: Uma Linha de Metadados Substitui a Adivinhação

Toda demonstração de fluxo de caixa repousa sobre uma decisão silenciosa tomada uma vez por conta: esta conta faz parte do caixa que você está explicando, ou é uma atividade operacional, de investimento ou de financiamento? Acertar essa decisão e a demonstração diz para onde seu dinheiro realmente foi. Errar e a demonstração é confiantemente enganosa.

Até agora, o relatório de fluxo de caixa do Beancount.io tomava essa decisão por você com heurísticas — o tipo raiz da conta, mais uma suposição baseada no nome sobre quais ativos contam como caixa. Para a maioria dos livros-razão, a suposição estava certa na maioria das vezes, e silenciosamente errada no resto do tempo. Uma conta de corretagem nomeada da maneira errada caía na seção errada. Um fundo do mercado monetário que é caixa em todos os sentidos práticos ficava em Atividades de Investimento porque seu nome não dizia isso.

A partir de hoje, você pode tornar a classificação explícita. Uma linha de metadados padrão do beancount na diretiva open da conta:

2000-01-01 open Assets:US:Brokerage
  cash-flow-role: "investing"
 
2000-01-01 open Assets:US:Marcus:Savings
  cash-flow-role: "cash"

Uma chave, quatro valores — cash, operating, investing, financing — e essa é toda a configuração. Não há página de configurações, nenhum arquivo JSON, nenhum diálogo de opções por relatório. Na próxima vez que o relatório de fluxo de caixa carregar, os fluxos da conta de corretagem aparecem em Atividades de Investimento, a conta poupança se junta ao monte de caixa cuja mudança a demonstração explica, e todas as outras contas continuam funcionando exatamente como antes.

O que cada papel significa​

Uma demonstração de fluxo de caixa classifica cada conta em uma de duas funções, e cash-flow-role responde a ambas com uma única palavra:

• "cash" — a conta pertence ao monte de caixa e equivalentes. Contas de caixa nunca aparecem como itens de linha; a demonstração explica a mudança no saldo combinado delas, e transferências entre duas contas de caixa se cancelam, da maneira que mover dinheiro da conta corrente para a poupança deveria.
• "operating" / "investing" / "financing" — a conta não é caixa, e sua mudança no período aparece como uma linha sob essa seção de atividade.

Por padrão, o relatório trata contas de ativos cujos nomes contêm Cash, Checking, Savings ou Bank como equivalentes de caixa. Declarar um papel substitui isso em ambas as direções. cash-flow-role: "cash" puxa uma conta que a regra de nome não pega — um fundo do mercado monetário, uma carteira de stablecoin. E cash-flow-role: "investing" em Assets:US:Bank:CD faz duas coisas com uma linha: exclui o CD do caixa e o arquiva em investimentos, mesmo que seu nome tivesse correspondido à regra de caixa.

Usamos deliberadamente uma chave em vez de duas. "Esta conta é caixa?" e "a qual seção de atividade ela pertence?" nunca foram perguntas independentes — uma conta é parte do monte de caixa ou pertence a exatamente uma seção de atividade. Duas chaves teriam permitido estados sem sentido, como uma conta de caixa com um papel de atividade. Uma chave torna os estados ilegais irrepresentáveis, e toda a especificação cabe em um tweet.

A classificação que você declara é a classificação que toda visão usa. O gráfico Por Atividade empilha os fluxos operacionais, de investimento e de financiamento de cada mês; mova o papel de uma conta, e seus fluxos se movem para a camada certa do gráfico, a seção certa da demonstração e a linha certa da exportação, tudo de uma vez.

Declarado vence inferido — e o relatório mostra seu trabalho​

A classificação agora resolve em uma ordem estrita: seus metadados primeiro, a heurística embutida em segundo. E o relatório é honesto sobre o que fez. A demonstração termina com um painel "Caixa e equivalentes de caixa neste relatório" listando exatamente quais contas tratou como caixa ao construir os números, e então as reconcilia: caixa no início do período, caixa no final do período e a mudança líquida que as seções de atividade explicam.

O relatório também distingue classificações que você declarou das que inferiu, e a distinção vai para as exportações CSV e Markdown: uma demonstração construída inteiramente de papéis declarados não carrega mais a linha de divulgação "classificação é inferida", porque nesse ponto a classificação não é uma inferência — é parte dos seus livros.

Erros de digitação são tratados da maneira que uma ferramenta de texto simples deveria tratá-los. cash-flow-role: "invsting" não é silenciosamente aceito e não é silenciosamente ignorado: a conta cai para a heurística padrão, e o painel de status sinaliza — "valor cash-flow-role desconhecido, usando padrão" — para que o erro seja visível onde você olha, não enterrado em um log.

Se você não mudar nada, nada muda​

Contas não anotadas usam os mesmos padrões publicados de antes: Income e Expenses mapeiam para operacional, Assets não-caixa para investimento, Liabilities e Equity para financiamento, e equivalentes de caixa correspondidos por nome formam o monte de caixa. Um livro-razão existente renderiza identicamente antes e depois deste lançamento. A maioria dos usuários anotará um punhado de contas — aquelas onde o padrão está errado — e nunca pensará no resto.

A portabilidade também não é tocada. Metadados em diretivas open são sintaxe central do beancount, analisados por toda ferramenta v2/v3 e ignorados por qualquer coisa que não procure por esta chave específica. bean-check passa, Fava dá de ombros, e seu livro-razão permanece totalmente utilizável fora do Beancount.io.

Toda visão do seu caixa concorda com todas as outras​

Um resolvedor compartilhado produz o papel final para cada conta, e todo consumidor lê dele:

• O relatório de fluxo de caixa constrói suas seções de atividade e seu resultado final — mudança líquida em caixa e equivalentes — a partir dos papéis resolvidos.
• Exportações CSV, Markdown e impressão carregam os mesmos números, com a divulgação de classificação inferida apenas onde uma heurística foi realmente usada.
• O diagrama Sankey da visão geral lê as mesmas declarações, então uma conta que você marcou como caixa para de aparecer como um nó de fluxo, e seus papéis de atividade declarados são honrados para contas não-Income.
• O painel de status da conta para de listar uma conta declarada como um "ativo não classificado".

Não há como a demonstração e o diagrama discordarem sobre o que seu caixa é, porque há apenas uma resposta sobre a qual discordar.

Por que o livro-razão, e não uma página de configurações​

Esta é a parte do lançamento sobre a qual nos sentimos mais fortes. Consideramos uma UI de configurações e a rejeitamos, por três razões:

1. O livro-razão é a fonte da verdade. Uma classificação que vive em qualquer outro lugar pode discordar dos livros que descreve. Uma classificação que vive na diretiva open viaja com a conta — através de renomeações, através de movimentos de repositório, através de todo cliente que lê o arquivo.
2. Texto simples é diffável, greppável e revisável. Se você mantém seu livro-razão em git — e se você usa Beancount.io, você mantém — a regra de classificação agora é algo que você pode grep, diff e blame, e algo que um revisor pode ver em um pull request. Uma página de configurações não é nenhuma dessas coisas.
3. Funciona offline e em qualquer lugar. Qualquer editor pode declarar um papel. Qualquer cliente futuro que leia o livro-razão obtém a classificação de graça, com zero configurações por cliente para sincronizar.

Pela mesma razão, classificações são deliberadamente não efetivas por data. Os metadados descrevem a natureza da conta, que raramente muda; quando muda, você edita a diretiva open, e seu histórico git registra o que mudou e quando. Esse histórico é a trilha de auditoria.

Experimente no seu livro-razão​

O recurso está sendo lançado para todos os livros-razão agora. Declarar um papel requer apenas um editor de texto:

1. Abra o arquivo onde a diretiva open da conta vive.
2. Adicione cash-flow-role: "cash" (ou "operating", "investing", "financing") como uma linha de metadados indentada sob ela.
3. Recarregue o relatório de fluxo de caixa. Sua declaração vence a heurística imediatamente.

Comece com as contas onde a suposição padrão está errada — o CD que não é realmente caixa, o fundo do mercado monetário que realmente é, a conta de corretagem que você quer limpa sob Atividades de Investimento. Deixe o resto em paz. A especificação completa — valores aceitos, precedência, classificações padrão e como valores inválidos são tratados — vive na referência de Papéis de Fluxo de Caixa.

O relatório de fluxo de caixa é parte de todo livro-razão Beancount.io, junto com a demonstração de resultados e o balanço patrimonial. Se você está se atualizando sobre o que mais foi lançado neste verão — importações mais inteligentes, um assistente de IA com capacidade de ação e um aplicativo móvel reconstruído — as notas de lançamento 3.6 cobrem o resto.

Seus livros já sabiam quais contas são investimentos e quais são gastos diários. Agora a demonstração de fluxo de caixa também sabe.