# Function listCharterReservation ### #### · هدف: این متد به عنوان یک مرکز گزارش‌گیری برای انواع مختلف رزروها و موجودیت‌های مرتبط با یک چارتر خاص عمل می‌کند. بر اساس پارامتر `type` که از طریق URL دریافت می‌شود، متد می‌تواند لیست رزروهای قطعی (`definite`)، موقت (`temporary`)، استرداد شده (`refund`)، حذف شده (`deleted`)، یا لیست گارانتی‌ها (`warranty`) و حتی مسافران بر اساس پلن اتاق‌بندی (`plan`) را استخراج کند. برای رزروهای قطعی (`definite`)، قابلیت فیلتر پیشرفته بر اساس بازه زمانی و نوع گزارش (`check_in`, `check_out`, `guests`) وجود دارد که امکان تهیه گزارش‌های دقیق از وضعیت حضور مسافران در یک هتل را فراهم می‌سازد. این تفکیک منطقی، پیچیدگی را کاهش داده و واکشی داده‌های مرتبط با یک چارتر را بسیار ساده و بهینه می‌کند.
**ویژگی‌ها****توضیحات**
**هدف کلی**واکشی لیست‌های مختلف مرتبط با یک چارتر (رزرو، گارانتی، استرداد و…).
**مرکز عملیات**استفاده از پارامتر `type` در URL برای تعیین نوع داده درخواستی.
**انواع گزارش**`definite`, `temporary`, `refund`, `warranty`, `deleted`, `plan`.
**فیلتر پیشرفته (برای `definite`)**فیلتر بر اساس بازه زمانی (`from`, `to`) و نوع گزارش (`check_in`, `check_out`, `guests`).
**انتخاب جدول پویا**استفاده از تابع کمکی `getTableCharter` برای یافتن جدول رزرو صحیح (بر اساس نوع چارتر).
**یکپارچگی خروجی**استفاده از `ReservationResource::collection` برای فرمت‌دهی استاندارد لیست رزروها.
**خطایابی**مدیریت خطا برای درخواست‌های نامعتبر (مثلاً درخواست `plan` برای چارتری غیر از اقامتگاه).
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****موقعیت****نوع داده****نام پارمتر**
**شناسه چارتر اصلی که گزارش‌ها از آن استخراج می‌شود.****`Route`****`Illuminate\Http\Request`****`$id`**
**نوع گزارش درخواستی. مقادیر معتبر: `definite`, `temporary`, `refund`, `warranty`, `deleted`, `plan`.****`Route`****`string`****`$type`**
**(اختیاری) تاریخ شروع بازه برای فیلتر رزروهای `definite`.****`Query`****`string (date)`****`advanced[from]`**
**(اختیاری) تاریخ پایان بازه برای فیلتر رزروهای `definite`.****`Query`****`string (date)`****`advanced[to]`**
**(اختیاری) نوع گزارش تاریخ برای `definite`. مقادیر: `check_in`, `check_out`, `guests`.****`Query`****`string`****`advanced[report_type]`**
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**یک آبجکت `JSON` حاوی کلید `items` (لیست نتایج) و `meta` (شامل `timestamp`). برای `definite`، نتایج با `ReservationResource` فرمت می‌شوند.****`Illuminate\Http\JsonResponse`**
**در صورت خطا (مثلاً درخواست `plan` برای چارتر مسیر)، یک پاسخ با کد `409 Conflict` و پیام خطا بازگردانده می‌شود.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده / سناریو: **سناریو ۱: دریافت لیست مسافرانی که در یک هتل در بازه زمانی مشخصی اقامت دارند** - **Request URL:** `/api/panel/v2/charter/380/definite/list?advanced[from]=2025-10-20&advanced[to]=2025-10-25&advanced[report_type]=guests` - **Action:** 1. متد با `$id=380` و `$type='definite'` فراخوانی می‌شود. 2. جدول رزرو مربوط به چارتر 380 (فرضاً `charter_accommodation_reservation`) مشخص می‌شود. 3. کوئری برای واکشی رزروهای قطعی (`refund_id` و `deleted_at` برابر `null`) اجرا می‌شود. 4. شرط `WHERE checkin_date <= '2025-10-25' AND checkout_date > '2025-10-20'` اعمال می‌شود. 5. نتایج با `ReservationResource` فرمت شده و بازگردانده می‌شوند. - **Response:** - `HTTP Status`: `200 OK` - `Body`: `{"items": [{...reservation 1...}, {...reservation 2...}], "meta": {...}}` **سناریو ۲: دریافت لیست گارانتی‌های ثبت شده برای یک چارتر** - **Request URL:** `/api/panel/v2/charter/412/warranty/list` - **Action:** 1. متد با `$id=412` و `$type='warranty'` فراخوانی می‌شود. 2. کوئری به جدول `charter_warranties` با شرط `main_id = 412` اجرا می‌شود. - **Response:** - `HTTP Status`: `200 OK` - `Body`: `{"items": [{...warranty 1...}, {...warranty 2...}], "meta": {...}}`