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