لینک‌ها و کوئری‌های سفارشی

دستورات لینک نوار کناری تاریخ‌دار را به Fava استاندارد اضافه کنید، سپس یک کوئری ذخیره کنید که مانده‌های منفی پایانی را پس از جمع‌بندی تمام ثبت‌ها پیدا می‌کند. مثال‌ها با Beancount 3.2.3، beanquery 0.2.0 و Fava 1.30.16 اجرا شده‌اند. از راه‌اندازی محلی ثابت استفاده کنید.

این URLها به یک سرور Fava استاندارد محلی هدف‌گیری می‌کنند. داشبورد میزبانی‌شده Beancount.io مسیرهای گزارش متفاوتی دارد و به‌طور جداگانه در زیر محدوده‌بندی شده است.

چرا Fava را سفارشی کنیم؟

میان‌برهای نوار کناری یک نمای فیلترشده مفید را حفظ می‌کنند. یک کوئری ذخیره‌شده سپس می‌تواند به یک سؤال حسابداری خاص بدون وارد کردن مکرر BQL پاسخ دهد.

مشکلاتی که این حل می‌کند:

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

✨ لینک‌های سفارشی نوار کناری

این دستورات را به دفتر کل کامل sidebar-demo.beancount در بخش بعدی اضافه کنید. آن را با fava sidebar-demo.beancount شروع کنید و قبل از کلیک روی یک میان‌بر، گزارش Journal آن را باز کنید.

2021-01-01 custom "fava-sidebar-link" "Current Month" "/jump?time=month"
2021-01-01 custom "fava-sidebar-link" "Last Month" "/jump?time=month-1"
2021-01-01 custom "fava-sidebar-link" "Clear All" "/jump?account=&time=&filter="

عملکرد آنها:

/jump به صفحه در هدر Referer مرورگر بازمی‌گردد و پارامترهای کوئری ارائه‌شده را جایگزین می‌کند. همیشه گزارش Journal را باز نمی‌کند. در ترازنامه، در ترازنامه باقی می‌ماند. این رفتار توسط مدیریت‌کننده تغییر مسیر Fava استاندارد پیاده‌سازی شده است.

ماه جاری: time=month را روی گزارش فعلی تنظیم می‌کند.
ماه قبل: time=month-1 را روی گزارش فعلی تنظیم می‌کند.
پاک کردن همه: account، time و filter را حذف می‌کند. سایر پارامترها، مانند تبدیل و بازه، باقی می‌مانند.

داده‌های آزمایشی 2021 در ماه جاری هیچ تراکنشی نخواهند داشت؛ قبل از بازتولید نتایج کوئری آن، از پاک کردن همه استفاده کنید. یک URL /jump به یک مرجع نیاز دارد. برای یک نشانک که مستقیماً باز می‌شود، به‌جای آن یک URL کامل گزارش کاری را کپی کنید.

در ریشه میزبان، /jump?time=month از /sidebar-demo/journal/?time=2021&account=Assets آزمایش شد: HTTP 302 به همان ژورنال با account=Assets&time=month برگرداند. گزارش مقصد 200 را برگرداند.

اگر یک مدیر کل برنامه Fava را در /books نصب کند، هر میان‌بر نسبی به ریشه باید آن پیشوند را شامل شود. این یک پیکربندی جایگزین است، نه دستور دیگری که در کنار ماه جاری در بالا اضافه شود:

2021-01-01 custom "fava-sidebar-link" "Current Month" "/books/jump?time=month"

یک آزمایش نصب WSGI محلی تأیید کرد که /books/jump به /books/sidebar-demo/journal/ با فیلتر جدید تغییر مسیر می‌دهد. /jump ساده خارج از آن نصب است و 404 برگرداند. لینک‌های سفارشی Fava URL ارائه‌شده را حفظ می‌کنند؛ یک / ابتدایی به معنای ریشه میزبان است، نه ریشه دفتر کل.

