پرش به محتوای اصلی

افزونه‌های بومی ضروری Beancount که باید بشناسید

· زمان مطالعه 11 دقیقه
Mike Thrift
Mike Thrift
Marketing Manager

قدرت بین‌کانت (Beancount) تنها در فرمت متن ساده آن نیست، بلکه در قابلیت گسترش آن از طریق پلاگین‌ها نهفته است. پلاگین‌های بومی، ماژول‌های داخلی هستند که عملکردهای بین‌کانت را تقویت کرده، وظایف خسته‌کننده را خودکار می‌کنند و بهترین شیوه‌های حسابداری را اعمال می‌نمایند. در این راهنمای جامع، تمامی پلاگین‌های بومی موجود در بین‌کانت و نحوه استفاده موثر از آن‌ها را بررسی خواهیم کرد.

پلاگین‌های بین‌کانت چیستند؟

پلاگین‌های بین‌کانت ماژول‌های پایتونی هستند که ورودی‌های دفتر کل شما را برای افزودن قابلیت‌های خودکارسازی، اعتبارسنجی یا تبدیل، پردازش می‌کنند. آن‌ها در مرحله بارگذاری فایل دفتر کل اجرا می‌شوند و می‌توانند:

  • وظایف تکراری را خودکار کنند (مثلاً ایجاد دستورات تعریف حساب)
  • یکپارچگی داده‌ها را اعتبارسنجی کنند (مثلاً بررسی تراکنش‌های تکراری)
  • ورودی‌ها را تبدیل کنند (مثلاً تولید قیمت‌ها از روی تراکنش‌ها)
  • قوانین حسابداری را اعمال کنند (مثلاً وجود تنها یک نوع کالا/ارز در هر حساب)

نحوه استفاده از پلاگین‌ها

برای فعال‌سازی یک پلاگین در فایل بین‌کانت خود، دستور plugin را در بالای دفتر کل اضافه کنید:

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"

برخی از پلاگین‌ها گزینه‌های پیکربندی را نیز می‌پذیرند:

plugin "beancount.plugins.check_commodity" "USD,EUR,CAD"

دسته‌بندی پلاگین‌های بومی

پلاگین‌های بومی بین‌کانت به چهار دسته اصلی تقسیم می‌شوند:

۱. پلاگین‌های خودکارسازی

۲. پلاگین‌های اعتبارسنجی

۳. پلاگین‌های تبدیل

۴. متا-پلاگین‌ها


۱. پلاگین‌های خودکارسازی

این پلاگین‌ها وظایف تکراری دفترداری را خودکار می‌کنند تا در وقت شما صرفه‌جویی شده و خطاهای انسانی کاهش یابد.

auto_accounts - تعریف خودکار حساب‌ها

عملکرد: به طور خودکار دستورات Open را برای حساب‌هایی که در تراکنش‌ها ظاهر شده‌اند اما به صراحت تعریف نشده‌اند، درج می‌کند.

دلیل استفاده: نیاز به تعریف دستی تک‌تک حساب‌ها قبل از استفاده را از بین می‌برد. برای شروع سریع یا کاربرانی که ترجیح می‌دهند کدهای تکراری (boilerplate) کمتری داشته باشند، عالی است.

مثال:

plugin "beancount.plugins.auto_accounts"

2026-01-01 * "Coffee shop"
Expenses:Food:Coffee 4.50 USD
Assets:Cash -4.50 USD

بدون این پلاگین، باید این موارد را به صورت دستی اضافه می‌کردید:

2025-12-01 open Expenses:Food:Coffee
2025-12-01 open Assets:Cash

زمان استفاده: ایده‌آل برای مبتدیان یا کسانی که دفتر کلی خلوت‌تر می‌خواهند. با این حال، تعریف صریح حساب‌ها می‌تواند به شناسایی غلط‌های املایی کمک کند.


close_tree - بستن خودکار سلسله‌مراتب حساب‌ها

عملکرد: وقتی یک حساب والد را می‌بندید، این پلاگین به طور خودکار تمام حساب‌های زیرمجموعه آن را می‌بندد.

دلیل استفاده: حفظ ثبات در سلسله‌مراتب حساب‌های شما. اگر Assets:Investments را ببندید، تمام زیرحساب‌ها مانند Assets:Investments:Stocks و Assets:Investments:Bonds به طور خودکار بسته می‌شوند.

مثال:

plugin "beancount.plugins.close_tree"

2025-06-30 close Assets:Investments

