Skip to main content
#P1668

GET /v2/charter/list

Charter: List & Search

این اندپوینت جهت دریافت لیست چارترها با قابلیت فیلتر کردن پیشرفته، جستجو بر اساس تاریخ (با منطق متفاوت برای اقامتگاه و پرواز)، مسیرهای دوطرفه و وضعیت‌های مختلف استفاده می‌شود.

Request Overview

URL: /v2/charter/list
Method: GET
Controller: CharterController@listCharter
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT
  • کاربران با branch_id = 1 به همه رکوردها دسترسی دارند؛ سایرین فقط رکوردهای شعبه خود را می‌بینند.

Request Parameters (Query String)

کلیه پارامترها به صورت Query Param ارسال می‌شوند.

Parameter Type Description
serial string فیلتر دقیق بر اساس شماره سریال
type string نوع چارتر (مثلاً accommodation, flight)
action string اگر مقدار list ارسال شود، ترتیب نمایش آیتم‌ها در صفحه جاری معکوس می‌شود.
paginate[length] integer تعداد آیتم در هر صفحه (پیش‌فرض: 30)
paginate[start] integer آفست شروع (پیش‌فرض: 0)
Advanced Filters (آرایه advanced)
advanced[id] integer جستجو بر اساس ID (سیستم به صورت خودکار ۱۰,۰۰۰ واحد از این عدد کم می‌کند)
advanced[from] date تاریخ شروع بازه جستجو
advanced[to] date تاریخ پایان بازه جستجو
advanced[origin] integer شناسه مبدا
advanced[destination] integer شناسه مقصد
advanced[roundtrip] boolean حالت دوطرفه (اگر true باشد، مسیر برگشت هم جستجو می‌شود)
advanced[route] string فیلتر بر اساس subtype
advanced[status] string active: وضعیت‌های 1 و 3
all: همه وضعیت‌ها (غیر از 1)

Complex Logic Details

۱. منطق تاریخ (Date Logic)

  • حالت عادی (General): جستجو می‌کند که start چارتر دقیقاً بین بازه from و to باشد.
  • حالت اقامتگاه (Accommodation): اگر type=accommodation باشد، سیستم تداخل زمانی (Overlap) را بررسی می‌کند:
    • تاریخ شروع چارتر در بازه باشد.
    • یا تاریخ پایان چارتر در بازه باشد.
    • یا چارتر کل بازه درخواستی را پوشش دهد (شروع چارتر <= شروع درخواست و پایان چارتر >= پایان درخواست).

۲. جستجوی دوطرفه (Roundtrip)

اگر advanced[roundtrip] برابر true باشد و مبدا و مقصد مشخص شده باشند، کوئری به صورت OR اجرا می‌شود:
(مبدا = Origin AND مقصد = Dest) یا (مبدا = Dest AND مقصد = Origin).

۳. صفحه‌بندی و مرتب‌سازی

  • مرتب‌سازی پیش‌فرض: بر اساس تاریخ شروع (ASC) و سپس شناسه (ASC).
  • اگر action=list باشد، آیتم‌های فچ شده در صفحه جاری، توسط کالکشن لاراول معکوس (Reverse) می‌شوند (نمایش از آخر به اول در همان صفحه).

Response (Success)

{
  "items": [
    {
      "id": 10050,
      "serial": "CHR-123",
      "type": "flight",
      "origin": "THR",
      "destination": "MHD",
      "start": "2024-05-20 10:00:00",
      "status": 1,
      // ... other resource fields
    }
  ],
  "meta": {
    "timestamp": 1715000000,
    "table": {
      "total": 150
    }
  }
}

Flowchart

Start (GET /v2/charter/list)
↓
Set Default Pagination (30 items)
↓
Apply Basic Filters (Serial, Type)
↓
Advanced Filters Logic
Date Logic
↓
If Accomm: Check Overlap
Else: Check Start Date
Roundtrip Logic
↓
If true: (A→B) OR (B→A)
Else: (A→B)
↓
Check Branch (Filter if not ID 1)
↓
Execute Query & Paginate
↓
Action = 'list'?
↓
Yes
↓
Reverse Items Collection
No
↓
Keep Order
↓
Return JSON Resource
Back to top