Salta al contenuto principale

Collegamenti Personalizzati e Query

Impara come migliorare la tua esperienza con Beancount implementando collegamenti personalizzati nella barra laterale e query SQL per ottimizzare il monitoraggio e la reportistica finanziaria.

Aggiungi direttive di collegamento nella barra laterale con data al Fava standard, poi salva una query che trovi saldi finali negativi dopo aver sommato tutte le registrazioni. Gli esempi sono stati eseguiti con Beancount 3.2.3, beanquery 0.2.0 e Fava 1.30.16. Utilizza la configurazione locale bloccata.

Questi URL puntano a un server Fava locale standard. La dashboard ospitata da Beancount.io ha percorsi di report diversi ed è trattata separatamente di seguito.

Perché Personalizzare Fava?​

Le scorciatoie nella barra laterale preservano una vista filtrata utile. Una query salvata può poi rispondere a una specifica domanda contabile senza dover reinserire BQL.

Problemi che questa soluzione risolve:​

  • Selezionare ripetutamente il mese corrente o precedente.
  • Riaprire un report salvato.
  • Distinguere un'uscita da un conto che in realtà termina sotto zero.

✨ Collegamenti Personalizzati nella Barra Laterale​

Aggiungi queste direttive al ledger completo sidebar-demo.beancount nella sezione successiva. Avvialo con fava sidebar-demo.beancount e apri il suo report Giornale prima di cliccare una scorciatoia.

2021-01-01 custom "fava-sidebar-link" "Current Month" "/jump?time=month"
2021-01-01 custom "fava-sidebar-link" "Last Month" "/jump?time=month-1"
2021-01-01 custom "fava-sidebar-link" "Clear All" "/jump?account=&time=&filter="

Cosa Fanno:​

/jump ritorna alla pagina nell'header Referer del browser e sostituisce i parametri di query forniti. Non apre sempre il report Giornale. Nel bilancio di verifica, rimane sul bilancio di verifica. Questo comportamento è implementato dal gestore di reindirizzamento Fava standard.

  • Mese Corrente: Imposta time=month sul report corrente.
  • Mese Precedente: Imposta time=month-1 sul report corrente.
  • Cancella Tutto: Rimuove account, time e filter. Altri parametri, come conversione e intervallo, rimangono.

Il fixture del 2021 non avrà transazioni nel mese odierno; usa Cancella Tutto prima di riprodurre i risultati delle sue query. Un URL /jump richiede un referrer. Per un segnalibro aperto direttamente, copia invece un URL di report funzionante completo.

Alla root dell'host, /jump?time=month è stato testato da /sidebar-demo/journal/?time=2021&account=Assets: ha restituito HTTP 302 allo stesso giornale con account=Assets&time=month. Il report di destinazione ha restituito 200.

Se un amministratore monta l'intera applicazione Fava su /books, ogni scorciatoia relativa alla root deve includere quel prefisso. Questa è una configurazione alternativa, non un'altra direttiva da aggiungere insieme a Mese Corrente sopra:

2021-01-01 custom "fava-sidebar-link" "Current Month" "/books/jump?time=month"

Un test di montaggio WSGI locale ha verificato che /books/jump reindirizza a /books/sidebar-demo/journal/ con il nuovo filtro. Il semplice /jump è fuori da quel montaggio e ha restituito 404. I collegamenti personalizzati di Fava preservano l'URL fornito; una / iniziale significa root dell'host, non root del ledger.

Ambito ospitato, verificato il 2026-09-07: il sorgente della dashboard Beancount.io utilizza percorsi come /ledger/OWNER/LEDGER/income-statement e /ledger/OWNER/LEDGER/query. La sua barra laterale costruisce il proprio menu di report. Il sorgente ispezionato non ha una route /jump o un consumatore di fava-sidebar-link. Questa ricetta standard non è quindi stabilita per quella dashboard. Sul prodotto ospitato, apri il report desiderato e aggiungi ai segnalibri il suo indirizzo funzionante. Lo snapshot del sorgente non prova quale revisione sia in esecuzione su una distribuzione live.

🔍 Query SQL Personalizzate​

Salva questo fixture completo come sidebar-demo.beancount. Include deliberatamente sia registrazioni positive che negative in ogni conto patrimoniale:

option "title" "Sidebar Demo"
option "operating_currency" "USD"
2021-01-01 open Assets:BCM:Positive USD
2021-01-01 open Assets:BCM:Negative USD
2021-01-01 open Equity:Opening-Balances USD
 
2021-12-01 * "Opening balances"
  Assets:BCM:Positive        100.00 USD
  Assets:BCM:Negative         20.00 USD
  Equity:Opening-Balances   -120.00 USD
 
