# Function listCharter
###
#### · هدف:
این متد به عنوان یک موتور جستجو و لیستساز قدرتمند برای چارترها عمل میکند. هدف اصلی آن فراهم کردن یک رابط کاربری منعطف برای بازیابی چارترها بر اساس مجموعهی گستردهای از فیلترها، از جمله فیلترهای ساده (مانند `serial`, `type`) و جستجوی پیشرفته (`advanced`) است. بخش `advanced` امکان فیلتر بر اساس بازه زمانی، مبدأ، مقصد، دوطرفه بودن (`roundtrip`)، نوع مسیر (هوایی، ریلی و…) و وضعیت (فعال/غیرفعال) را فراهم میکند. متد به طور خودکار صفحهبندی (Pagination) را مدیریت کرده و مقادیر پیشفرض را در صورت عدم ارائه، تنظیم میکند. یک ویژگی خاص این متد، قابلیت مرتبسازی معکوس (`action == 'list'`) نتایج است که برای نمایش آخرین موارد ثبتشده در ابتدا کاربرد دارد. همچنین، این متد با در نظر گرفتن سطح دسترسی کاربر، نتایج را فقط به شعبه مربوط به همان کاربر محدود میکند (مگر اینکه کاربر ادمین اصلی با `branch=1` باشد).
| **ویژگیها** | **توضیحات** |
| **هدف کلی** | جستجو، فیلتر و صفحهبندی جامع چارترها. |
| **فیلترهای اصلی** | `serial`, `type`. |
| **فیلتر پیشرفته** | بازه زمانی (`from`, `to`)، مبدأ/مقصد، `roundtrip`، `subtype`, `status`. |
| **مدیریت شعبه** | محدودسازی خودکار نتایج به شعبه کاربر لاگین کرده. |
| **صفحهبندی** | مدیریت هوشمند پارامترهای `paginate` با مقادیر پیشفرض. |
| **مرتبسازی** | مرتبسازی پیشفرض بر اساس تاریخ شروع و شناسه. |
| **مرتبسازی معکوس** | قابلیت برعکس کردن ترتیب آیتمهای صفحه فعلی با `action=list`. |
| **فرمت خروجی** | استفاده از `CharterResource` برای استانداردسازی آبجکتهای JSON خروجی. |
---
#### · ورودیها (پارامترها):
| **توضیحات** | **موقعیت** | **نوع داده** | **نام پارمتر** |
| **شناسه منحصر به فرد چارتری که باید حذف شود.** | **`Query`** | **`string`** | **`serial`** |
| **نوع چارتر (مثلاً `route`, `accommodation`).** | **`Query`** | **`string`** | **`type`** |
| **اگر مقدار `list` باشد، ترتیب نتایج صفحه فعلی معکوس میشود.** | **`Query`** | **`string`** | **`action`** |
| **آرایهای برای مدیریت صفحهبندی شامل `length` (تعداد در صفحه) و `start` (نقطه شروع).** | **`Query`** | **`array`** | **`paginate`** |
| **آرایهای برای فیلترهای پیشرفته.** | **`Query`** | **`array`** | **`advanced`** |
**ساختار آرایه `advanced`:**
- `id`: `integer` - جستجو بر اساس شناسه نمایشی (`id - 10000`).
- `from`, `to`: `string` (date) - بازه زمانی برای فیلتر تاریخ `start` و `end` چارتر.
- `origin`, `destination`: `integer` - شناسه شهر/فرودگاه مبدأ و مقصد.
- `roundtrip`: `boolean` - آیا مسیرهای دوطرفه (رفت و برگشت) نیز در نظر گرفته شوند یا خیر.
- `route`: `string` - `subtype` چارتر (مثلاً `aircraft`, `train`).
- `status`: `string` - وضعیت چارتر (`all`, `active`, `inactive`).
---
#### · خروجی (Return):
| **توضیحات** | **نوع داده** |
| **یک آبجکت `JSON` حاوی دو کلید اصلی: `items` (آرایهای از چارترها با فرمت `CharterResource`) و `meta` (شامل `timestamp` و اطلاعات جدول مانند `total` تعداد کل نتایج).** | **`Illuminate\Http\JsonResponse`** |
---
#### · مثال استفاده / سناریو:
**سناریو ۱: جستجوی پروازهای فعال تهران به مشهد در هفته آینده**
- **Request URL:** `/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`
- **Action:**
1. متد `listCharter` اجرا میشود.
2. کوئری اصلی به جدول `charters` اعمال میشود.
3. فیلتر `where('type', 'route')` و `where('subtype', 'aircraft')` اعمال میشود.
4. فیلتر `where('origin', 1)` و `where('destination', 2)` اعمال میشود.
5. فیلتر `whereBetween('start', ['2025-10-16 00:00:00', '2025-10-23 23:59:59'])` اعمال میشود.
6. فیلتر `whereIn('status', [1, 3])` برای وضعیت `active` اعمال میشود.
7. نتایج بر اساس تاریخ شروع مرتب شده و ۱۰ مورد اول بازگردانده میشود.
- **Response:**
- `HTTP Status`: `200 OK`
- `Body`:
```
{
"items": [
{ "...charter object 1..." },
{ "...charter object 2..." },
// ... up to 10 items
],
"meta": {
"timestamp": 1728994200,
"table": {
"total": 54 // Total charters matching the criteria
}
}
}
```