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

بهروزرسانی تا تاریخ ۲۰۲۶-۰۹-۱۵.

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

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

افزونههای Beancount چیست؟​

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

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

نحوه استفاده از افزونهها​

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

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

برخی از افزونهها گزینههای پیکربندی را میپذیرند:

; @m49-fragment dateless
plugin "beancount.plugins.check_commodity" "{'Assets:Trading': '.*'}"

دستهبندی افزونههای بومی​

افزونههای بومی Beancount در چهار دسته اصلی قرار میگیرند:

۱. افزونههای اتوماسیون​

۲. افزونههای اعتبارسنجی​

۳. افزونههای تبدیل​

۴. فرافزونهها​

۱. افزونههای اتوماسیون​

این افزونهها کارهای تکراری دفترداری را خودکار میکنند، در وقت شما صرفهجویی میکنند و خطاهای دستی را کاهش میدهند.

auto_accounts - اعلانهای خودکار حساب​

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

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

مثال:

plugin "beancount.plugins.auto_accounts"
 
2026-01-01 * "کافه"
  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 * "خرید سهام AAPL"
  Assets:Investments:Stocks    10 AAPL @ 150.00 USD
  Assets:Cash                 -1500.00 USD

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

2026-01-02 price AAPL  150.00 USD

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

۲. افزونههای اعتبارسنجی​

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

noduplicates - تشخیص تراکنش تکراری​

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

چرا استفاده کنیم: از ورودیهای تکراری تصادفی، بهویژه هنگام وارد کردن تراکنشها از چندین منبع، جلوگیری میکند.

مثال:

; @m49-fragment expected-failure
plugin "beancount.plugins.noduplicates"
 
2026-01-02 * "پرداخت اجاره"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD
 
; این یک خطا ایجاد میکند:
2026-01-02 * "پرداخت اجاره"
  Expenses:Rent              1200.00 USD
  Assets:Checking           -1200.00 USD

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

check_commodity - اعتبارسنجی اعلان کالا​

عملکرد: اطمینان میدهد که همه کالاهای استفادهشده در دفتر کل شما دستورالعملهای Commodity مربوطه دارند.

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

مثال:

; @m49-fragment expected-failure
plugin "beancount.plugins.check_commodity"
 
2015-01-01 commodity USD
2020-01-01 commodity AAPL
 
; این بدون اعلان کالا یک خطا ایجاد میکند:
2026-01-02 * "خرید بیتکوین"
  Assets:Crypto              0.5 BTC @ 45000 USD
  Assets:Cash             -22500.00 USD

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

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

عملکرد: بررسی میکند که مبنای هزینه بهدرستی در تراکنشها حفظ شده است، بهویژه هنگام استفاده از ثبت هزینه میانگین.

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

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

check_closing - اعتبارسنجی بستن موجودی​

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

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

مثال:

plugin "beancount.plugins.check_closing"
 
2026-01-02 * "بستن کل موقعیت AAPL" #closing
  Assets:Investments:Stocks   -100 AAPL {150.00 USD}
  Assets:Cash                15500.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.

مثال:

; @m49-fragment expected-failure
plugin "beancount.plugins.leafonly"
 
; این یک خطا ایجاد میکند:
2026-01-02 * "خرید مواد غذایی"
  Expenses:Food              50.00 USD  ; خطا: باید به حساب برگ پست شود
  Assets:Cash               -50.00 USD
 
; روش صحیح:
2026-01-02 * "خرید مواد غذایی"
  Expenses:Food:Groceries    50.00 USD  ; صحیح: پستینگ به حساب برگ
  Assets:Cash               -50.00 USD

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

nounused - تشخیص حساب استفادهنشده​

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

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

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

onecommodity - تککالایی در هر حساب​

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

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

مثال:

; @m49-fragment expected-failure
plugin "beancount.plugins.onecommodity"
 
2026-01-02 * "خرید سهام"
  Assets:Investments         10 AAPL @ 150 USD
  Assets:Cash             -1500.00 USD
 
; این یک خطا ایجاد میکند:
2026-01-03 * "خرید سهام بیشتر"
  Assets:Investments         5 GOOGL @ 140 USD  ; خطا: کالای متفاوت
  Assets:Cash              -700.00 USD

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

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

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

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

مثال:

plugin "beancount.plugins.sellgains"
 
2026-01-02 * "فروش سهام AAPL"
  Assets:Investments:Stocks   -10 AAPL {140.00 USD}
  Assets:Cash                1500.00 USD
  Income:Investments:Gains   -100.00 USD  ; افزونه تأیید میکند که این صحیح است

افزونه بررسی خواهد کرد: عواید فروش (۱۵۰۰) - مبنای هزینه (۱۴۰۰) = سود (۱۰۰)

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

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

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

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

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

check_drained - اعتبارسنجی حساب تخلیهشده​

عملکرد: حسابهایی را علامتگذاری میکند که هنوز موجودی دارند (از جمله ارزهای بدون قیمت یا لاتهای باقیمانده) در حالی که انتظار داشتید پس از انتقال یا بستن خالی باشند.

چرا استفاده کنیم: موجودیهای باقیمانده را که تأییدهای balance و برچسبهای #closing ممکن است از دست بدهند، شناسایی میکند — بهویژه پس از جابهجاییهای چندکالایی مفید است.

وضعیت (بررسیشده در ۲۰۲۶-۰۹-۱۵): در درخت Beancount 3.x در beancount/plugins/check_drained.py در خط فعلی PyPI (3.2.3) موجود است.

چه زمانی استفاده کنیم: پس از سازماندهی مجدد پرتفوی بزرگ یا هنگام بستن حسابهای کارگزار.

۳. افزونههای تبدیل​

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

currency_accounts - حسابهای معاملات ارزی​

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

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

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

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

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

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

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

۴. فرافزونهها​

این افزونهها مجموعههایی از سایر افزونهها برای راحتی هستند.

auto - همه افزونههای خودکار​

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

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

pedantic - همه افزونههای اعتبارسنجی​

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

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

مثال:

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"

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

وضعیت افزونه بررسیشده در ۲۰۲۶-۰۹-۱۵​

در برابر درخت زنده beancount/plugins در Beancount 3.2.3 (PyPI، ۲۰۲۶-۰۹-۱۵):

هیچ چیزی در آن مجموعه بومی بین پیشنویس اصلی این راهنما و تاریخ بالا حذف نشده است. افزونههای جامعه (غیربومی) همچنان به فهرست افزونههای Awesome Beancount و نمایشگاه جامعه تعلق دارند — مخازن شخص ثالث را بهعنوان نسخهبندی مستقل در نظر بگیرید و قبل از فعال کردن در دفتر کل تولیدی، آخرین انتشار هر مخزن را بررسی کنید.

بهترین روشها​

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

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

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

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

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

فراتر از افزونههای بومی​

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

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

برای گزینههای بیشتر، اکوسیستم Beancount را کاوش کنید، و برای نحوه ترکیب افزونههای بومی با ایمپورترها و Fava، نمایشگاه جامعه را ببینید.

نتیجهگیری​

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

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

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

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

منابع​

• مرجع API افزونههای Beancount
• راهنمای اسکریپتنویسی و افزونههای Beancount
• افزونهها و گزینههای Beancount نوشته Bryan Alves
• مخزن گیتهاب Beancount

سؤالی درباره افزونههای Beancount دارید؟ در انجمن جامعه ما به بحث بپیوندید یا مستندات ما را بررسی کنید.

یک دفتر کل مثال ارز دیجیتال زنده را کاوش کنید: