مستندات امیر

مستندات پروژه امیر، نرم‌افزار آزاد حسابداری لاراول.

دستور خروجی گرفتن سال مالی (fiscal-year:export)

این دستور Artisan داده‌های مرتبط با یک سال مالی (که به‌صورت یک رکورد Company نمایش داده می‌شود) را به یک فایل JSON منتقل می‌کند. این فایل می‌تواند برای پشتیبان‌گیری، مهاجرت داده‌ها یا به‌عنوان ورودی برای دستور fiscal-year:import استفاده شود.

هدف

استخراج بخش‌های مشخصی از داده‌ها (مانند بانک‌ها، مشتری‌ها، محصولات، تنظیمات و غیره) مرتبط با یک سال مالی خاص از پایگاه داده و ذخیره آن‌ها در قالب JSON ساختاریافته.

نحوه استفاده

php artisan fiscal-year:export <source_id> [options]

آرگومان‌ها

آرگومان توضیحات الزامی
source_id شناسه عددی رکورد Company که باید منتقل شود بله

گزینه‌ها

گزینه توضیحات الزامی مقدار پیش‌فرض
--output مسیر نسبی داخل storage/app برای فایل خروجی JSON (مثلاً my_exports/fy_export.json). در صورت عدم تعیین، نام پیش‌فرض تولید می‌شود. خیر exports/fiscal_year_<source_id>_<timestamp>.json
--sections لیست بخش‌های موردنظر برای خروجی به‌صورت جداشده با کاما (مثل banks,customers,products). بخش‌های معتبر در FiscalYearService::getAvailableSections() تعریف شده‌اند. خیر همه بخش‌های موجود

بخش‌های قابل دسترس (از FiscalYearService):

  • configs
  • banks
  • bank_accounts
  • customer_groups
  • customers
  • product_groups
  • products
  • subjects

مثال‌ها

  1. خروجی گرفتن از تمام داده‌های سال مالی با ID برابر 1:
sail artisan fiscal-year:export 1

خروجی: storage/app/exports/fiscal_year_1_<timestamp>.json

  1. خروجی گرفتن فقط از بانک‌ها و مشتری‌ها برای سال مالی ID برابر 5:
sail artisan fiscal-year:export 5 --output=data_exports/fy5_banks_customers.json --sections=banks,customers

خروجی: storage/app/data_exports/fy5_banks_customers.json

  1. خروجی گرفتن کامل با مسیر سفارشی:
sail artisan fiscal-year:export 2 --output=archive/fiscal_year_2_full.json

خروجی: storage/app/archive/fiscal_year_2_full.json

خروجی

  • مسیر کامل فایل JSON تولید شده نمایش داده می‌شود.
  • JSON شامل کلیدهایی برای هر بخش صادر شده است (مثل "banks"، "customers").

  • همچنین یک کلید "meta" شامل اطلاعات زیر وجود دارد:

    • source_id
    • company_name
    • timestamp
    • sections_exported

مدیریت خطا

  • اگر source_id معتبر نباشد، خطا نمایش داده می‌شود.
  • اگر نام بخش‌ها در --sections اشتباه باشد، هشدار داده می‌شود. اگر هیچ بخش معتبری باقی نماند، دستور متوقف می‌شود.
  • خطاهای دیگر (مثل مشکل دسترسی به فایل) در لاگ storage/logs/laravel.log ثبت می‌شوند.

دستور وارد کردن سال مالی (fiscal-year:import)

این دستور Artisan داده‌ها را از یک فایل JSON (که معمولاً توسط fiscal-year:export ساخته شده است) به یک سال مالی جدید (رکورد Company جدید) وارد می‌کند.

هدف

ایجاد یک سال مالی جدید و پر کردن آن با داده‌های قبلی (بانک‌ها، مشتری‌ها، محصولات و غیره). این قابلیت برای بازیابی بکاپ یا انتقال داده‌ها بین محیط‌ها استفاده می‌شود.

نحوه استفاده

php artisan fiscal-year:import <file> <fiscal_year> --name=<new_name> [options]

آرگومان‌ها

آرگومان توضیحات الزامی
file مسیر فایل JSON ورودی نسبت به storage/app بله
fiscal_year شناسه سال مالی (عدد مثبت) بله

گزینه‌ها

گزینه توضیحات الزامی مقدار پیش‌فرض
--name نام سال مالی جدید که ایجاد خواهد شد بله —
--force رد کردن پیام تأیید قبل از شروع عملیات (با احتیاط استفاده شود) خیر false

توجه: بسته به ساختار مدل Company ممکن است فیلدهای دیگری نیز در FiscalYearService::importData لازم باشد.

مثال‌ها

  1. وارد کردن داده از فایل backup به سال مالی جدید 2024:
sail artisan fiscal-year:import exports/fy1_backup.json 2024 --name="سال مالی ۱۴۰۳"

قبل از اجرا تأیید گرفته می‌شود.

  1. وارد کردن داده بدون تأیید (اجباری):
sail artisan fiscal-year:import archive/old_data.json 2023 --name="بازیابی شده" --force

روند اجرا

  1. اعتبارسنجی
    • بررسی وجود گزینه --name
    • بررسی مثبت بودن fiscal_year
    • بررسی وجود فایل در storage/app
  2. تأیید کاربر
    • نمایش مسیر فایل و اطلاعات سال مالی جدید
    • درخواست تأیید (مگر با --force)
  3. اجرای عملیات واردسازی
    • خواندن و decode کردن JSON
    • آماده‌سازی داده‌ها برای ایجاد رکورد جدید Company
    • فراخوانی FiscalYearService::importData برای ایجاد داده‌ها
  4. خروجی
    • نمایش پیام موفقیت همراه با ID و نام سال مالی جدید
    • در صورت خطا، نمایش پیام مناسب

مدیریت خطا

  • نبود گزینه --name
  • نامعتبر بودن fiscal_year
  • نبود فایل ورودی
  • خراب بودن JSON
  • خطاهای داخلی سرویس FiscalYearService
  • لغو عملیات توسط کاربر

تمام خطاها در storage/logs/laravel.log ثبت می‌شوند.