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/BodyQuery	integerstring	$request->idserial
نوع چارتر (مثلاً route, accommodation).	Query	string	type
اگر مقدار list باشد، ترتیب نتایج صفحه فعلی معکوس می‌شود.	Query	string	action
آرایه‌ای برای مدیریت صفحه‌بندی شامل length (تعداد در صفحه) و start (نقطه شروع).	Query	array	paginate
آرایه‌ای برای فیلترهای پیشرفته.	Query	array	advanced

ساختار آرایه advanced:

---

·     خروجی (Return):

 

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

---

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

سناریو ۱: حذفجستجوی موفقپروازهای یکفعال چارترتهران بدونبه فروشمشهد در هفته آینده

• Request:Request URL:
• id/api/panel/v2/charter/list?advanced[type]=route&advanced[subtype]=aircraft&advanced[origin]=1&advanced[destination]=2&advanced[from]=2025-10-16&advanced[to]=2025-10-23&advanced[status]=active&paginate[length]=10: 350
• Action:

1. متد ظرفیتlistCharter چارتر با شناسه 350 را بررسی می‌کند.
2. فرض: هیچ رزروی ثبت نشده است (capacity['total'] == capacity['capacity']).
3. یک تراکنش دیتابیس آغازاجرا می‌شود.
4. رکوردها از charter_items و charter_calculations که main_id آن‌ها 350 است، حذف می‌شوند.
5. رکوردکوئری اصلی ازبه جدول charters با شناسه 350 حذفاعمال می‌شود.
6. تراکنش با موفقیتفیلتر commitwhere('type', 'route') و where('subtype', 'aircraft') اعمال می‌شود.
7. فیلتر where('origin', 1) و where('destination', 2) اعمال می‌شود.
8. فیلتر whereBetween('start', ['2025-10-16 00:00:00', '2025-10-23 23:59:59']) اعمال می‌شود.
9. فیلتر whereIn('status', [1, 3]) برای وضعیت active اعمال می‌شود.
10. نتایج بر اساس تاریخ شروع مرتب شده و ۱۰ مورد اول بازگردانده می‌شود.

• Response:
• HTTP Status: 204200 No Content

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

• Request:
• id: 351
• Action:

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

• Response:
• HTTP Status: 409 ConflictOK
• Body:

        {
            "error"items": [
                { "...charter object 1..." },
                { "...charter object 2..." },
                // ... up to 10 items
            ],
            "meta": {
                "code"timestamp": 1000,1728994200,
                "message"table": {
                    "برtotal": روی54 این// چارترTotal رزروcharters انجامmatching شدهthe است و امکان حذف وجود ندارد."criteria
                }
            }
        }