Демонстрація спільноти: Реальні налаштування Beancount

Реальні налаштування Beancount

Вступ

Beancount – це універсальна система обліку в текстовому форматі, і її користувачі пристосували її до широкого спектру реальних потреб. У цій демонстрації спільноти ми представляємо анонімізовані приклади того, як різні люди структурують і використовують свої облікові робочі процеси Beancount – від фрілансерів і власників малого бізнесу до ентузіастів особистих фінансів. Ці приклади висвітлюють креативні практики, такі як позначення транзакцій метаданими, автоматизація оновлень книги за допомогою спеціальних скриптів, обробка кількох валют, бюджетування та прогнозування, а також розширення Beancount за допомогою плагінів або інтеграцій (таких як веб-інтерфейс Fava). Мета полягає в тому, щоб надихнути та поінформувати бухгалтерів, розробників і фінансово підкованих користувачів про те, що можливо з гнучкою системою Beancount.

Приклад інтерфейсу Fava: Багато користувачів Beancount покладаються на Fava – веб-інформаційну панель з відкритим кодом – для візуалізації своїх фінансів. Fava може перетворити книгу Beancount на інтерактивні звіти та діаграми. Наприклад, на скріншоті вище показана діаграма "Звіт про прибутки та збитки" у вигляді дерева, яка розбиває доходи та витрати за категоріями, даючи швидкий огляд того, звідки надходять і куди йдуть гроші. Користувачі можуть фільтрувати це представлення за часом, рахунком або тегами, щоб детально вивчити конкретні проєкти або періоди. Такі візуалізації допомагають зробити текстові дані більш доступними, дозволяючи користувачам одразу помічати тенденції та аномалії.

Кожне налаштування Beancount є унікальним, але є загальні теми. Нижче ми розглянемо три сценарії – фрілансер, власник малого бізнесу та досвідчений користувач особистих фінансів – щоб побачити, як вони організовують свої рахунки та використовують функції Beancount. Усі особисті дані були видалені або узагальнені, зосереджуючись лише на техніках і конфігураціях.

Фрілансер: Тегування проєктів і відстеження рахунків-фактур

Наш перший приклад – консультант-фрілансер, який використовує Beancount як основу своїх ділових фінансів. Книга цього фрілансера організована для відстеження доходів і витрат за проєктами та для управління рахунками-фактурами для кількох клієнтів. Вони налаштували спеціальні рахунки для дебіторської заборгованості (A/R) в розділі "Активи" для кожного клієнта, що допомагає відокремити, хто скільки винен. Коли вони завершують проєкт і виставляють рахунок-фактуру клієнту, вони записують транзакцію, дебетуючи рахунок A/R клієнта та кредитуючи рахунок доходів. Наприклад, новий рахунок-фактуру можна записати так:

2025-08-01 * "Проєкт X завершено" ^INV-0001
    Assets:AccountsReceivable:ClientA   5,000 USD
    Income:Consulting                   -5,000 USD

Тут позначення ^INV-0001 є посиланням (вбудована функція метаданих Beancount), яке використовується для позначення цієї транзакції номером рахунку-фактури. Коли клієнт сплачує частину або всю суму цього рахунку-фактури, транзакція оплати містить те саме посилання ^INV-0001, яке зв'язує обидва записи разом. Це зв'язування дозволяє легко розподіляти платежі за конкретними рахунками-фактурами та бачити непогашені залишки. Як пояснив один із членів спільноти, ви можете використовувати такі теги або посилання для позначення часткових платежів – наприклад, платіж у розмірі 20 доларів США проти рахунку-фактури на 30 доларів США – як у записі рахунку-фактури, так і в записі платежу. За допомогою запиту до книги за цим посиланням на рахунок-фактуру фрілансер може миттєво побачити, скільки рахунку-фактури було сплачено і що залишається відкритим.

