Skip to main content
#P1663

GET /v2/charter (Multi‑Mode Charter Loader)

Charter: Get Charter(s) Details

این اندپوینت، هسته اصلی بازیابی اطلاعات چارترهاست. بسته به ورودی، می‌تواند یک چارتر واحد را برگرداند، یا چندین چارتر را به‌صورت آرایه، و همچنین بسته به مقدار action می‌تواند چهار سطح مختلف از داده‌ها را برگرداند: all / list / base / calculations / capacity. این Endpoint از کلاس پیچیده CharterResource استفاده می‌کند که شامل غنی‌سازی بسیار سنگین دیتاست.

Request Overview

URL: /v2/charter
Method: GET
Controller: CharterController@indexCharter
Middleware: authWithJwt

Behavior Summary

  • اگر id یک عدد باشد → فقط یک چارتر را لود می‌کند
  • اگر id آرایه باشد → چندین چارتر را لود می‌کند
  • تمامی رکوردها از جدول charters خوانده می‌شوند
  • داده نهایی با new CharterResource() تبدیل می‌شود

Query Parameters

Field Type Required Description
id integer | array yes شناسه یک چارتر یا چند چارتر
action string optional نوع خروجی را تعیین می‌کند:
all | list | base | calculations | capacity
item_id integer optional فقط در action = capacity

Single Charter Mode

if (is_numeric($request->id)) {
    $charter = DB::table('charters')->where('id', $request->id)->first();
}

اگر یافت نشود:

{
  "status": false,
  "time": 1710000000,
  "message": "item not found!"
}

Multiple Charter Mode

$charters = DB::table('charters')->whereIn('id', $request->id)->get();

همه رکوردها map می‌شوند:

$charters->map(fn($item) => new CharterResource($item))

CharterResource Overview

این کلاس بسیار بزرگ مسئول تبدیل رکورد دیتابیس به ساختارهای کامل، شامل اطلاعات اپراتور، محاسبات، قوانین، آیتم‌ها، ظرفیت رزرو، ویژگی‌ها، و ده‌ها نوع داده متفاوت دیگر است.

Modes (action)

  • all: کامل‌ترین مود. شامل همه موارد: items, calculations, rules, schedule, reservation و …
  • list: نسخه سبک برای لیست‌گیری
  • base: اطلاعات پایه + قوانین + آیتم‌ها
  • calculations: فقط آیتم‌ها و محاسبات مالی
  • capacity: فقط ظرفیت‌های رزرو (با item_id اختیاری)

Shared Data Loaders (Resource Level)

  • اپراتور: جدول operators
  • آیتم‌ها: جدول charter_items
  • محاسبات: جدول {table}_calculation
  • قوانین استرداد: charter_refund_rules
  • قوانین عمومی: charter_public_rules
  • ظرفیت رزرو: ReservationController::capacityItemCharter()
  • اطلاعات کلی: getInformation()
  • نوتیفیکشن زمان‌بندی شده: جدول scheduled_notifications

sortItems() Logic

این تابع یکی از سنگین‌ترین بخش‌هاست و بسته به method/submethod آیتم دیتا را enrich می‌کند:

  • method = route (aircraft, train, bus, ship)
  • method = accommodation
  • method = service
  • method = custom

جزئیات شامل:

  • لینک‌کردن airline، airports، aircraft
  • محاسبه duration از روی دقیقه → فرمت HH:MM
  • لوک‌آپ شرکت‌ها، supplierها و شهرها
  • normalize کردن vehicle و company

sortCalculations() Logic

این قسمت شامل:

  • لود مالیات‌ها: جدول charter_taxes
  • لود خدمات: charter_services + charter_service_categories
  • محاسبات مبتنی بر type و subtype
  • rule mapping برای:
    commission / markup / citizenship
    از جدول charter_financial_handling
  • financial.base = قیمت‌ها
  • financial.staircases
  • financial.taxes
  • financial.commissions
  • financial.markups
  • financial.citizenship

getInformation() Logic

بسته به type → title و blocks متفاوت تولید می‌کند. مقادیر در Redis کش می‌شوند تحت کلید:

charter:{id}:information:title
  • tour → origin, destination, start, end
  • route → origin, destination, start
  • accommodation → destination, start, end (+ hotel title)
  • service → اطلاعات سرویس مثل بیمه/ویزا/CIP

Response Structure (Single Charter, action=all)

{
  "status": true,
  "time": 1710000000,
  "data": {
     "id": 123,
     "serial": 10000 + serial,
     "title": { fa, en },
     "type": "...",
     "subtype": "...",
     "capacity": ...,
     "buy": ...,
     "deadline": ...,
     "information": {...},
     "reservation": {...},
     "calculations": [...],
     "rules": { refund: [...], public: [...] },
     "operator": {...},
     "items": [...],
     "details": {...},
     "plan": ...,
     "slug": ...,
     "hub": ...,
     "schedule": {...} | false,
     "status": ...
  }
}

Error Response

{
  "status": false,
  "time": 1710000000,
  "message": "item not found!"
}

Flowchart

Validate JWT
↓
Check id type (numeric | array)
↓
Load charter(s)
↓
If empty → return 'item not found'
↓
For each → new CharterResource()
↓
Inside Resource → action switch
↓
Load items, rules, calculations, information
↓
SortItems() + SortCalculations()
↓
Return Final JSON
Back to top