Skip to main content
#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 خروجی.

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

 

توضیحات موقعیت نوع داده نام پارمتر
شناسه منحصر به فرد چارتری که باید حذف شود. 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:
json
        {
            "items": [
                { "...charter object 1..." },
                { "...charter object 2..." },
                // ... up to 10 items
            ],
            "meta": {
                "timestamp": 1728994200,
                "table": {
                    "total": 54 // Total charters matching the criteria
                }
            }
        }
Back to top