На додаток до посилань, фрілансер активно використовує теги для категоризації. Теги в Beancount – це мітки з префіксом #, які можуть позначати транзакції для подальшої фільтрації. Цей користувач позначає кожну витрату, яку можна виставити клієнту, кодом проєкту, наприклад #ProjectX, і позначає витрати, що підлягають відшкодуванню, тегом #Reimbursable. Наприклад, якщо вони купують авіаквитки для клієнтського проєкту, запис про витрати може містити #ProjectX #Reimbursable. Ця практика дозволяє створювати звіти за проєктом або клієнтом шляхом фільтрації за тегами. Після проєкту фрілансер може запустити запит, щоб перерахувати всі витрати #Reimbursable для цього проєкту та переконатися, що вони виставили рахунок-фактуру клієнту за кожну з них. Один користувач Beancount зазначив, що позначення витрат на робочі поїздки допомогло виявити будь-які витрати, які не були відшкодовані – в ідеалі витрати на робочу поїздку мають дорівнювати 0 доларів США, коли всі відшкодування від клієнта отримано. Це підкреслює, як тегування в поєднанні з можливостями запитів Beancount забезпечує додатковий рівень контролю для фрілансерів, які керують витратами, що підлягають виставленню рахунків.

Щоб керувати статусом непогашених платежів, наш фрілансер використовує спеціальну конвенцію для непогашеної дебіторської заборгованості. Вони застосовують тег #UNRESOLVED до будь-якої транзакції рахунку-фактури, яка ще не була повністю сплачена. Beancount (і Fava) не застосовує цей тег, але це загальноприйнятий шаблон у спільноті для позначення транзакцій, які очікують на врегулювання. Наприклад, доки Client A не сплатить усі 5 000 доларів США, транзакція рахунку-фактури вище включатиме #UNRESOLVED. Фільтруючи за цим тегом, фрілансер може будь-коли перерахувати всі відкриті рахунки-фактури. Після отримання та застосування платежу (введено відповідну транзакцію A/R) вони видаляють або ігнорують тег #UNRESOLVED, і рахунок дебіторської заборгованості для цього клієнта збалансується до нуля. Ця система гарантує, що жоден рахунок-фактура не "провадиться". Це, по суті, звіт про старіння, зроблений у текстовому форматі – якщо дебіторська заборгованість залишається ненульовою та позначеною як нерозв'язана, вона потребує уваги.

Оскільки фрілансери часто мають справу з кількома способами оплати, а іноді й з кількома валютами, налаштування Beancount без проблем враховує це. У нашому прикладі консультант може виставляти рахунки деяким клієнтам у доларах США, а іншим – в євро. Обробка мультивалютності в Beancount є простою: будь-який рахунок може містити кілька товарів (валюти розглядаються як товари). Фрілансер може або зберігати окремі субрахунки для кожної валюти (наприклад, Assets:AccountsReceivable:ClientA:EUR проти ...:USD), або просто розміщувати транзакції у відповідній валюті на одному рахунку. Beancount автоматично відстежуватиме залишки за валютою. Один користувач підкреслив, як приємно, що "Beancount може відстежувати кількості в будь-якій валюті, будь то долари США чи тікер акцій", все в одній книзі. Наш фрілансер користується цим, записуючи обмінні курси за допомогою директив price щоразу, коли їм потрібно конвертувати валюти для звітування. Вони можуть створити звіт про доходи, конвертований у валюту їхньої країни, після того, як вони ввели періодичні обмінні курси або ринкові ціни.

Нарешті, цей фрілансер інтегрує свою книгу Beancount з практичними інструментами для оптимізації свого робочого процесу. Наприклад, вони прикріплюють PDF-копії кожного рахунку-фактури до книги за допомогою метаданих документа. Типовий запис про оплату рахунку-фактури може виглядати так:

2025-08-30 * "ClientA" "Оплата за INV-0001" ^INV-0001
    Assets:Bank:Checking       5,000 USD
    Assets:AccountsReceivable:ClientA  -5,000 USD
    document: "Invoices/ClientA/INV-0001.pdf"

Директива або метадані document Beancount дозволяють пов'язувати файли із записами, і Fava показуватиме гіперпосилання для цих вкладень. Це означає, що фрілансер (або їхній бухгалтер) може натиснути безпосередньо зі звіту книги, щоб переглянути оригінальний PDF-файл рахунку-фактури, забезпечуючи легкий доступ до резервної документації. Фрілансер також використовує звіти Fava для моніторингу свого бізнесу: фільтруючи звіт про прибутки та збитки або баланс за клієнтом, вона може бачити прибутковість на клієнта та перевіряти, чи всі проєкти оплачено. Підсумовуючи, система Beancount цього фрілансера демонструє широке використання тегування та зв'язування для управління обліком на основі проєкту. Вона перетворює текстову книгу на надійний інструмент обліку фрілансера з чіткою видимістю витрат проєкту, мультивалютного доходу та статусів рахунків-фактур.