; این موارد به طور خودکار بسته خواهند شد:
; Assets:Investments:Stocks
; Assets:Investments:Bonds
; Assets:Investments:RealEstate

زمان استفاده: هنگام بازسازی ساختار سلسله‌مراتبی حساب‌ها یا بستن کل دسته‌بندی‌های حساب.


implicit_prices - تولید خودکار ورودی‌های قیمت

عملکرد: دایرکتیوهای Price را از ثبت‌های تراکنشی که شامل بهای تمام شده (@) یا قیمت (@@) هستند، استخراج و ایجاد می‌کند.

دلیل استفاده: پایگاه داده قیمت‌های شما را به طور خودکار از روی تراکنش‌ها پر می‌کند و گزارش‌دهی دقیق از ارزش بازار را بدون نیاز به وارد کردن دستی قیمت‌ها ممکن می‌سازد.

مثال:

plugin "beancount.plugins.implicit_prices"

2026-01-02 * "Buy AAPL shares"
Assets:Investments:Stocks 10 AAPL @ 150.00 USD
Assets:Cash -1500.00 USD

این کار به طور خودکار تولید می‌کند:

2026-01-02 price AAPL  150.00 USD

زمان استفاده: برای ردیابی سرمایه‌گذاری‌ها و حسابداری چند ارزی که در آن خواهان تاریخچه قیمت خودکار هستید، ضروری است.


۲. پلاگین‌های اعتبارسنجی

این پلاگین‌ها یکپارچگی داده‌ها و بهترین شیوه‌های حسابداری را اعمال کرده و خطاها را قبل از تبدیل شدن به مشکل، شناسایی می‌کنند.

noduplicates - تشخیص تراکنش‌های تکراری

عملکرد: با محاسبه و مقایسه هش‌های داده‌های تراکنش، بررسی می‌کند که هیچ دو تراکنشی یکسان نباشند.

دلیل استفاده: از ورود تصادفی تراکنش‌های تکراری جلوگیری می‌کند، به خصوص زمانی که تراکنش‌ها را از منابع مختلف وارد (Import) می‌کنید.

مثال:

plugin "beancount.plugins.noduplicates"

2026-01-02 * "Rent payment"
Expenses:Rent 1200.00 USD
Assets:Checking -1200.00 USD

; این مورد باعث ایجاد خطا می‌شود:
2026-01-02 * "Rent payment"
Expenses:Rent 1200.00 USD
Assets:Checking -1200.00 USD

زمان استفاده: همیشه توصیه می‌شود، به خصوص اگر از صورت‌حساب‌های بانکی تراکنش‌ها را وارد می‌کنید یا از چندین منبع داده استفاده می‌نمایید.


check_commodity - اعتبارسنجی تعریف کالا/ارز

عملکرد: اطمینان حاصل می‌کند که تمام کالاها یا ارزهای استفاده شده در دفتر کل شما، دارای دایرکتیوهای Commodity متناظر باشند.

دلیل استفاده: تعریف صریح کالاها را اجباری می‌کند که به شما در حفظ لیستی تمیز از دارایی‌ها و ارزها کمک می‌نماید.

مثال:

plugin "beancount.plugins.check_commodity"

2015-01-01 commodity USD
2020-01-01 commodity AAPL

; این مورد بدون تعریف کالا باعث ایجاد خطا می‌شود:
2026-01-02 * "Buy Bitcoin"
Assets:Crypto 0.5 BTC @ 45000 USD
Assets:Cash -22500.00 USD

زمان استفاده: برای حفظ ردیابی دقیق کالاها و جلوگیری از غلط‌های املایی در نمادهای معاملاتی توصیه می‌شود.


check_average_cost - اعتبارسنجی مبنای هزینه

عملکرد: بررسی می‌کند که مبنای هزینه (cost basis) در تراکنش‌ها، به‌ویژه هنگام استفاده از ثبت با بهای تمام‌شده میانگین (average-cost booking)، به‌درستی حفظ شده باشد.

چرا استفاده کنیم: اطمینان حاصل می‌کند که حسابداری بهای تمام‌شده شما برای گزارش‌دهی مالیاتی و محاسبات سود سرمایه‌ای دقیق باقی می‌ماند.

زمان استفاده: برای سبدهای سرمایه‌گذاری و هر سناریویی که ردیابی دقیق هزینه در آن اهمیت دارد، حیاتی است.


check_closing - اعتبارسنجی بستن تراز