محدوده میزبانی‌شده، بررسی‌شده در 2026-09-07: منبع داشبورد Beancount.io از مسیرهایی مانند /ledger/OWNER/LEDGER/income-statement و /ledger/OWNER/LEDGER/query استفاده می‌کند. نوار کناری آن منوی گزارش خود را می‌سازد. منبع بازرسی‌شده هیچ مسیر /jump یا مصرف‌کننده fava-sidebar-link ندارد. بنابراین این دستور استاندارد برای آن داشبورد ایجاد نشده است. در محصول میزبانی‌شده، گزارش مورد نظر را باز کنید و آدرس کاری آن را نشانک کنید. اسنپ‌شات منبع ثابت نمی‌کند که یک استقرار زنده کدام نسخه را اجرا می‌کند.

🔍 کوئری‌های SQL سفارشی

این فایل کامل را به‌عنوان sidebar-demo.beancount ذخیره کنید. عمداً شامل ثبت‌های مثبت و منفی در هر حساب دارایی است:

option "title" "Sidebar Demo"
option "operating_currency" "USD"
2021-01-01 open Assets:BCM:Positive USD
2021-01-01 open Assets:BCM:Negative USD
2021-01-01 open Equity:Opening-Balances USD
 
2021-12-01 * "Opening balances"
  Assets:BCM:Positive        100.00 USD
  Assets:BCM:Negative         20.00 USD
  Equity:Opening-Balances   -120.00 USD
 
2021-12-10 * "Outflows"
  Assets:BCM:Positive        -30.00 USD
  Assets:BCM:Negative        -50.00 USD
  Equity:Opening-Balances     80.00 USD
 
2022-01-05 * "Refund"
  Assets:BCM:Negative         10.00 USD
  Equity:Opening-Balances    -10.00 USD
 
2022-01-09 balance Assets:BCM:Positive 70.00 USD
2022-01-09 balance Assets:BCM:Negative -20.00 USD

bea --file sidebar-demo.beancount check عبور می‌کند. در ابتدای 9 ژانویه، Positive دارای 100 - 30 = 70 USD است؛ Negative دارای 20 - 50 + 10 = -20 USD است.

این کوئری را در صفحه Query Fava استاندارد با فیلترهای سراسری پاک‌شده اجرا کنید:

SELECT account, currency, SUM(number) AS ending_balance
FROM postings
WHERE account ~ ':BCM:'
  AND date < 2022-01-09
GROUP BY account, currency
HAVING SUM(number) < 0
ORDER BY account, currency;

حساب	ارز	مانده پایانی
Assets:BCM:Negative	USD	-20.00

تجزیه و تحلیل:

WHERE ثبت‌هایی را که باید جمع شوند انتخاب می‌کند. هیچ مرز تاریخ پایینی وجود ندارد: یک مانده پایانی به تمام تاریخچه قبلی، از جمله مانده‌های افتتاحیه 1 دسامبر نیاز دارد. مرز بالایی انحصاری شامل 8 ژانویه است و تراکنش‌های 9 ژانویه را حذف می‌کند.

GROUP BY account, currency ارزهای متمایز را جدا نگه می‌دارد. HAVING SUM(number) < 0 پس از جمع‌بندی مقادیر مثبت و منفی هر گروه فیلتر می‌کند. این یک مانده واحد پایانی به ازای هر ارز است، نه ارزش بازار تبدیل‌شده به یک ارز. هر حساب دقیق را گزارش می‌دهد، نه حساب‌های والد جمع‌شده.

برای مقایسه، این کوئری قابل اجرا به یک سؤال متفاوت پاسخ می‌دهد: چه مقدار در طول پنجره بررسی به‌صورت منفی ثبت شده است؟

SELECT account, currency, SUM(number) AS negative_postings
FROM postings
WHERE account ~ ':BCM:'
  AND number < 0
  AND date >= 2021-12-09 AND date < 2022-01-09