Ключові практики в налаштуванні фрілансера: Використання тегів для групування транзакцій за проєктом або метою, зв'язування рахунків-фактур і платежів за допомогою унікальних ідентифікаторів, позначення непогашеної дебіторської заборгованості тегом #UNRESOLVED, прикріплення документів рахунків-фактур до записів книги для довідки та використання підтримки мультивалютності Beancount для виставлення рахунків міжнародним клієнтам без проблем. Усе це досягається за допомогою простих текстових записів плюс декілька допоміжних інструментів, що демонструє потужність метаданих у Beancount.

Малий бізнес: Автоматизація та мультивалютний облік

Далі ми розглянемо власника малого бізнесу – зокрема, засновника стартапу – який використовував Beancount для ведення бухгалтерського обліку компанії. Малі підприємства мають потреби, подібні до фрілансерів (рахунки-фактури, витрати, мультивалютність), але часто у більшому масштабі та з більшим акцентом на автоматизації, послідовності та співпраці. У цьому випадку засновник був технічно підкованим і створив високоавтоматизований робочий процес Beancount, щоб мінімізувати ручне ведення бухгалтерського обліку. Після оцінки традиційного бухгалтерського програмного забезпечення, такого як QuickBooks, вони обрали текстовий підхід Beancount, щоб зберегти повний контроль над даними. За кілька років вони ітеративно розробили спеціальні інструменти для досягнення 95% автоматизованого процесу ведення бухгалтерського обліку.

Автоматизований імпорт і звірка: Одним із перших завдань було імпортування транзакцій з різних джерел (банківські рахунки, кредитні картки, платіжні процесори) до книги. Замість того, щоб вводити кожну транзакцію, цей користувач налаштував скрипти імпорту для отримання та перетворення даних у формат Beancount. Вони написали спеціальні імпортери Python для CSV або API-формату кожної фінансової установи, щоб за допомогою однієї команди вони могли отримати нові транзакції та додати їх до книги. Наприклад, використовуючи фреймворк bean-extract Beancount, засновник може запустити скрипт, який сканує папку завантажень на наявність нових виписок і виводить їх у вигляді записів Beancount. Інший користувач, Рід Льюїс, описав подібну настройку, де він має окремі скрипти імпортеру для кожного банку і може викликати їх за допомогою простої команди (використовуючи Justfile) для оновлення своєї книги. Наш власник малого бізнесу робить те саме – усі банківські транзакції, операції з кредитними картками та навіть транзакції PayPal або Stripe автоматично отримуються та додаються до бухгалтерських книг, класифіковані за відповідними рахунками.

Щоб забезпечити цілісність даних навіть після автоматичного додавання цих записів, вони також використовують інструменти перевірки та плагіни Beancount. Наприклад, плагін beancount.plugins.noduplicates увімкнено, щоб запобігти випадковому повторному імпорту однієї й тієї самої транзакції, а beancount.plugins.nounused позначає будь-які рахунки, які не мають записів (корисно для очищення застарілих рахунків). Засновник також використовує форматер (наприклад, bean-format або інструмент спільноти beancount-black), щоб підтримувати постійний стиль файлу книги. Це важливо, оскільки з великою кількістю автоматизованих змін мати єдиний стиль полегшує диференціацію та аудит. Фактично, засновник зберігає книгу в репозиторії Git, розглядаючи оновлення книги як зміни коду. Кожна нова партія імпортованих транзакцій стає комітом Git, і вони можуть переглядати відмінності, щоб побачити, що змінилося. На одному скріншоті вони показують історію Git, де транзакція кредитної картки для "Costco" переходить із очікуваного стану до очищеного в книзі, і все це без ручного втручання. Контроль версій забезпечує контрольний слід: вони можуть точно бачити, коли транзакцію було додано або змінено, і навіть скасовувати зміни, якщо щось було імпортовано неправильно. Це чудовий приклад впровадження кращих практик розробки програмного забезпечення (таких як контроль вихідного коду) в облікові записи.

Мультивалютні та міжнародні транзакції: Малі підприємства часто здійснюють транзакції в кількох валютах – наприклад, стартап може мати витрати в доларах США, але також отримувати платежі в євро або мати банківський рахунок у фунтах стерлінгів. Наша компанія-учасник використовує мультивалютні функції Beancount, щоб об'єднати все це в одній книзі. Вони відкрили окремі рахунки для кожної валюти (наприклад, Assets:Bank:Checking:USD і Assets:Bank:Checking:EUR), що є одним із поширених підходів. Однак, навіть якщо різні валюти мають спільний рахунок, Beancount відстежуватиме баланс кожної валюти окремо та вимагатиме збалансування транзакцій за валютою. Засновник часто запускає звіти про оцінку, щоб побачити загальний баланс компанії, конвертований у базову валюту. Оскільки Beancount підтримує пошук цін, він налаштував щоденні цінові канали для обмінних курсів валют (і цін на акції для будь-яких інвестицій) за допомогою інструменту bean-price або плагіна. Результат полягає в тому, що в будь-який час він може створити баланс, скажімо, в доларах США, який включає рахунок в євро, перерахований за останнім курсом. Члени спільноти зазначають, що обробка кількох валют в обліку в стилі книги є простою – ви просто додаєте транзакції у вказаній валюті та записуєте обмінні курси за потреби. Наприклад, один користувач поділився прикладом конвертації доларів США в євро в CAD через проміжні рахунки як спосіб управління конвертацією валют у Beancount. У нашому випадку малий бізнес не обов'язково конвертує валюти в транзакціях (вони зберігають їх у місцевій валюті), але використовує звіти для консолідації. Ця гнучкість була вирішальною, оскільки стартап розширився в усьому світі.

Спеціальні скрипти та розширення: Не все, що потрібно було засновнику, було доступне "з коробки", тому вони розширили Beancount за допомогою спеціальних плагінів. Згодом вони написали бібліотеку парсерів, інструмент форматування та механізм імпорту транзакцій на основі правил, випустивши багато з них як пакети з відкритим кодом. Наприклад, вони створили механізм імпорту на основі правил, який використовує конфігурацію YAML для автоматичної категоризації транзакцій. Фрагмент цієї конфігурації показує, як конкретні одержувачі або описи (наприклад, "Comcast" або "PG&E") зіставляються з певними рахунками витрат і розповідями, так що коли вони з'являються в банківській виписці, правильний запис Beancount генерується без ручного редагування. Це, по суті, спеціальна автоматизація для застосування правил бухгалтерського обліку (для комунальних послуг, підписок тощо) на льоту. Інший плагін гарантує, що книга завжди залишається збалансованою та відформатованою. Усі ці інструменти працюють як частина робочого процесу засновника щоразу, коли надходять нові дані. Результатом є книга, яка "оновлюється сама" з мінімальним втручанням, що, за словами засновника, приносить йому "чисту радість" як розробнику, одержимому автоматизацією.

Безпека та доступність також були важливими. Засновник хотів, щоб його фінансова команда (і навіть його дружина, яка виконувала роль наглядача) могли легко переглядати бухгалтерські книги. Для цього він налаштував приватне розгортання Fava в хмарі. Щоразу, коли він надсилає новий коміт книги до приватного репозиторію Git, конвеєр CI (за допомогою GitHub Actions і AWS Elastic Beanstalk) розгортає оновлений екземпляр Fava. Веб-інтерфейс захищений паролем (за допомогою проксі-сервера Nginx з базовою автентифікацією), тому його можуть бачити лише авторизовані люди. Таким чином, останні фінансові звіти завжди доступні через веб-панель, без необхідності встановлювати щось локально. Діаграма архітектури нижче ілюструє цю настройку: файл Beancount і необхідна конфігурація об'єднані в образ Docker разом з Fava та обслуговуються на AWS, а Cloudflare знаходиться попереду для забезпечення безпеки.

