راهنمای رابط وب beancount.io

رابط وب beancount.io (با پشتیبانی Fava) مجموعه کاملی از ابزارها را برای مدیریت، پرس و جو و مصورسازی داده‌های مالی شما ارائه می‌دهد. این راهنما ویژگی‌های اصلی آن، از ورود داده‌های اولیه تا سفارشی‌سازی و عیب‌یابی پیشرفته را پوشش می‌دهد.

۱. ویرایش و ورود داده

ویرایشگر داخلی

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

• تکمیل خودکار: کلید Tab را فشار دهید تا نام حساب‌ها، پرداخت‌کنندگان، تگ‌ها و لینک‌ها تکمیل شوند.

• میانبرهای صفحه کلید:

  • Ctrl+Space: فعال کردن تکمیل خودکار.
  • Ctrl+/: خطوط را کامنت یا از حالت کامنت خارج کنید.
  • Ctrl+D: خط فعلی را کپی کنید.
  • Alt+Up/Down: خط فعلی را به بالا یا پایین منتقل کنید.

• مکان‌نمای هوشمند: از گزینه $insert-entry$ در فایل خود استفاده کنید تا هنگام باز شدن ویرایشگر، مکان‌نما به طور خودکار در آخرین ورودی برای یک حساب خاص قرار گیرد.

  option "insert-entry" "Expenses:Food:Dining-Out"

افزودن تراکنش‌ها

برای باز کردن فرم تراکنش، روی دکمه + (یا کلید n) کلیک کنید.

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

• تگ‌ها/لینک‌های درون‌خطی: تگ‌ها و لینک‌ها را مستقیماً در فیلد توضیحات اضافه کنید (به عنوان مثال، Lunch #food ^receipt-001).

• الگوهای تراکنش: ورودی‌های دارای تاریخ آتی را با تگ #template ایجاد کنید. سپس می‌توانید از فرم برای یافتن و پر کردن آنها استفاده کنید.

  2099-01-01 * "Monthly Rent Payment" #template
      Expenses:Housing:Rent      1500.00 USD
      Assets:Checking           -1500.00 USD

۲. مدیریت اسناد

رسیدها، صورت‌حساب‌ها و سایر فایل‌ها را به طور موثر به تراکنش‌های خود پیوند دهید.

• بارگذاری از طریق کشیدن و رها کردن:

  • یک فایل را روی نام حساب رها کنید تا در پوشه آن حساب ذخیره شود.
  • یک فایل را روی تراکنش در دفتر روزنامه رها کنید تا مستقیماً آن را پیوند دهید.

• ذخیره‌سازی سند: فایل‌ها در پوشه‌ای ذخیره می‌شوند که توسط دستورالعمل $option "documents" "path/to/your/documents"$ در فایل Beancount شما مشخص شده است.

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

  plugin "fava.plugins.link_documents"
  plugin "fava.plugins.tag_discovered_documents"

۳. پرس و جو و تجزیه و تحلیل با BQL

صفحه Query به شما امکان می‌دهد پرس و جوهای زبان پرس و جوی Beancount ‏(BQL) را اجرا کنید، مشابه ابزار خط فرمان bean-query.

• مصورسازی: نتایج پرس و جو به طور خودکار به صورت جدول ارائه می‌شوند. اگر پرس و جوی شما دو ستون (مانند تاریخ/رشته و یک عدد) برگرداند، رابط همچنین یک نمودار خطی، میله‌ای یا درختی ایجاد می‌کند.
• خروجی: هر نتیجه پرس و جو را به عنوان یک فایل CSV بارگیری کنید.

مثال‌های کاربردی پرس و جو

• خلاصه هزینه‌های ماهانه:

  SELECT account, SUM(position) AS total
  FROM postings
  WHERE account ~ '^Expenses' AND date >= 2024-01-01 AND date < 2024-02-01
  GROUP BY account
  ORDER BY total DESC;

• درآمد در مقابل هزینه‌ها بر اساس ماه:

  SELECT YEAR(date) as year, MONTH(date) as month,
         SUM(IIF(account ~ '^Income', -position, 0)) as income,
         SUM(IIF(account ~ '^Expenses', position, 0)) as expenses
  FROM postings
  GROUP BY year, month
  ORDER BY year, month;

۴. سفارشی‌سازی و گردش کار

سفارشی‌سازی نمای

نمایش رابط را با این گزینه‌ها در فایل Beancount خود تنظیم کنید:

• قابلیت مشاهده حساب: کنترل کنید کدام حساب‌ها در نوار کناری ظاهر شوند.

  option "show-closed-accounts" "false"
  option "show-accounts-with-zero-balance" "false"
  option "collapse-pattern" "Assets:Investments:.*"

• نشانگرهای به‌روز: نقاط رنگی در کنار حساب‌ها وضعیت آنها را نشان می‌دهند (سبز برای ترازنامه موفق، قرمز برای ناموفق، زرد برای عدم بررسی ترازنامه اخیر). این ویژگی را در دستورالعمل open یک حساب فعال کنید:

  2020-01-01 open Assets:Checking   fava-uptodate-indication: "TRUE"

لینک‌های نوار کناری

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

2024-01-01 custom "fava-sidebar-link" "This Month's Expenses" "/income_statement/?time=month"
2024-01-01 custom "fava-sidebar-link" "All Documents" "/journal/?show=document"

پیکربندی عمومی

• فایل‌های متعدد: اگر چند فایل .beancount را بارگیری می‌کنید، می‌توانید با استفاده از منوی کشویی در بالا سمت چپ بین آنها جابجا شوید.
• ویرایشگر خارجی: رابط کاربری را طوری پیکربندی کنید که فایل‌ها را مستقیماً در ویرایشگر محلی خود با استفاده از گزینه $use-external-editor$ و یک URL handler باز کند.
• زبان: زبان رابط را با گزینه $language$ تنظیم کنید، یا اجازه دهید به طور خودکار از مرورگر شما تشخیص دهد.
• خروجی: هر نمای فیلتر شده دفتر روزنامه را با استفاده از دکمه Export در قالب Beancount خروجی بگیرید.

۵. عملکرد و عیب‌یابی

رسیدگی به فایل‌های بزرگ

برای دفتر کل‌ها با هزاران تراکنش، عملکرد را با موارد زیر بهبود بخشید:

• استفاده از Include: دفتر کل خود را به چندین فایل بر اساس سال یا ماه تقسیم کنید و از دستورالعمل include استفاده کنید.

  include "accounts.beancount"
  include "transactions/2023.beancount"
  include "transactions/2024.beancount"

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

مسائل رایج و رفع آنها

• بارگیری نشدن رابط:

  1. فایل خود را برای خطاهای نحوی با استفاده از ابزار خط فرمان bean-check بررسی کنید.
  2. به دنبال پیام‌های خطا در پایین صفحه وب باشید.
  3. حافظه پنهان مرورگر خود را پاک کنید.

• عملکرد کند:

  1. محدوده تاریخ فعال را در رابط کاربری کاهش دهید.
  2. پرس و جوهای پیچیده BQL را ساده کنید.

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

  ; Correct
  option "documents" "/path/to/docs"
  custom "fava-sidebar-link" "Label" "URL"
  
  ; Incorrect (will cause errors)
  option documents "/path/to/docs"
  custom fava-sidebar-link "Label" "URL"