GROUP BY account, currency
ORDER BY account, currency;

حساب	ارز	ثبت‌های منفی
Assets:BCM:Negative	USD	-50.00
Assets:BCM:Positive	USD	-30.00

کوئری دوم بازپرداخت و مانده‌های افتتاحیه را حذف می‌کند. ردیف -30.00 USD آن به این معنی نیست که Positive بیش از حد برداشت شده است. افزودن یک مرز تاریخ پایینی به کوئری اول به‌جای آن حرکت خالص در طول یک دوره را تولید می‌کند، نه یک مانده پایانی. برای نحو بیشتر کوئری، به مرجع BQL مراجعه کنید.

موارد استفاده:

بررسی حساب‌های دارایی برای مقادیر منفی غیرمنتظره.
بررسی جداگانه ثبت‌های منفی هنگام تحقیق در مورد خروج وجه یا برگشت‌ها.
تطبیق مانده گزارش‌شده با تاریخچه افتتاحیه و فعالیت بعدی قبل از درمان آن به‌عنوان ناهنجاری. مانده منفی بدهی یا درآمد می‌تواند طبیعی باشد.

🛠 نکته حرفه‌ای: ترکیب لینک‌ها + کوئری‌ها

Fava از لینک به کوئری‌ها پشتیبانی می‌کند. این کوئری ذخیره‌شده و میان‌بر را به sidebar-demo.beancount اضافه کنید:

2021-01-01 query "negative-balances" "SELECT account, currency, SUM(number) AS ending_balance FROM postings WHERE account ~ ':BCM:' AND date < 2022-01-09 GROUP BY account, currency HAVING SUM(number) < 0 ORDER BY account, currency"
2021-01-01 custom "fava-sidebar-link" "Negative Balances" "/sidebar-demo/query/?query_string=.run+%22negative-balances%22"

دستور کوئری همچنین در نوار کناری کوئری‌های ذخیره‌شده Fava ظاهر می‌شود، مشروط به sidebar-show-queries (پیش‌فرض 5). میان‌بر صریح به اسلاگ sidebar-demo فایل آزمایشی هدف‌گیری می‌کند و کوئری نام‌گذاری‌شده را اجرا می‌کند. صفحه کوئری استاندارد query_string را از URL می‌خواند؛ API کوئری آن همان ردیف واحد -20.00 USD را در آزمایش محلی برگرداند. به کامپوننت Query نسخه‌بندی‌شده مراجعه کنید.

از اسلاگ واقعی دفتر کل خود در یک کتاب متفاوت استفاده کنید. در زیر نصب /books، میان‌بر به /books/sidebar-demo/query/?query_string=.run+%22negative-balances%22 تبدیل می‌شود. فیلترهای سراسری را برای مانده پایانی تمام‌تاریخ پاک نگه دارید؛ یک فیلتر تاریخ می‌تواند تاریخچه افتتاحیه را قبل از اجرای کوئری ذخیره‌شده حذف کند.

افکار نهایی

از میان‌برهای ماه برای پیمایش گزارش‌ها استفاده کنید و از کوئری ذخیره‌شده برای بررسی یک مانده پایانی قابل تکرار استفاده کنید. هنگام بررسی بودجه خود، خروج وجه، حرکت دوره و مانده‌های پایانی را قبل از تفسیر یک عدد منفی تشخیص دهید. برای گزارش‌های اضافی، به مستندات افزونه Fava و راهنمای رابط کاربری مراجعه کنید.

چرا Fava را سفارشی کنیم؟​

مشکلاتی که این حل می‌کند:​

✨ لینک‌های سفارشی نوار کناری​

عملکرد آنها:​

🔍 کوئری‌های SQL سفارشی​

تجزیه و تحلیل:​

موارد استفاده:​

🛠 نکته حرفه‌ای: ترکیب لینک‌ها + کوئری‌ها​

افکار نهایی​