Автоматизація Beancount у хмарі: Ця діаграма показує конвеєр розгортання для книги Beancount + Fava. Користувач оновлює файл книги локально та надсилає до Git; контейнер Docker (включаючи Fava та Nginx для автентифікації) створюється та розгортається на сервері AWS Beanstalk, а Cloudflare діє як проксі-сервер. Результатом є безпечний веб-портал, де дані про фінанси малого бізнесу можуть бути доступні з будь-якого місця (власником або командою) в режимі реального часу. Ця розширена настройка демонструє, як малий бізнес може інтегрувати Beancount із сучасними хмарними інструментами для досягнення зручності, не відмовляючись від права власності на дані.

У повсякденному використанні основна увага власника малого бізнесу зосереджена на обробці винятків, а не на введенні даних. Щомісяця він коротко переглядає автоматично імпортовані транзакції (використовуючи Git diffs або журнал переглядів Fava), щоб виявити будь-які некласифіковані або неправильні записи. Він також використовує підтвердження балансу Beancount для узгодження рахунків. Наприклад, після введення всіх транзакцій за червень він може додати перевірку балансу, щоб підтвердити, що кінцевий баланс банківського рахунку відповідає виписці; якщо ні, Beancount видасть помилку, вказуючи на те, що щось відсутнє або введено неправильно. Це гарантує, що книги залишаються точними.

Ключові практики в налаштуванні малого бізнесу: Широка автоматизація за допомогою спеціальних імпортерів і скриптів (що робить книгу "на 95% автоматичною"), використання контролю версій для аудиторських слідів і співпраці, мультивалютний облік із ціновими каналами для оцінки та розгортання Fava для легкого та спільного доступу до фінансових звітів. Сценарій малого бізнесу показує, як далеко можна зайти з Beancount з інженерними зусиллями – перетворюючи бухгалтерський облік на значною мірою автоматизований конвеєр, зберігаючи при цьому прозорість і гнучкість. Навіть якщо ви не програміст, багатьох із цих переваг можна досягти, використовуючи плагіни спільноти (для форматування, виявлення дублікатів тощо) та прийнявши текстовий робочий процес, який заохочує часті перевірки та резервне копіювання.

Ентузіаст особистих фінансів: Бюджетування та спеціальний аналіз

Наш останній приклад – ентузіаст особистих фінансів – людина, яка використовує Beancount для управління фінансами домогосподарства та інвестиціями з високим рівнем деталізації. Цей користувач ставиться до своїх особистих фінансів з ретельністю бухгалтера та цікавістю аналітика даних. Результатом є книга Beancount, яка не тільки відстежує кожну копійку, але й служить основою для бюджетування, прогнозування та аналітичних експериментів.

Організація особистої книги: Багато людей починають з одного файлу Beancount для всіх своїх рахунків, і цей ентузіаст не відрізняється. Вони підтримують одну головну книгу (наприклад, main.beancount), яка містить усі рахунки (банківські рахунки, кредитні картки, позики, інвестиційні портфелі тощо) та транзакції. Згодом вони запровадили деяку структуру, розділивши розділи – наприклад, вони мають файл для відкриття/закриття рахунків та окремі файли для річних транзакцій – які включені до головного файлу. Ця модульна організація полегшує навігацію роками даних (можна архівувати старі роки в окремих файлах), залишаючись логічно однією книгою. Інший особистий користувач на форумі спільноти описав подібний макет: головний файл, який включає інші за категоріями (наприклад, Income.beancount, Expenses.beancount, Investments.beancount). Наш ентузіаст поки що робить це просто: один файл, синхронізований на різних пристроях.

Говорячи про синхронізацію, оскільки це особисті фінанси, цей користувач хоче фіксувати транзакції, де б вони не були. Вони використовують мобільний додаток під назвою Beancount Mobile, щоб швидко додавати записи в дорозі (наприклад, реєструвати витрати готівкою прямо в магазині). Файл книги спільно використовується через хмарну синхронізацію (Syncthing, у цьому випадку), щоб їхній телефон, ноутбук і VPS (сервер) мали останню копію. На комп'ютері вони віддають перевагу використанню Emacs з beancount-mode для зручного редагування з підсвічуванням синтаксису. Ця настройка гарантує, що незалежно від того, чи перебувають вони за столом, чи в дорозі, вони можуть негайно записувати транзакції та уникати забування будь-чого. Це чудовий приклад адаптації технічних інструментів для особистої зручності – ефективно створення альтернативи комерційним додаткам для бюджетування, які розміщуються самостійно.