عملکرد: متادیتای closing را به بررسی‌های تراز گسترش می‌دهد و اطمینان حاصل می‌کند که پوزیشن‌ها پس از بستن معاملات صفر شده‌اند.

چرا استفاده کنیم: تایید می‌کند که وقتی کل یک پوزیشن را می‌فروشید، مانده واقعاً صفر است (هیچ سهم کسری باقی نمانده است).

مثال:

plugin "beancount.plugins.check_closing"

2026-01-02 * "Close entire AAPL position" #closing
Assets:Investments:Stocks -100 AAPL {150.00 USD}
Assets:Cash 15000.00 USD
Income:Investments:Gains -500.00 USD

تگ #closing به پلاگین می‌گوید که بررسی کند مانده پوزیشن AAPL شما پس از این تراکنش صفر شده باشد.

زمان استفاده: هنگام فروش کامل پوزیشن‌ها برای اطمینان از اینکه چیزی باقی نمانده است.


coherent_cost - بررسی سازگاری ارز/هزینه

عملکرد: بررسی می‌کند که ارزها به‌صورت متناقض (هم با حاشیه‌نویسی هزینه و هم بدون آن) استفاده نشده باشند.

چرا استفاده کنیم: از ترکیب ارزهای خام (مانند 100 USD) با ارزهای دارای هزینه (مانند 100 USD {1.2 CAD}) که می‌تواند باعث بروز خطا در حسابداری شود، جلوگیری می‌کند.

زمان استفاده: برای دفاتر چندارزی جهت حفظ ثبات و سازگاری توصیه می‌شود.


leafonly - اجبار به استفاده از حساب‌های سطح آخر (برگ)

عملکرد: اطمینان حاصل می‌کند که فقط حساب‌های برگ (حساب‌هایی که زیرمجموعه ندارند) ثبتِ آرتیکل دریافت می‌کنند.

چرا استفاده کنیم: یک سلسله‌مراتب تمیز برای حساب‌ها ایجاد می‌کند که در آن حساب‌های خلاصه مانند Expenses:Food ثبت مستقیم ندارند و فقط زیرمجموعه‌های آن‌ها مانند Expenses:Food:Groceries و Expenses:Food:Restaurants دارای ثبت هستند.

مثال:

plugin "beancount.plugins.leafonly"

; This would trigger an error:
2026-01-02 * "Grocery shopping"
Expenses:Food 50.00 USD ; Error: Should post to a leaf account
Assets:Cash -50.00 USD

; Correct way:
2026-01-02 * "Grocery shopping"
Expenses:Food:Groceries 50.00 USD ; Correct: Posting to leaf account
Assets:Cash -50.00 USD

زمان استفاده: زمانی که می‌خواهید یک حسابداری سلسله‌مراتبی دقیق با دسته‌بندی شفاف داشته باشید.


nounused - شناسایی حساب‌های استفاده‌نشده

عملکرد: حساب‌هایی را که افتتاح شده‌اند اما هرگز در هیچ تراکنشی استفاده نشده‌اند، شناسایی می‌کند.

چرا استفاده کنیم: به شما کمک می‌کند تعاریف حساب‌های خود را پاک‌سازی کرده و غلط‌های املایی احتمالی یا حساب‌های رها شده را شناسایی کنید.

زمان استفاده: به‌صورت دوره‌ای، برای بازرسی و تمیز کردن ساختار حساب‌های خود.


onecommodity - یک کالا برای هر حساب

عملکرد: اجبار می‌کند که هر حساب فقط یک نوع کالا (ارز یا دارایی) را نگه دارد.

چرا استفاده کنیم: از ترکیب دارایی‌های مختلف در یک حساب جلوگیری می‌کند که به‌طور کلی یکی از بهترین شیوه‌های حسابداری است.

مثال:

plugin "beancount.plugins.onecommodity"

2026-01-02 * "Buy stocks"
Assets:Investments 10 AAPL @ 150 USD
Assets:Cash -1500.00 USD

; This would trigger an error:
2026-01-03 * "Buy more stocks"
Assets:Investments 5 GOOGL @ 140 USD ; Error: Different commodity
Assets:Cash -700.00 USD

زمان استفاده: زمانی که تفکیک دقیق حساب‌ها را ترجیح می‌دهید (یک حساب برای هر سهم/دارایی).


sellgains - اعتبارسنجی سود سرمایه‌ای

عملکرد: سود سرمایه‌ای اظهار شده را با سودهای محاسبه شده از فروش دسته‌ها (lot sales) تطبیق می‌دهد تا از صحت محاسبات سود/زیان شما اطمینان حاصل کند.

