Екосистема Beancount: Комплексний аналіз
Основна функціональність та філософія Beancount
Beancount — це система бухгалтерського обліку подвійного запису з відкритим вихідним кодом, яка використовує текстові файли для запису транзакцій. По суті, Beancount розглядає вашу бухгалтерську книгу як набір даних, визначений простою, суворою граматикою. Кожна фінансова подія (транзакції, відкриття рахунків, ціни на товари тощо) є директивою в текстовому файлі, яку Beancount аналізує та перетворює на базу даних записів у пам'яті. Ця архітектура забезпечує дотримання принципу подвійного запису: кожна транзакція повинна балансувати дебети та кредити між рахунками. Результатом є високопрозора та аудитована бухгалтерська книга, яку можна легко контролювати за версіями, перевіряти та запитувати.
Філософія – коректність та мінімалізм: Дизайн Beancount надає пріоритет цілісності даних та простоті. Його творець, Мартін Блейс, описує Beancount як "песимістичний", припускаючи, що користувач робитиме помилки, і тому накладає додаткові перевірки та обмеження. Наприклад, Beancount не дозволить вам видалити активи, які ніколи не були додані (запобігаючи від'ємним залишкам запасів або готівки), і може вимагати, щоб кожен рахунок був відкритий перед використанням. Йому бракує концепції "віртуальних" або автоматично збалансованих проводок Ledger – це свідомий вибір, щоб змусити використовувати повністю збалансовані записи. Beancount ефективно "йде напролом" у коректності, надаючи більше перехресних перевірок, ніж забезпечує базовий подвійний запис. Цей обережний підхід приваблює користувачів, які "не надто довіряють собі" і хочуть, щоб програмне забезпечення виявляло їхні помилки.
Мінімальні опції, максимальна послідовність: На відміну від безлічі прапорців командного рядка та параметрів налаштування Ledger, Beancount обирає мінімалізм. Існує дуже мало глобальних опцій, і жодна з них не змінює семантику транзакцій за межами файлу бухгалтерської книги. Всі конфігурації, що впливають на облік (наприклад, методи обліку собівартості товарів або припущення щодо обліку), виконуються у файлі за допомогою директив або плагінів, що гарантує, що завантаження одного й того ж файлу завжди дає однакові результати, незалежно від того, як генеруються звіти. Цей дизайн дозволяє уникнути складності численних налаштувань Ledger та тонких взаємодій між ними. Філософія Beancount полягає в тому, що інструмент обліку повинен бути стабільним, детермінованим конвеєром від вхідного файлу до звітів. Він досягає цього, розглядаючи бухгалтерську книгу як впорядкований потік директив, які можуть бути програмно оброблені послідовно. Навіть те, що Ledger розглядає як спеціальний синтаксис (наприклад, початкові залишки або заяви про ціни), є першокласними директивами в моделі даних Beancount, що робить с истему дуже розширюваною.
Розширюваність за допомогою плагінів та мови запитів: Beancount реалізовано на Python і надає хуки для впровадження власної логіки в конвеєр обробки. Користувачі можуть писати плагіни на Python, які працюють з потоком транзакцій (наприклад, для застосування власного правила або генерації автоматичних записів). Ці плагіни запускаються під час обробки файлу, ефективно розширюючи основну функціональність Beancount без необхідності модифікації вихідного коду. Beancount також включає потужну мову запитів (на основі SQL) для аналізу та деталізації бухгалтерської книги. Інструмент bean-query
розглядає проаналізовану бухгалтерську книгу як базу даних і дозволяє виконувати на ній аналітичні запити – наприклад, підсумовувати витрати за категоріями або витягувати всі транзакції для певного одержувача. У Beancount 3.x ця можливість запитів була перенесена в окремий пакет beanquery
, але з точки зору користувача вона все ще забезпечує гнучку звітність за допомогою SQL-подібних запитів.
Простий текст та контроль версій: Як інструмент обліку на основі простого тексту, Beancount наголошує на контролі користувача та довговічності даних. Бухгалтерська книга – це просто текстовий файл .beancount
, який можна редагувати в будь-якому текстовому редакторі. Це означає, що вся ваша фінансова історія зберігається в людиночитаному форматі, і ви можете розмістити її в Git або іншій VCS для відстеження змін з часом. Користувачі часто зберігають свій файл Beancount під контролем версій, щоб підтримувати аудиторський слід кожної зміни (з повідомленнями комітів, що описують зміни). Цей підхід відповідає філософії Beancount, згідно з якою облікові дані, особливо особисті фінанси або фінанси малого бізнесу, повинні бути прозорими та "стійкими до майбутніх змін" – не заблокованими у власницькій базі даних. За словами самого Мартіна Блейса, Beancount – це "плід праці", створений бути простим, довговічним та безкоштовним для спільноти. Він був вперше розроблений близько 2007 року і еволюціонував через значні переробки (з v1 до v2, а тепер v3 у 2024 році), щоб удосконалити свій дизайн, зберігаючи при цьому свою основну філософію мінімалізму та коректності.
Інструменти, Плагіни та Розширення в Екосистемі Beancount
Екосистема Beancount розвинула багатий набір інструментів, плагінів та розширень, що покращують основну функціональність бухгалтерської книги. Вони охоплюють імпорт даних, редагування бухгалтерських книг, перегляд звітів та додавання спеціалізованих бухгалтерських функцій. Нижче наведено огляд ключових компонентів та додатків у світі Beancount:
Утиліти для імпорту даних (Імпортери)
Однією з найважливіших потреб для практичного використання є імпортування транзакцій з банків, кредитних карток та інших фінансових установ. Beancount надає фреймворк для імпорту та скрипти для імпорту, надані спільнотою, для цієї мети. У Beancount 2.x вбудований модуль beancount.ingest
(з командами, такими як bean-extract
та bean-identify
) використовувався для визначення плагінів імпортерів на Python та їх застосування до завантажених виписок. У Beancount 3.x це було замінено зовнішнім проєктом під назвою Beangulp. Beangulp — це спеціалізований фреймворк для імпортерів, який еволюціонував з beancount.ingest
і тепер є рекомендованим способом автоматизації імпорту транзакцій для Beancount 3.0. Він дозволяє писати скрипти Python або інструменти командного рядка, які читають зовнішні файли (такі як виписки CSV або PDF) та виводять записи Beancount. Цей новий підхід відокремлює логіку імпорту від ядра Beancount – наприклад, стара команда bean-extract
була видалена у версії 3, і натомість ваші скрипти імпорту самі генерують транзакції через інтерфейс командного рядка Beangulp.
Десятки готових імпортерів існують для різних банків та форматів, надані спільнотою. Існують скрипти імпортерів для установ по всьому світу – від Alipay та WeChat Pay у Китаї, до різних європейських банків (Commerzbank, ING, ABN AMRO тощо), до американських банків, таких як Chase та Amex. Багато з них зібрані у публічних репозиторіях (часто на GitHub) або в пакетах, таких як beancount-importers
. Наприклад, проєкт Tarioch Beancount Tools (tariochbctools
) надає імпортери для швейцарських та британських банків і навіть обробляє імпорт криптотранзакцій. Іншим прикладом є Lazy Beancount, який містить набір поширених імпортерів (для Wise, Monzo, Revolut, IBKR тощо) та надає налаштування на основі Docker для легкої автоматизації. Незалежно від того, який банк чи фінансовий сервіс ви використовуєте, ймовірно, хтось вже написав імпортер Beancount для нього – або ви можете написати свій власний, використовуючи фреймворк Beangulp. Гнучкість Python означає, що імпортери можуть обробляти парсинг файлів CSV/Excel, завантаження OFX/QIF або навіть скрапінг API, а потім генерувати транзакції у стандартизованому форматі Beancount.
Редагування та інтеграція з редакторами
Оскільки бухгалтерські книги Beancount — це просто текст, користувачі часто використовують свої улюблені текстові редактори або IDE для їх ведення. Екосистема пропонує плагіни підтримки редакторів, щоб зробити цей досвід зручнішим. Існують розширення для багатьох популярних редакторів, які додають підсвічування синтаксису, автозаповнення назв рахунків та перевірку помилок у реальному часі:
- Режим Beancount для Emacs: Доступний основний режим Emacs (
beancount-mode
) для редагування файлів .beancount, що пропонує такі функції, як підсвічування синтаксису та інтеграцію з перевіркою Beancount. Він може навіть запускатиbean-check
у фоновому режимі, щоб помилки в бухгалтерській книзі (наприклад, незбалансована транзакція) позначалися під час редагування. - Розширення VS Code: Розширення Beancount на VSCode Marketplace надає подібні зручності для користувачів Visual Studio Code. Воно підтримує підсвічування синтаксису, вирівнювання сум, автозаповнення для рахунків/одержувачів і навіть перевірку балансу на льоту при збереженні файлу. Воно також може інтегруватися з Fava, дозволяючи запускати веб-інтерфейс Fava з VSCode.
- Плагіни або режими також існують для Vim, Atom та інших редакторів. Наприклад, існує граматика Tree-sitter для Beancount, яка забезпечує підсвічування синтаксису в сучасних редакторах і навіть була прийнята у веб-компоненті редактора Fava. Коротко кажучи, незалежно від вашого середовища редагування, спільнота, ймовірно, надала плагін, щоб зробити редагування файлів Beancount зручним і безпомилковим.
Для швидкого введення транзакцій поза традиційними редакторами також існують такі інструменти, як Bean-add та мобільні додатки. Bean-add — це інструмент командного рядка, який дозволяє додавати нову транзакцію через запит або в один рядок, обробляючи пропозиції щодо дати та рахунку. На мобільних пристроях проєкт під назвою Beancount Mobile надає простий інтерфейс для введення транзакцій на ходу (наприклад, запис готівкової покупки з вашого телефону). Крім того, існує Telegram-бот Beancount для фіксації транзакцій через повідомлення — ви можете надіслати повідомлення з деталями транзакції, і бот відформатує його у файл вашої бухгалтерської книги.
Веб-інтерфейси та інструменти візуалізації
(Fava) Веб-інтерфейс Fava надає інтерактивну панель інструментів для Beancount, що містить такі звіти, як звіт про прибутки та збитки з візуалізаціями (тут показано як деревоподібну діаграму витрат за категоріями) разом з таблицями рахунків та залишків.
Флагманським фронтендом для Beancount є Fava, сучасний веб-інтерфейс. Fava працює як локальний веб-додаток, який читає ваш файл Beancount і створює насичений інтерактивний досвід у вашому браузері. Він пропонує повний набір звітів: баланс, звіт про прибутки та збитки, чиста вартість з часом, склад портфеля, графіки ефективності, бюджети та багато іншого – все готове до використання. Користувачі часто називають Fava головною причиною вибору Beancount серед інших інструментів текстового обліку. За допомогою однієї команди (fava ledger.beancount
) ви можете переглядати свої фінанси за допомогою графіків та таблиць замість тексту. Fava підтримує такі функції, як: деталізація рахунків, фільтрація транзакцій за отримувачем або тегом, редактор запитів (щоб ви могли виконувати запити Beancount та бачити результати в браузері), і навіть інтегрований веб-редактор для вашої книги обліку. Він дуже зручний у використанні, що робить текстовий облік доступним для тих, хто віддає перевагу візуальним інтерфейсам.
Під капотом Fava написана на Python (Flask на бекенді) та JavaScript (Svelte на фронтенді). Вона має власний цикл випуску та активно підтримується. Зокрема, Fava йшла в ногу з розробкою Beancount – наприклад, Fava 1.30 додала підтримку Beancount v3, перейшовши на вико ристання нових пакетів beanquery
та beangulp
всередині. (Вона все ще підтримує Beancount 2 для старіших книг обліку.) Зосередженість Fava на зручності використання включає приємні дрібниці, такі як автозавершення у веб-редакторі, та елегантний інтерфейс користувача з темним режимом та адаптивними діаграмами. Існує також відгалуження під назвою Fava-GTK, яке пакує Fava в настільний додаток для користувачів GNOME/Linux, які віддають перевагу відчуттю нативного додатку.
Крім Fava, існують інші варіанти візуалізації та аналізу. Оскільки дані Beancount можуть бути експортовані або запитувані як таблиці, користувачі часто використовують такі інструменти, як Jupyter notebooks або Pandas для власного аналізу. Наприклад, один користувач описує витягування даних з Beancount через інтерфейс запитів у Pandas DataFrame для підготовки власного звіту. Існують також скрипти, надані спільнотою, для конкретних звітів – наприклад, інструмент аналізу розподілу портфеля або контрольна карта процесу для витрат порівняно з чистою вартістю. Однак, для більшості людей Fava надає більш ніж достатньо можливостей звітності без необхідності писати код. Вона навіть підтримує розширення: ви можете просто додати файли Python, які додають нові сторінки звітів або діаграми до Fava. Помітним розширенням є fava-envelope для конвертного бюджетування всередині Fava. Загалом, Fava слугує центральним вузлом візуалізації екосистеми Beancount.
Інструменти командного рядка та скрипти
Beancount постачається з різноманітними інструментами командного рядка (особливо в старішій гілці v2, деякі з яких були скорочені у v3). Ці інструменти працюють з вашим файлом облікової книги для його перевірки або генерації певних звітів у текстовому форматі або HTML:
- bean-check: валідатор, який перевіряє файл на синтаксичні або бухгалтерські помилки. Запуск
bean-check myfile.beancount
повідомить вас про будь-який дисбаланс, відсутній рахунок або інші проблеми, і не виведе нічого, якщо файл не містить помилок. - bean-format: фор матувальник, який впорядковує вашу облікову книгу, вирівнюючи числа в акуратні стовпці, подібно до запуску форматувальника коду для вихідного коду. Це допомагає підтримувати файл чистим і читабельним.
- bean-query: інтерактивна оболонка або пакетний інструмент для виконання мови запитів Beancount у вашій обліковій книзі. Ви можете використовувати його для створення власних табличних звітів (наприклад,
bean-query myfile.beancount "SELECT account, sum(amount) WHERE ..."
). - bean-report: універсальний генератор звітів (у v2), який може виводити попередньо визначені звіти (баланс, звіт про прибутки та збитки, пробний баланс тощо) на консоль або у файли. Наприклад,
bean-report file.beancount balances
виведе залишки на рахунках. (На практиці, багато з цих текстових звітів були замінені більш приємним представленням Fava.) - bean-web / bean-bake: старіший веб-інтерфейс, який обслуговував звіти на
localhost
або "запікав" їх як статичні HTML-файли. Вони переважно використовувалися до того, як Fava стала популярною; bean-web надавав базовий веб-перегляд тих самих звітів, які міг генерувати bean-report. У Beancount 3 bean-web було видалено (оскільк и Fava тепер є рекомендованим веб-інтерфейсом, що пропонує чудовий досвід). - bean-example: утиліта для генерації прикладу файлу облікової книги (корисна для новачків, щоб побачити шаблон записів Beancount).
- bean-doctor: інструмент налагодження, який може діагностувати проблеми у вашій обліковій книзі або середовищі.
Варто зазначити, що станом на Beancount v3, багато з цих інструментів були винесені з основного проєкту. Основний пакет Beancount був оптимізований, а такі інструменти, як механізм запитів та імпортери, були розділені на окремі пакети (beanquery, beangulp тощо) для полегшення обслуговування. Наприклад, функціональність bean-query тепер надається інструментом beanquery
, який встановлюється окремо. З точки зору користувача, функціональність залишається доступною; її просто було модулізовано. Спільнота Arch Linux відзначила цю зміну під час оновлення Fava: пакет Fava додав залежності від beanquery та beangulp для підтримки Beancount 3.x. Цей модульний підхід також дозволяє іншим членам спільноти робити внесок у ці допоміжні інструменти більш незалежно від циклу випуску Beancount.