Тегування та метадані для детального відстеження: Цей користувач використовує теги, щоб додати другий вимір до своїх даних, окрім плану рахунків. Для звичайних категорій бюджетування достатньо рахунків (у них є рахунки, такі як Expenses:Groceries, Expenses:Rent тощо), але для наскрізних тем, таких як події або цілі, вони використовують теги. Наприклад, вони позначають усі транзакції, пов'язані з їхнім проєктом ремонту будинку, тегом #HomeReno, незалежно від того, чи купують вони пиломатеріали в господарському магазині (витрати), чи отримують знижку від виробника (дохід). Таким чином, вони можуть легко створити звіт про загальну вартість проєкту без того, щоб ці витрати були ізольовані на різних рахунках. Один користувач Reddit продемонстрував цей підхід, позначивши витрати, такі як #garage-improvement або #lighting-improvement, для проєктів дому, що робить тривіальним фільтрування та підсумовування їх за допомогою запитів Beancount. Наш ентузіаст робить те саме для відпусток (#ItalyTrip2025), великих покупок і разових подій.

Метадані (пари ключ-значення в транзакціях) також використовуються для деяких конкретних цілей. Наприклад, вони додають метадані location: ... до великих витрат, щоб відстежувати, де вони витратили гроші, або note: ... для додаткового контексту, окрім одержувача та розповіді. У кількох випадках вони навіть створили спеціальні поля метаданих, щоб допомогти з прогнозуванням. Одним із прикладів є додавання budget: X і frequency: monthly до певних періодичних витрат – ідея, натхненна обговоренням у списку розсилки Beancount, де користувач зберігав бюджетні прогнози в метаданих для кожної витрати. Ці поля метаданих не впливають на ядро Beancount, але ентузіаст написав невеликий скрипт Python, який зчитує їх і порівнює фактичні витрати з запланованим бюджетом. Це альтернатива використанню вбудованих бюджетів Fava (описаних нижче), що показує, як метадані можна підлаштувати під волю користувача. Як зазначив творець Beancount, метадані "існують лише для вас [щоб використовувати в спеціальних скриптах] – Beancount їх аналізує, але ігнорує" сам по собі. Коротше кажучи, цей користувач не боїться розширювати книгу додатковою інформацією, щоб допомогти своєму особистому аналізу.

Бюджетування за допомогою Beancount: Одною з головних цілей цього користувача є дотримання місячного бюджету. Раніше вони використовували додаток для бюджетування (YNAB) і хотіли відтворити деякі з його концепцій конвертного бюджетування. Є кілька способів бюджетування в Beancount, але найпростіший – використання бюджетних директив Fava. Наш ентузіаст додає записи budget до книги таким чином:

2025-01-01 custom "budget" Expenses:Groceries   "monthly" 500 USD
2025-01-01 custom "budget" Expenses:DiningOut   "monthly" 200 USD
2025-01-01 custom "budget" Expenses:Travel      "yearly" 3000 USD

Кожен рядок встановлює бюджет для рахунку (категорії) протягом певного періоду. Потім Fava відображає смуги бюджету та фактичних даних у веб-інтерфейсі, дозволяючи користувачеві бачити, наприклад, що вони витратили 480 доларів США на продукти цього місяця з 500 запланованих, і, можливо, 220 на харчування поза домом (перевищення бюджету). Ентузіаст регулярно перевіряє звіти Fava "Звіт про прибутки та збитки" та "Витрати", які показують як щомісячні підсумки, так і бюджетні цілі. Fava зручно згортає щоденні/щотижневі бюджети у відповідні часові проміжки. Використовуючи для цього інтерфейс користувача Fava, користувачеві не потрібна окрема таблиця для бюджетування; все інтегровано. (Вони також експериментували з більш автоматизованою "конвертною" системою, переміщуючи кошти на фіктивні рахунки на початку кожного місяця, як запропоновано на форумах, але вважали спеціальні бюджетні директиви простішими в обслуговуванні.)

Для прогнозування, крім бюджетів, вони стежать за майбутніми рахунками. Деякі члени спільноти створили плагіни для створення майбутніх транзакцій для підписок або графіків амортизації позик, але цей користувач обрав простіший підхід: вони підтримують окремий розділ книги з майбутніми транзакціями для відо