2021-12-10 * "Outflows"
  Assets:BCM:Positive        -30.00 USD
  Assets:BCM:Negative        -50.00 USD
  Equity:Opening-Balances     80.00 USD
 
2022-01-05 * "Refund"
  Assets:BCM:Negative         10.00 USD
  Equity:Opening-Balances    -10.00 USD
 
2022-01-09 balance Assets:BCM:Positive 70.00 USD
2022-01-09 balance Assets:BCM:Negative -20.00 USD

bea --file sidebar-demo.beancount check passa. All'inizio del 9 gennaio, Positive detiene 100 - 30 = 70 USD; Negative detiene 20 - 50 + 10 = -20 USD.

Esegui questa query nella pagina Query di Fava standard con i filtri globali cancellati:

SELECT account, currency, SUM(number) AS ending_balance
FROM postings
WHERE account ~ ':BCM:'
  AND date < 2022-01-09
GROUP BY account, currency
HAVING SUM(number) < 0
ORDER BY account, currency;
ContoValutaSaldo finale
Assets:BCM:NegativeUSD-20.00

Analisi:​

WHERE seleziona le registrazioni da aggregare. Non c'è un limite inferiore di data: un saldo finale richiede tutta la storia precedente, inclusi i saldi di apertura del 1° dicembre. Il limite superiore esclusivo include l'8 gennaio ed esclude le transazioni del 9 gennaio.

GROUP BY account, currency mantiene separate le diverse valute. HAVING SUM(number) < 0 filtra dopo aver sommato le quantità positive e negative di ciascun gruppo. Questo è un saldo finale in unità per valuta, non un valore di mercato convertito in una sola valuta. Riporta ogni conto esatto, non conti padre aggregati.

Per confronto, questa query eseguibile risponde a una domanda diversa: quanto è stato registrato negativamente durante la finestra di revisione?

SELECT account, currency, SUM(number) AS negative_postings
FROM postings
WHERE account ~ ':BCM:'
  AND number < 0
  AND date >= 2021-12-09 AND date < 2022-01-09
GROUP BY account, currency
ORDER BY account, currency;
ContoValutaRegistrazioni negative
Assets:BCM:NegativeUSD-50.00
Assets:BCM:PositiveUSD-30.00

La seconda query omette il rimborso e i saldi di apertura. La sua riga -30.00 USD non significa che Positive è scoperto. Aggiungere un limite inferiore di data alla prima query produrrebbe invece il movimento netto durante un periodo, non un saldo finale. Vedi il riferimento BQL per ulteriore sintassi delle query.

Casi d'uso:​

  • Controlla i conti patrimoniali per quantità negative inaspettate.
  • Rivedi le registrazioni negative separatamente quando indaghi su uscite o storni.
  • Riconcilia il saldo riportato con la storia di apertura e l'attività successiva prima di trattarlo come un'anomalia. Un saldo negativo di passività o entrate può essere normale.

🛠 Suggerimento Pro: Combina Collegamenti + Query​

Fava supporta i collegamenti alle query. Aggiungi questa query salvata e scorciatoia a sidebar-demo.beancount:

2021-01-01 query "negative-balances" "SELECT account, currency, SUM(number) AS ending_balance FROM postings WHERE account ~ ':BCM:' AND date < 2022-01-09 GROUP BY account, currency HAVING SUM(number) < 0 ORDER BY account, currency"
2021-01-01 custom "fava-sidebar-link" "Negative Balances" "/sidebar-demo/query/?query_string=.run+%22negative-balances%22"

La direttiva della query appare anche nella barra laterale delle query salvate di Fava, soggetta a sidebar-show-queries (default 5). La scorciatoia esplicita punta allo slug sidebar-demo del fixture ed esegue la query nominata. La pagina Query standard legge query_string dall'URL; la sua API di query ha restituito la stessa singola riga -20.00 USD nel test locale. Vedi il componente Query versionato.

Usa lo slug effettivo del tuo ledger in un libro diverso. Sotto il montaggio /books, la scorciatoia diventa /books/sidebar-demo/query/?query_string=.run+%22negative-balances%22. Mantieni i filtri globali cancellati per un saldo finale a storia completa; un filtro data può rimuovere la storia di apertura prima che la query salvata venga eseguita.

Considerazioni Finali​

Usa le scorciatoie mensili per navigare tra i report e usa la query salvata per verificare un saldo finale riproducibile. Quando rivedi il tuo budget, distingui uscite, movimento di periodo e saldi di chiusura prima di interpretare un numero negativo. Per ulteriori report, vedi la documentazione delle estensioni di Fava e la guida all'interfaccia utente.

Collegamenti Personalizzati e Query

Fonte: https://beancount.io/it/docs/Tips/side-bar-link