چرا استفاده کنیم: خطاهای محاسبات دستی سود سرمایه‌ای را شناسایی می‌کند که برای گزارش‌دهی دقیق مالیاتی حیاتی است.

مثال:

plugin "beancount.plugins.sellgains"

2026-01-02 * "Sell AAPL shares"
Assets:Investments:Stocks -10 AAPL {140.00 USD}
Assets:Cash 1500.00 USD
Income:Investments:Gains -100.00 USD ; Plugin validates this is correct

پلاگین تایید می‌کند: عواید فروش (1500) - مبنای هزینه (1400) = سود (100)

زمان استفاده: برای هر کسی که سهام، ارز دیجیتال یا سایر دارایی‌هایی را معامله می‌کند که سود سرمایه‌ای در آن‌ها اهمیت دارد، ضروری است.


unique_prices - بررسی یکتایی قیمت

عملکرد: اطمینان حاصل می‌کند که برای هر کالا در هر تاریخ، فقط یک ورودی قیمت وجود داشته باشد.

چرا استفاده کنیم: از داده‌های قیمتی متناقض که می‌تواند منجر به ارزش‌گذاری‌های نادرست شود، جلوگیری می‌کند.

زمان استفاده: هنگام وارد کردن دستی قیمت‌ها یا وارد کردن داده‌ها از منابع قیمتی متعدد توصیه می‌شود.


۳. پلاگین‌های تغییر شکل (Transformation Plugins)

این پلاگین‌ها داده‌های دفتر کل شما را به روش‌های مفیدی تغییر داده یا بهبود می‌بخشند.

currency_accounts - حساب‌های مبادلات ارزی

عملکرد: حساب‌های مبادلات ارزی را برای ردیابی صریح تبدیل‌های فارکس پیاده‌سازی می‌کند.

چرا استفاده کنیم: ردیابی دقیق تراکنش‌های تبدیل ارز را فراهم می‌کند که برای استانداردهای حسابداری خاصی که به آن نیاز دارند، مفید است.

زمان استفاده: زمانی که نیاز دارید سود/زیان فارکس را به‌طور جداگانه ردیابی کنید یا الزامات حسابداری خاصی را برآورده سازید.


commodity_attr - اعتبارسنجی ویژگی‌های کالا

عملکرد: تایید می‌کند که دستورالعمل‌های کالا (commodity directives) دارای ویژگی‌های مورد نیاز (مانند export ،name و غیره) باشند.

چرا استفاده کنیم: اطمینان حاصل می‌کند که متادیتای کالای شما کامل و سازگار است.

زمان استفاده: زمانی که متادیتای دقیق کالاها را برای اهداف گزارش‌دهی یا خروجی گرفتن (export) نگهداری می‌کنید.


۴. فرا-پلاگین‌ها (Meta-Plugins)

این پلاگین‌ها مجموعه‌ای از پلاگین‌های دیگر هستند که برای راحتی بیشتر در یک‌جا جمع شده‌اند.

auto - تمام پلاگین‌های خودکار

عملکرد: مجموعه‌ای از پلاگین‌های «آسان‌گیر» یا خودکار را در یک دستور فعال می‌کند.

زمان استفاده: راه‌اندازی سریع برای کاربرانی که خواهان حداکثر خودکارسازی با حداقل پیکربندی هستند.


pedantic - تمام پلاگین‌های اعتبارسنجی

عملکرد: تمام پلاگین‌های اعتبارسنجی سخت‌گیرانه را به طور هم‌زمان فعال می‌کند.

چرا از آن استفاده کنیم: حداکثر یکپارچگی داده‌ها و دقت حسابداری را اعمال می‌کند. برای دفترهای مالی نهایی (Production) یا زمانی که دقت بالاترین اولویت را دارد، عالی است.

مثال:

plugin "beancount.plugins.pedantic"

; این معادل فعال‌سازی موارد زیر است:
; - check_commodity
; - check_average_cost
; - coherent_cost
; - leafonly
; - noduplicates
; - nounused
; - onecommodity
; - sellgains
; - unique_prices

زمان استفاده: برای دفترهای مالی نهایی که در آن خواهان حداکثر اعتبارسنجی هستید و تمایل دارید استانداردهای حسابداری سخت‌گیرانه‌تری را رعایت کنید.


پیکربندی‌های پیشنهادی پلاگین

