Um Guia para a Interface Web do beancount.io

A interface web do beancount.io (com tecnologia Fava) fornece um conjunto abrangente de ferramentas para gerir, consultar e visualizar os seus dados financeiros. Este guia cobre as suas principais funcionalidades, desde a entrada básica de dados até à personalização avançada e resolução de problemas.

1. Edição e Entrada de Dados

O Editor Integrado

A interface inclui um editor de texto poderoso para fazer alterações diretas aos seus ficheiros Beancount. As principais funcionalidades incluem:

• Autocompletar: Prima Tab para completar nomes de contas, beneficiários, tags e links.

• Atalhos de Teclado:

  • Ctrl+Espaço: Acionar o autocompletar.
  • Ctrl+/: Comentar ou descomentar linhas.
  • Ctrl+D: Duplicar a linha atual.
  • Alt+Seta para Cima/Baixo: Mover a linha atual para cima ou para baixo.

• Posicionamento Inteligente do Cursor: Utilize a opção $insert-entry$ no seu ficheiro para colocar automaticamente o cursor na entrada mais recente para uma conta específica quando o editor abre.

  option "insert-entry" "Expenses:Food:Dining-Out"

Adicionar Transações

Clique no botão + (ou prima n) para abrir o formulário de transação.

• Entrada Rápida: O formulário sugere contas recentes e memoriza montantes comuns para beneficiários.

• Tags/Links Inline: Adicione tags e links diretamente no campo de narração (por exemplo, Almoço #food ^recibo-001).

• Templates de Transação: Crie entradas com datas futuras com uma tag #template. Pode então usar o formulário para as encontrar e preencher.

  2099-01-01 * "Pagamento Mensal da Renda" #template
      Expenses:Housing:Rent      1500.00 USD
      Assets:Checking           -1500.00 USD

2. Gestão de Documentos

Ligue de forma eficiente recibos, extratos e outros ficheiros às suas transações.

• Upload via Arrastar e Largar:

  • Largue um ficheiro no nome de uma conta para o guardar na pasta dessa conta.
  • Largue um ficheiro numa transação no diário para o ligar diretamente.

• Armazenamento de Documentos: Os ficheiros são guardados na pasta especificada pela diretiva $option "documents" "caminho/para/os/seus/documentos"$ no seu ficheiro Beancount.

• Ligação Automatizada: O Beancount pode descobrir e ligar automaticamente documentos a transações. Ative isto com os seguintes plugins:

  plugin "fava.plugins.link_documents"
  plugin "fava.plugins.tag_discovered_documents"

3. Consulta e Análise com BQL

A página Consulta permite-lhe executar consultas na Linguagem de Consulta do Beancount (BQL), semelhante à ferramenta de linha de comandos bean-query.

• Visualização: Os resultados da consulta são automaticamente renderizados como tabelas. Se a sua consulta retornar duas colunas (como uma data/string e um número), a interface também gerará um gráfico de linhas, barras ou treemap.
• Exportação: Descarregue qualquer resultado de consulta como um ficheiro CSV.

Exemplos Práticos de Consulta

• 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 total DESC;

• Receitas vs. Despesas por Mês:

  SELECT YEAR(date) as year, MONTH(date) as month,
         SUM(IIF(account ~ '^Income', -position, 0)) as income,
         SUM(IIF(account ~ '^Expenses', position, 0)) as expenses
  FROM postings
  GROUP BY year, month
  ORDER BY year, month;

4. Personalização e Fluxo de Trabalho

Personalizar a Visualização

Adapte a exibição da interface com estas opções no seu ficheiro Beancount:

• Visibilidade da Conta: Controle quais contas aparecem na barra lateral.

  option "show-closed-accounts" "false"
  option "show-accounts-with-zero-balance" "false"
  option "collapse-pattern" "Assets:Investments:.*"

• Indicadores Atualizados: Pontos coloridos ao lado das contas mostram o seu estado (verde para saldo aprovado, vermelho para falhado, amarelo para nenhuma verificação de saldo recente). Ative isto na diretiva open de uma conta:

  2020-01-01 open Assets:Checking   fava-uptodate-indication: "TRUE"

Links da Barra Lateral

Adicione links personalizados para relatórios frequentemente utilizados ou visualizações filtradas na barra lateral.

2024-01-01 custom "fava-sidebar-link" "Despesas Deste Mês" "/income_statement/?time=month"
2024-01-01 custom "fava-sidebar-link" "Todos os Documentos" "/journal/?show=document"

Configuração Geral

• Vários Ficheiros: Se carregar vários ficheiros .beancount, pode alternar entre eles usando o dropdown no canto superior esquerdo.
• Editor Externo: Configure a IU para abrir ficheiros diretamente no seu editor local usando a opção $use-external-editor$ e um manipulador de URL.
• Idioma: Defina o idioma da interface com a opção $language$, ou deixe-o detetar automaticamente a partir do seu browser.
• Exportação: Exporte qualquer visualização de diário filtrada no formato Beancount usando o botão Exportar.

5. Desempenho e Resolução de Problemas

Lidar com Ficheiros Grandes

Para livros-razão com milhares de transações, melhore o desempenho ao:

• Usar Includes: Divida o seu livro-razão em vários ficheiros por ano ou mês e use a diretiva include.

  include "accounts.beancount"
  include "transactions/2023.beancount"
  include "transactions/2024.beancount"

• Filtrar: Use as opções de tempo e filtro para limitar a quantidade de dados exibidos de uma vez.

Problemas Comuns e Correções

• Interface Não Carrega:

  1. Verifique o seu ficheiro quanto a erros de sintaxe usando a ferramenta de linha de comandos bean-check.
  2. Procure mensagens de erro na parte inferior da página web.
  3. Limpe a cache do seu browser.

• Desempenho Lento:

  1. Reduza o intervalo de datas ativas na IU.
  2. Simplifique consultas BQL complexas.

• Erros de Configuração: Certifique-se de que os nomes das opções e os tipos de diretivas personalizadas estão entre aspas.

  ; Correto
  option "documents" "/caminho/para/docs"
  custom "fava-sidebar-link" "Rótulo" "URL"
  
  ; Incorreto (causará erros)
  option documents "/caminho/para/docs"
  custom fava-sidebar-link "Rótulo" "URL"