Preskočiť na hlavný obsah
Beancount.io Logo
Automatizujte účtovníctvo s bea

Automatizujte účtovníctvo s bea

Skriptujte svoje Beancount účtovné knihy s bea: vyriešte hlavnú knihu explicitne, parsujte JSON obálku s jq, vetvite na exit kódy, spúšťajte bez dozoru a naplánujte nočnú kontrolu.

Skript riadi bea so štyrmi rozhodnutiami: ktorú hlavnú knihu číta, --json pre strojovo čitateľný výstup, jq pre hodnotu, ktorú potrebuje, a exit kód, na ktorom vetví. Táto príručka prechádza týmito štyrmi rozhodnutiami od začiatku do konca a potom ich naplánuje.

Potrebujete bea na stroji, ktorý spúšťa úlohu, a hlavnú knihu, ktorú môže dosiahnuť. Ak začínate nové účtovné knihy, najprv postupujte podľa CLI rýchleho štartu. Každý fakt o prepínačoch, kľúčoch obálky a exit kódoch je vyhľadaný v referencii Beancount CLI, nie je tu zopakovaný.

Vyberte hlavnú knihu explicitne​

Pomenujte súbor. Lokálny príkaz vyrieši svoj cieľ z --file, potom z $BEA_FILE, potom z ./main.bean v pracovnom adresári, a naplánovaná úloha sa málokedy spúšťa tam, kde si myslíte.

bea --file ~/books/main.bean check
BEA_FILE=~/books/main.bean bea check
cd ~/books && bea check

Globálne možnosti idú pred príkaz, ako napríklad bea --file main.bean check. Ak vyriešený súbor neexistuje, príkaz ukončí sa s 2 a uvedie všetky tri zdroje, takže preklep v cron zázname zlyhá hlasno namiesto overovania nesprávnych kníh. Cielené hosťovanie cez --ledger prepínač ešte neexistuje; bea nikdy implicitne nenahráva lokálny súbor.

Čítajte JSON obálku​

Pridajte globálne --json a každý podporovaný príkaz odpovedá s rovnakou obálkou: bea, target, data, truncated a limit na ohraničených zoznamoch. Sumy sú desatinné reťazce a dátumy sú ISO YYYY-MM-DD, takže hodnota je bezpečná na porovnanie bez toho, aby sa do pipeline dostal akýkoľvek float. Kľúče obálky sú tabuľkovo uvedené v referencii JSON a exit kódov.

bea --json --file main.bean report income-statement | jq .data.net_profit
bea --json --file main.bean list transaction --limit 2 | jq '.data[0].postings[0].units'
bea --json --file main.bean import statement.csv --csv date=Date,amount=Amount,payee=Payee \
  --account Assets:Checking --apply --duplicates skip | jq '.data | {written, ready, duplicates}'

Tieto tri príkazy — report, list a import — si zachovávajú svoje tvary výsledkov, takže jq cesta napísaná proti nim zostáva platná. bea --json check a bea --json query tiež dnes emitujú obálku, ale sú to príkazy odovzdávané natívnym Beancount spustiteľným súborom, takže skript by sa mal kľúčovať na exit stav check skôr ako na jeho tvar výstupu. Vyberte si svoju politiku duplicit zámerne: --duplicates je stále potrebné, keď import potrebuje rozhodnutie, ako vysvetľuje importovací návod.

Zastavte na správnom exit kóde​

Vetvite na stave a prečítajte chybový objekt pred opakovaním čohokoľvek, čo zapisuje. V --json režime zlyhanie nezapíše nič na stdout a presne jeden objekt na stderr, ktorého error.category pomenúva triedu: validation (1), usage (2), auth (3), conflict (4).

#!/usr/bin/env bash
set -euo pipefail
 
out=$(mktemp)
err=$(mktemp)
status=0
 
bea --json --file main.bean report income-statement >"$out" 2>"$err" || status=$?
 
case "$status" in
  0) jq -r '.data.net_profit | to_entries[] | "net profit: \(.value) \(.key)"' "$out" ;;
  4) echo "conflict — inspect the ledger before retrying" >&2
     jq -r '.error.message' "$err" >&2
     exit 4 ;;
  *) jq -r '.error | "\(.category) (exit \(.exit_code)): \(.message)"' "$err" >&2
     exit "$status" ;;
esac

Exit 4 je ten, ktorý skript nikdy nesmie slepo opakovať: znamená to, že výsledok je konflikt alebo je neznámy, ako napríklad externá úprava prichádzajúca uprostred zápisu alebo init cieľ, ktorý už existuje. Preskúmajte hlavnú knihu, potom opakujte od čerstvého čítania. Exit 1 pokrýva validačné zlyhania a akýkoľvek iný runtime error; error.details nesie jednotlivé chyby hlavnej knihy a error.result nesie to, čo čiastočný zápis skutočne urobil. Nonzero exit nikdy nezaručuje, že sa nič nezmenilo.

Spúšťajte bez terminálu​

bea prestane vyzývať sám. --no-input je implicitný vždy, keď stdin nie je terminál, vždy, keď je nastavený --json, a vždy, keď je CI pravdivé — 1, true, yes alebo on. V tomto režime chýbajúce potvrdenie zlyhá s exit 2 namiesto čakania naveky.

CI=true BEA_NO_UPDATE_NOTIFIER=1 bea --json --file main.bean report balance-sheet
bea --json --file main.bean list transaction --limit 100 --sort oldest

Čítania sú zhovievavé v termináli a prísne všade inde. Keď má hlavná kniha chyby loaderu, query, list a report ukončia sa s 1 pod --json, pod rúrkovaným stdout, pod pravdivým CI, alebo s --strict; odovzdajte vlastný --allow-errors príkazu, aby ste prijali čiastočnú odpoveď, čo tiež nastaví ledger_valid: false a vyplní ledger_errors v JSON. --strict je zrkadlový obraz: odmieta čiastočné odpovede aj v termináli, čo je to, čo chcete, keď človek spúšťa rovnaký skript ručne. bea check nemá --allow-errors — hlásenie chýb je jeho celá práca — a vždy ukončí sa s 1, keď nájde akékoľvek. Nastavte BEA_NO_UPDATE_NOTIFIER=1 na stíšenie pasívneho upozornenia na aktualizáciu; pravdivé CI to už robí.

Naplánujte kontrolu​

Spúšťajte validáciu každú noc a nechajte exit kód byť alarmom. Oba bloky nižšie sú šablóny — cesty, plán a spúšťač sú vaše.

# crontab -e — 07:15 daily; cron mails you only when bea exits nonzero
15 7 * * * BEA_NO_UPDATE_NOTIFIER=1 /opt/homebrew/bin/bea --file /home/alice/books/main.bean check
name: ledger
on:
  schedule:
    - cron: "15 7 * * *"
  push:
jobs:
  check:
    runs-on: ubuntu-latest
    env:
      BEA_NO_UPDATE_NOTIFIER: "1"
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install beancount-io==0.1.0
      - run: bea --file main.bean check
      - run: bea --json --file main.bean report balance-sheet > balance-sheet.json

Pripnite verziu, keď úloha musí byť reprodukovateľná, a zrušte pripnutie, keď by ste radšej sledovali vydania. CI je už pravdivé na GitHub Actions, takže výzvy sú vypnuté a upozornenie na aktualizáciu je tiché predtým, než čokoľvek nastavíte. Nie je tu zámerne žiadny krok formátovania. Naplánovaná úloha by nemala prepisovať súbory, ktoré nemusela, takže siahajte po bea format --check v pre-commit háku, ktorý sa ničoho nedotýka a ukončí sa s 1, keď súbor potrebuje formátovanie.

Použite hosťovaný poverovací údaj v úlohe​

Nastavte BEA_TOKEN z úložiska tajomstiev vášho CI poskytovateľa a preskočte prihlásenie cez prehliadač úplne. Token sa číta z prostredia a nikdy sa nezapisuje na disk, takže nič nepristane v domovskom adresári spúšťača pre ďalšiu úlohu.

export BEA_TOKEN="$YOUR_CI_SECRET"
bea --json cloud status

Exit 0 znamená, že poverovací údaj sa vyriešil a obálka pomenúva účet, ktorému patrí; exit 3 s error.category auth znamená, že nie, a správa rozlišuje nenastavený poverovací údaj od odmietnutého. bea cloud logout neurobí nič s tokenom dodaným týmto spôsobom — ani ho neodvolá, ani ho nenastaví, pretože iná úloha ho môže zdieľať — takže odvolajte uniknutý token z dashboardu namiesto toho. Lokálne príkazy nepotrebujú žiadny poverovací údaj; iba bea cloud a bea ask dosahujú hosťovanú službu. Úplný zoznam premenných je v referencii nastavení.

Nie všetko odpovedá v JSON. bea ask odmieta JSON režim priamo, bea cloud login potrebuje človeka a úspešný bea cloud logout alebo bea cloud ledger clone nevracia žiadny JSON úspech objekt — čítajte ich exit stav namiesto toho. Výstup pomoci, verzie a shell-kompletnosti zostáva textový.

Ďalšie kroky​

Automatizujte účtovníctvo s bea

Zdroj: https://beancount.io/sk/docs/Solutions/automate-bookkeeping-with-bea