برای مبتدیان

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.noduplicates"
plugin "beancount.plugins.implicit_prices"

این مجموعه حداقلی، ضمن جلوگیری از خطاهای رایج، اتوماسیون لازم را فراهم می‌کند.

برای سرمایه‌گذاران

plugin "beancount.plugins.auto_accounts"
plugin "beancount.plugins.implicit_prices"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_average_cost"
plugin "beancount.plugins.unique_prices"

بر ردیابی سرمایه‌گذاری و دقت سود سرمایه‌ای تمرکز دارد.

برای حسابداری سخت‌گیرانه

plugin "beancount.plugins.pedantic"
plugin "beancount.plugins.sellgains"
plugin "beancount.plugins.check_closing"

حداکثر اعتبارسنجی برای محیط‌های عملیاتی.

پیکربندی پیش‌فرض در Beancount.io

ما در Beancount.io، پلاگین auto_accounts را به صورت پیش‌فرض در تمام فایل‌های لجر جدید قرار می‌دهیم:

plugin "beancount.plugins.auto_accounts"

این کار تعادل خوبی بین سهولت استفاده و عملکرد برای شروع سریع ایجاد می‌کند.


بهترین روش‌ها (Best Practices)

۱. با حداقل شروع کنید و به مرور اضافه کنید: با auto_accounts و noduplicates شروع کنید، سپس با تکامل دفتر مالی خود، پلاگین‌های اعتبارسنجی را اضافه کنید.

۲. پلاگین‌ها را به صورت جداگانه تست کنید: هنگام افزودن چندین پلاگین، آن‌ها را یکی‌یکی فعال کنید تا تاثیر هر کدام را درک کنید.

۳. پیام‌های خطا را با دقت بخوانید: خطاهای پلاگین اغلب به مسائل واقعی حسابداری اشاره دارند که نیاز به اصلاح دارند.

۴. از pedantic برای فایل‌های نهایی استفاده کنید: هنگامی که گردش کار شما تثبیت شد، فعال کردن اعتبارسنجی سخت‌گیرانه را مد نظر قرار دهید.

۵. ترکیب با پلاگین‌های سفارشی: پلاگین‌های اصلی در کنار پلاگین‌های سفارشی مانند پلاگین پیش‌بینی (forecast) برای حداکثر کارایی عمل می‌کنند.


فراتر از پلاگین‌های بومی

در حالی که پلاگین‌های بومی عملکردهای اصلی را ارائه می‌دهند، اکوسیستم Beancount شامل بسیاری از پلاگین‌های توسعه‌یافته توسط جامعه برای نیازهای تخصصی است:

  • fava.plugins.forecast - برای پیش‌بینی تراکنش‌های تکراری
  • fava.plugins.link_documents - برای پیوند دادن تراکنش‌ها به فایل‌های رسید
  • واردکننده‌های سفارشی (Importers) برای فرمت‌های CSV اختصاصی بانک‌ها
  • ماشین‌حساب‌ها و گزارش‌های مخصوص مالیات

برای گزینه‌های بیشتر، اکوسیستم Beancount را بررسی کنید.


نتیجه‌گیری

پلاگین‌های بومی Beancount، حسابداری متن‌محور را از یک فرآیند دستی به یک سیستم مدیریت مالی خودکار، معتبر و قدرتمند تبدیل می‌کنند. با درک و بهره‌گیری از این ابزارهای داخلی، می‌توانید:

  • ✅ کارهای خسته‌کننده دفترداری را خودکار کنید
  • ✅ خطاها را قبل از تبدیل شدن به مشکل شناسایی کنید
  • ✅ یکپارچگی دقیق داده‌ها را حفظ کنید
  • ✅ گزارش‌های مالی دقیق تهیه کنید
  • ✅ به جای ورود داده‌ها، بر تحلیل‌های مالی تمرکز کنید

همین امروز آزمایش این پلاگین‌ها را در دفتر مالی خود شروع کنید. با auto_accounts و implicit_prices آغاز کنید و به تدریج با بلوغ روش‌های حسابداری خود، پلاگین‌های اعتبارسنجی را اضافه نمایید.

برای امتحان کردن این پلاگین‌ها آماده‌اید؟ به Beancount.io بروید و از امروز استفاده از آن‌ها را در فایل لجر خود شروع کنید!


منابع


درباره پلاگین‌های Beancount سوالی دارید؟ به گفتگو در انجمن گفتگو ما بپیوندید یا مستندات ما را بررسی کنید.

References: