#P1083

Function listCharter

· هدف:

این متد به عنوان یک موتور جستجو و لیست‌ساز قدرتمند برای چارترها عمل می‌کند. هدف اصلی آن فراهم کردن یک رابط کاربری منعطف برای بازیابی چارترها بر اساس مجموعه‌ی گسترده‌ای از فیلترها، از جمله فیلترهای ساده (مانند serial, type) و جستجوی پیشرفته (advanced) است. بخش advanced امکان فیلتر بر اساس بازه زمانی، مبدأ، مقصد، دوطرفه بودن (roundtrip)، نوع مسیر (هوایی، ریلی و…) و وضعیت (فعال/غیرفعال) را فراهم می‌کند. متد به طور خودکار صفحه‌بندی (Pagination) را مدیریت کرده و مقادیر پیش‌فرض را در صورت عدم ارائه، تنظیم می‌کند. یک ویژگی خاص این متد، قابلیت مرتب‌سازی معکوس (action == 'list') نتایج است که برای نمایش آخرین موارد ثبت‌شده در ابتدا کاربرد دارد. همچنین، این متد با در نظر گرفتن سطح دسترسی کاربر، نتایج را فقط به شعبه مربوط به همان کاربر محدود می‌کند (مگر اینکه کاربر ادمین اصلی با branch=1 باشد).

ویژگی‌ها	توضیحات
هدف کلی	جستجو، فیلتر و صفحه‌بندی جامع چارترها.
فیلترهای اصلی	`serial`, `type`.
فیلتر پیشرفته	بازه زمانی (`from`, `to`)، مبدأ/مقصد، `roundtrip`، `subtype`, `status`.
مدیریت شعبه	محدودسازی خودکار نتایج به شعبه کاربر لاگین کرده.
صفحه‌بندی	مدیریت هوشمند پارامترهای `paginate` با مقادیر پیش‌فرض.
مرتب‌سازی	مرتب‌سازی پیش‌فرض بر اساس تاریخ شروع و شناسه.
مرتب‌سازی معکوس	قابلیت برعکس کردن ترتیب آیتم‌های صفحه فعلی با `action=list`.
فرمت خروجی	استفاده از `CharterResource` برای استانداردسازی آبجکت‌های JSON خروجی.

· ورودی‌ها (پارامتر‌ها):

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه منحصر به فرد چارتری که باید حذف شود.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content` بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`
در صورت وجود رزرو روی چارتر، یک آبجکت `JSON` با کد `409 Conflict` و پیام خطا بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`
در صورت بروز خطای غیرمنتظره در حین تراکنش دیتابیس، یک آبجکت `JSON` با کد `400 Bad Request` و جزئیات استثناء (Exception) بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو ۱: حذف موفق یک چارتر بدون فروش

Request:
id: 350
Action:

متد ظرفیت چارتر با شناسه 350 را بررسی می‌کند.
فرض: هیچ رزروی ثبت نشده است (capacity['total'] == capacity['capacity']).
یک تراکنش دیتابیس آغاز می‌شود.
رکوردها از charter_items و charter_calculations که main_id آن‌ها 350 است، حذف می‌شوند.
رکورد اصلی از جدول charters با شناسه 350 حذف می‌شود.
تراکنش با موفقیت commit می‌شود.

Response:
HTTP Status: 204 No Content

سناریو ۲: تلاش برای حذف چارتری که فروش داشته است

Request:
id: 351
Action:

متد ظرفیت چارتر با شناسه 351 را بررسی می‌کند.
فرض: تعدادی رزرو ثبت شده است (capacity['total'] != capacity['capacity']).
عملیات متوقف شده و هیچ تغییری در دیتابیس اعمال نمی‌شود.

Response:
HTTP Status: 409 Conflict
Body:

json

        {
            "error": {
                "code": 1000,
                "message": "بر روی این چارتر رزرو انجام شده است و امکان حذف وجود ندارد."
            }
        }