Recursos da Interface

Use o editor, o formulário de transações e os relatórios de consulta para trabalhar com seu livro-razão. As receitas executáveis abaixo visam Fava 1.30.16 padrão com Beancount 3.2.3 e beanquery 0.2.0; siga a configuração local fixada.

O beancount.io usa um painel separado. Sua fonte de produto confirma rotas de livro-razão para edição, consultas, documentos e Configurações, além de consumidores para várias opções de exibição do Fava. Isso não torna os atalhos de teclado, regras de inserção, execução de plugins ou caminhos de URL do Fava padrão uma promessa de compatibilidade hospedada. A imagem abaixo mostra o painel hospedado, não a interface padrão.

Explore o livro-razão ao vivo →

1. Edição e Entrada de Dados​

O Editor Integrado​

O editor do Fava padrão oferece autocompletar para contas, beneficiários e tags. Use default-file para escolher seu arquivo de origem inicial. insert-entry também posiciona o cursor no marcador de inserção mais recente nesse arquivo; não é uma opção principal do Beancount.

2000-01-01 custom "fava-option" "default-file"
2024-01-01 custom "fava-option" "insert-entry" "^Expenses:Food$"

Este trecho seleciona o arquivo que o contém. Novas entradas após 1 de janeiro de 2024 que correspondam a Expenses:Food são inseridas antes do marcador, a menos que uma regra elegível posterior ou a conta de um lançamento posterior tenha precedência. Veja o exemplo completo de inserção em múltiplos arquivos.

Adicionando Transações​

No Fava padrão, clique em + ou pressione n para abrir o formulário de transação. O campo de narração aceita tags e links separados por espaços, como Lunch #food ^receipt-001. Nomes de contas devem já ter diretivas open.

Salve este livro-razão completo como ui-demo.beancount para testar os relatórios abaixo. A despesa positiva é um débito; o lançamento de caixa negativo é seu crédito.

option "title" "UI Demo"
option "operating_currency" "USD"
2024-01-01 open Assets:Checking USD
  fava-uptodate-indication: TRUE
2024-01-01 open Income:Salary USD
2024-01-01 open Expenses:Food USD
 
2024-01-02 * "Salary"
  Assets:Checking    3000.00 USD
  Income:Salary     -3000.00 USD
 
2024-01-03 * "Groceries" #food
  Expenses:Food       400.00 USD
  Assets:Checking    -400.00 USD
 
2024-01-04 balance Assets:Checking 2600.00 USD

Execute bea --file ui-demo.beancount check, depois fava ui-demo.beancount. A verificação passa e o saldo totaliza 2.600,00 USD. Uma transação com data futura e #template ainda é uma transação real: essa tag não a torna um modelo de formulário reutilizável inerte. Mantenha transações hipotéticas em um livro-razão de cenário separado.

2. Gestão de Documentos​

O Fava padrão pode enviar documentos arrastando-os sobre nomes de contas ou linhas de diário. Configure uma raiz de documentos real e mantenha sua hierarquia de contas consistente com suas contas abertas.

Este trecho opcional pode ser adicionado a ui-demo.beancount. Primeiro crie um diretório documents ao lado do livro-razão. Para testar a descoberta, coloque um arquivo real chamado 2024-01-03-receipt.pdf dentro de documents/Expenses/Food/.

option "documents" "documents"
plugin "fava.plugins.link_documents"
plugin "fava.plugins.tag_discovered_documents"

Estes são módulos reais fornecidos no Fava 1.30.16. O Beancount descobre arquivos datados em diretórios de contas; tag_discovered_documents adiciona #discovered. link_documents corresponde metadados document a entradas de documentos e os vincula. Ele não infere uma associação de transação a partir do conteúdo de um recibo. Adicione estes metadados diretamente sob o cabeçalho existente de Groceries, antes de seus lançamentos:

  document: "2024-01-03-receipt.pdf"

Essa linha indentada é um fragmento de metadados, não um livro-razão autônomo. Com o arquivo presente, o documento recebe #linked e compartilha ^dok-2024-01-03 com a transação. Documentos correspondentes ausentes produzem um erro. Para o comportamento exato padrão, veja o plugin de vinculação de documentos versionado.

3. Consultas e Análise com BQL​

A página de Consulta do Fava padrão executa a Linguagem de Consulta do Beancount. Limpe os filtros globais de tempo/conta antes de reproduzir esses resultados de livro-razão completo. Esses filtros de interface podem remover entradas antes de uma consulta ser executada.

Os resultados podem ser baixados como CSV. O suporte a gráficos depende dos tipos de resultado: a ajuda padrão descreve exatamente duas colunas, com uma data ou string seguida por um inventário. Um par arbitrário de colunas numéricas não garante um gráfico.

Exemplos Práticos de Consulta​

