# 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