Execute estas consultas contra ui-demo.beancount na página de Consulta do Fava ou passe cada consulta entre aspas para bea --file ui-demo.beancount query.

Resumo mensal de despesas:

SELECT account, SUM(position) AS total
FROM postings
WHERE account ~ '^Expenses:'
  AND date >= 2024-01-01 AND date < 2024-02-01
GROUP BY account
ORDER BY account;

Resultado esperado: Expenses:Food, 400,00 USD.

Receitas vs. despesas por mês:

SELECT YEAR(date) AS year, MONTH(date) AS month,
       ROOT(account, 1) AS category, currency,
       SUM(number) AS signed_total
FROM postings
WHERE account ~ '^(Income|Expenses):'
GROUP BY year, month, category, currency
ORDER BY year, month, category, currency;

A consulta preserva os sinais do Beancount e agrupa unidades separadamente por moeda. Receitas de 3.000,00 USD menos despesas de 400,00 USD deixam 2.600,00 USD. É um relatório de unidades, não um relatório de conversão ou base de custo. IIF não está disponível no beanquery 0.2.0, e -position unário não é suportado; agrupar as duas categorias de contas evita ambas as operações.

4. Personalização e Fluxo de Trabalho​

Personalizando a Visualização​

Adicione estas diretivas do Fava ao livro-razão de exemplo para ocultar contas com saldo zero e recolher ramos de investimento:

2000-01-01 custom "fava-option" "show-closed-accounts" "false"
2000-01-01 custom "fava-option" "show-accounts-with-zero-balance" "false"
2000-01-01 custom "fava-option" "collapse-pattern" "^Assets:Investments"

Elas afetam as árvores de contas dos relatórios. Contas com saldos não nulos permanecem visíveis. Formulários principais como option "show-closed-accounts" "false" falham na validação do Beancount.

Os metadados fava-uptodate-indication: TRUE da amostra estão em sua própria linha indentada sob open. Não os coloque na linha open nem cite o booleano. Uma verificação de saldo mais recente aprovada produz verde; uma verificação reprovada produz vermelho; uma transação subsequente produz amarelo. A afirmação de 4 de janeiro é verde. Um indicador de frescor cinza separado também pode aparecer porque essas datas são antigas.

Links da Barra Lateral​

Para o exemplo padrão intitulado UI Demo, estes caminhos completos levam aos seus relatórios:

2024-01-01 custom "fava-sidebar-link" "January Expenses" "/ui-demo/income_statement/?time=2024-01"
2024-01-01 custom "fava-sidebar-link" "All Documents" "/ui-demo/documents/"

Estes caminhos assumem que o Fava padrão está montado na raiz do host. Substitua /ui-demo pelo slug real do seu livro-razão e inclua qualquer prefixo de montagem do servidor. Veja links personalizados da barra lateral para comportamento /jump testado e o limite de roteamento hospedado.

Configuração Geral​

Iniciar o Fava padrão com múltiplos arquivos principais cria livros-razão separados em seu alternador de livros. Arquivos trazidos via include permanecem parte de um livro-razão e aparecem como fontes editáveis; não são livros separados.

Use opções do Fava para language, default-file e use-external-editor. Um editor externo precisa de um manipulador beancount:// e acesso aos arquivos de origem. Módulos de extensão reais padrão também incluem fava.ext.auto_commit e fava.ext.portfolio_list. Extensões usam custom "fava-extension" com seus próprios pré-requisitos; são distintas das diretivas plugin usadas acima. Veja a ajuda de extensões versionada do Fava.

5. Desempenho e Solução de Problemas​

Lidando com Arquivos Grandes​

Use includes para organizar um livro-razão por conta ou período. O Beancount ainda carrega os arquivos incluídos, então dividir um livro não reduz em si a entrada do relatório. Limite as datas exibidas e simplifique consultas caras quando precisar de um relatório menor.

Problemas Comuns e Correções​

• Erros no livro-razão: Execute bea check e inspecione o relatório de Erros do Fava. Uma página pode renderizar enquanto o carregador tem erros.
• Comportamento inesperado de opções: Verifique o runtime testado e use diretivas personalizadas datadas do Fava. bea check não pode detectar uma opção desconhecida do Fava por si só.
• Totais de consulta inesperados: Limpe filtros globais, inclua histórico de abertura e mantenha moedas separadas.
• Documentos ausentes: Verifique se o diretório existe, a conta está aberta, o nome do arquivo começa com uma data válida e os metadados da transação correspondem ao documento.

Para contraste, estes são exemplos inválidos intencionais. Eles não devem ser copiados para um livro-razão funcional:

option "insert-entry" "Expenses:Food"
custom "fava-sidebar-link" "Label" "/jump?time=month"

O primeiro usa uma opção principal desconhecida. O segundo omite a data obrigatória. A referência de recursos padrão descreve o comportamento da interface para esta versão.