CharterController.php

فایل یک کنترلر PHP Laravel برای مدیریت چرخه عمر چارترها (پرواز، قطار، هتل) در API پنل مدیریت است.

وظایف کلیدی:

: بازیابی اطلاعات چارترها.
: ایجاد چارترها با تکرار منطقی؛ عملیات در تراکنش پایگاه داده‌ای برای ثبت قیمت، قوانین مالی و کنسلی.
: به‌روزرسانی با بررسی ظرفیت (Capacity Check) برای حفظ فروش‌های قطعی.

این کنترلر با استفاده از تراکنش‌ها و ابزارهایی مانند Jalalian (تاریخ شمسی)، نقشی حیاتی در صحت عملیات فروش سیستم رزرواسیون دارد.

Function indexCharter
Function storeCharter
Function operationCharter
Function updateCharter
Function deleteCharter
Function listCharter
Function listCharterReservation
Function storeCharterReservation
Function transferCharterReservation
Function listWarrantyCharter
Function listPledgerCharter
Function storePledgerCharter
Function deletePledgerCharter
Function getFinancialCharter
Function setCompletionFinancialCharter
Function getAgeTitle
Function listCommunicationsCharter
Function storeCommunicationCharter
Function deleteCommunicationCharter
Function getDetailsCharterItem
Function getTableCharter
Function getConditionCharterItem
Function listPlanCharter
Function setRoomingPlanCharter
Function deleteRoomingPlanCharter
Function getAccommodationRooms
Function setAccommodationRooms
Function getCommunicationsCalculation
Function getCommunicationsCharter
Function updateCharterReservation
Function deleteCharterReservation
Function operationWarrantyCharter
Function listServicesCharter
Function storeRefundCharterReservation

Function indexCharter

· هدف:

این متد کنترلی (Controller Method)، به عنوان یک نقطه پایانی (Endpoint) برای دریافت اطلاعات مربوط به یک یا چند "چارتر" (Charter) از پایگاه داده طراحی شده است. هدف اصلی این است که فرآیند بازیابی داده‌ها را با یک ورودی شناسه (ID) هوشمند کند؛ به طوری که اگر یک شناسه واحد (عددی) ارسال شود، تنها همان رکورد را بازگرداند، و اگر یک آرایه از شناسه‌ها ارسال شود، تمامی رکوردهای منطبق را بازیابی کند. این متد برای اطمینان از سازگاری و ساختاردهی خروجی، از Laravel Resources (CharterResource) برای تبدیل مدل‌های خام پایگاه داده به یک فرمت JSON استاندارد و غنی استفاده می‌کند. در نهایت، پاسخ خروجی همیشه به صورت JSON شامل وضعیت (status)، زمان (timestamp) و داده‌های اصلی (data) ارائه می‌شود.

ویژگی‌ها	توضیحات
هدف کلی	بازیابی اطلاعات یک یا چند رکورد "charter" از جدول `charters` بر اساس شناسه(ها)ی ارسالی در درخواست.
ورودی هوشمند	پشتیبانی از بازیابی بر اساس یک شناسه تکی (با `is_numeric`) یا چندین شناسه (با `whereIn`).
قالب‌بندی خروجی	استفاده از `CharterResource` برای استانداردسازی و قالب‌بندی داده‌های خروجی قبل از ارسال به کلاینت.
مورد استفاده	فراهم کردن یک API منعطف برای سیستم‌های فرانت‌اند که نیاز دارند به طور همزمان یا منفرد، جزئیات چارترها را نمایش دهند.

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

توضیحات	نوع داده	نام پارمتر
شیء درخواست HTTP که حاوی داده‌های ورودی است.	`Request` (Laravel)	$request
array	int	$request->id

· خروجی (Return):

توضیحات	نوع داده
یک پاسخ استاندارد JSON که همیشه شامل کلیدهای `status`, `time` و `data` یا `message` است.	JsonResponse
`status: true` و `data` حاوی یک شیء `CharterResource` یا یک کالکشن از آن.	حالت موفقیت
`status: false` و `message: "item not found!"` در صورتی که شناسه(ها) معتبر باشند اما رکوردی یافت نشود.	حالت عدم یافتن

· مثال استفاده:

// سناریو ۱: درخواست برای یک چارتر با شناسه 12
// متد و آدرس: GET /api/panel/v2/charter/index?id=12

// خروجی مورد انتظار (در صورت موفقیت):
{
    "status": true,
    "time": 1729017600,
    "data": {
        "id": 12,
        "slug": "abc1234",
        "type": "route",
        // ... سایر جزئیات فرمت‌شده توسط CharterResource
    }
}

// ----------------------------------------------------------------

// سناریو ۲: درخواست برای سه چارتر با شناسه‌های 15، 20 و 21
// متد و آدرس: GET /api/panel/v2/charter/index?id[]=15&id[]=20&id[]=21

// خروجی مورد انتظار (در صورت موفقیت):
{
    "status": true,
    "time": 1729017600,
    "data": [
        { "id": 15, /* ... */ },
        { "id": 20, /* ... */ },
        { "id": 21, /* ... */ }
    ]
}

// ----------------------------------------------------------------

// سناریو ۳: درخواست برای یک چارتر با شناسه ناموجود (مثلاً 9999)
// متد و آدرس: GET /api/panel/v2/charter/index?id=9999

// خروجی مورد انتظار:
{
    "status": false,
    "time": 1729017600,
    "message": "item not found!"
}

Function storeCharter

· هدف:

این تابع، موتور اصلی و بسیار پیچیده‌ی ایجاد چارترهای جدید در سیستم است که به عنوان یک نقطه پایانی واحد، قابلیت تعریف انواع مختلف چارتر با پیکربندی‌های گوناگون را فراهم می‌کند. هدف اصلی آن، دریافت یک ساختار داده‌ی پیچیده از کلاینت، پردازش آن بر اساس نوع چارتر (route یا accommodation) و منطق تکرار (repeat)، و در نهایت ثبت مجموعه‌ای از رکوردها در پایگاه داده به صورت اتمی و یکپارچه است. این تابع تمام عملیات‌های خود را درون یک DB::transaction قرار می‌دهد تا اطمینان حاصل شود که یا تمام مراحل (شامل ایجاد چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و دوره‌های تکرار) با موفقیت انجام می‌شوند، یا در صورت بروز کوچکترین خطا، تمام تغییرات به حالت اولیه بازمی‌گردند (rollback). این رویکرد، از ایجاد داده‌های ناقص یا متناقض در دیتابیس جلوگیری می‌کند. این متد همچنین مسئولیت آماده‌سازی داده‌های پیچیده‌ای مانند مسیرهای رفت و برگشت (inbound/outbound) و تولید تاریخ‌های تکرار بر اساس الگوهای مختلف (dates, weekly, periodic) را بر عهده دارد و در نهایت، خلاصه‌ای از شناسه‌های ایجاد شده را به عنوان خروجی بازمی‌گرداند.

ویژگی‌ها	توضیحات
هدف کلی	ایجاد یک یا چند چارتر بر اساس تنظیمات ورودی، شامل نوع، جزئیات مسیر/اقامتگاه و الگوی تکرار.
عملیات اتمی (Atomic)	استفاده از `DB::transaction` برای تضمین یکپارچگی داده‌ها؛ تمام عملیات یا با هم موفق می‌شوند یا با هم لغو می‌گردند.
پشتیبانی از انواع چارتر	مدیریت منطق متفاوت برای چارترهای `route` (پرواز، قطار، اتوبوس) و `accommodation` (هتل).
موتور تکرار (Repeat Engine)	قابلیت ایجاد چارترها بر اساس یک الگوی تکرار: لیست تاریخ‌های مشخص (`dates`)، روزهای هفتگی (`weekly`) یا دوره‌های زمانی متناوب (`periodic`).
ساختار داده پیچیده	پردازش ساختارهای تو در تو برای جزئیات مسیر، کلاس‌های قیمتی (`calculations`)، مالیات‌ها (`taxes`) و اطلاعات مالی (`financial`).
پاک‌سازی کش	پس از ایجاد موفقیت‌آمیز، کلیدهای مرتبط در Redis را حذف می‌کند تا اطمینان حاصل شود که داده‌های جدید در پاسخ‌های بعدی لحاظ می‌شوند.

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

توضیحات	نوع داده	نام پارمتر
آبجکت اصلی درخواست حاوی تمام داده‌های لازم برای ایجاد چارتر.	`Illuminate\Http\Request`	`$request`
کلید اصلی. نوع چارتر را مشخص می‌کند. مقادیر معتبر: `'route'` یا `'accommodation'`.	`string`	`$request->type`
(برای `type: 'route'`) نوع وسیله نقلیه را مشخص می‌کند: `'aircraft'`, `'train'`, `'bus'`.	`string`	`$request->subtype`
آرایه‌ای حاوی جزئیات اصلی چارتر، مانند مبدأ، مقصد، تاریخ و اطلاعات وسیله نقلیه.	`array`	`$request->items`
مهم. آرایه‌ای از آبجکت‌ها که کلاس‌های مختلف قیمتی و ظرفیتی چارتر را تعریف می‌کنند.	`array`	`$request->calculations`
(اختیاری) آبجکتی که منطق تکرار چارتر را مشخص می‌کند. شامل `type` (مانند `'weekly'`) و جزئیات مربوطه.	`object`	`$request->repeat`
(برای `type: 'accommodation'`) شامل `start` و `end` برای محدوده تاریخ اقامت.	`object`	`$request->date_range`
سایر فیلدها مانند `capacity`, `description`, `permissions` و غیره.	`...`	`...`

· خروجی (Return):

توضیحات نوع داده

یک پاسخ JSON که در صورت موفقیت، حاوی یک آرایه با کلیدهای main، calculations، taxes و financial است. این کلیدها به ترتیب شناسه‌های ایجاد شده برای چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و اطلاعات مالی را در خود جای داده‌اند. در صورت بروز خطا، یک پاسخ با کد وضعیت 500 و پیام خطا برگردانده می‌شود. Illuminate\Http\JsonResponse

توضیحات	نوع داده
یک پاسخ JSON که در صورت موفقیت، حاوی یک آرایه با کلیدهای `main`، `calculations`، `taxes` و `financial` است. این کلیدها به ترتیب شناسه‌های ایجاد شده برای چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و اطلاعات مالی را در خود جای داده‌اند. در صورت بروز خطا، یک پاسخ با کد وضعیت `500` و پیام خطا برگردانده می‌شود.	`Illuminate\Http\JsonResponse`

· مثال استفاده:

// سناریو: ایجاد یک چارتر پرواز هفتگی برای روزهای شنبه و دوشنبه
// POST /api/panel/v2/charter/store
// Body (JSON):
{
    "type": "route",
    "subtype": "aircraft",
    "capacity": 180,
    "description": "چارتر هفتگی تهران-مشهد",
    "permissions": { /* ... */ },
    "repeat": {
        "type": "weekly",
        "from": "1404/08/01",
        "to": "1404/08/30",
        "days": [6, 1] // شنبه و دوشنبه
    },
    "items": [
        {
            "details": {
                "origin": { "id": 1, "name": "THR" },
                "destination": { "id": 2, "name": "MHD" },
                "datetime": "1404/08/04 10:30", // تاریخ یکی از روزهای الگو (یک‌شنبه)
                "vehicle": { /* ... */ }
            }
        }
    ],
    "calculations": [
        {
            "name": "اکونومی",
            "capacity": 150,
            "financial": { /* ... */ }
        },
        {
            "name": "بیزنس",
            "capacity": 30,
            "financial": { /* ... */ }
        }
    ]
}

// خروجی مورد انتظار (در صورت موفقیت):
{
    "main": [101, 102, 103, ...], // شناسه‌های چارترهای اصلی ایجاد شده برای هر تاریخ
    "calculations": [201, 202, 203, ...], // شناسه‌های کلاس‌های قیمتی
    "taxes": [301, 302, ...], // شناسه‌های مالیات‌ها
    "financial": [401, 402, ...] // شناسه‌های اطلاعات مالی
}

Function operationCharter

· هدف:

این تابع به عنوان یک مرکز عملیاتی چندمنظوره برای مدیریت و به‌روزرسانی چارترهای موجود طراحی شده است. برخلاف storeCharter که وظیفه ایجاد را بر عهده دارد، operationCharter مسئول رسیدگی به اقدامات (actions) مختلفی است که می‌توان روی یک چارتر از قبل ایجاد شده انجام داد. این متد با دریافت یک پارامتر action در درخواست، منطق خود را تغییر می‌دهد تا عملیات‌های متفاوتی را اجرا کند. در حال حاضر، این تابع دو اقدام اصلی را پشتیبانی می‌کند: base برای به‌روزرسانی اطلاعات پایه‌ای و کلی چارتر (مانند ظرفیت کل، توضیحات، دوره‌های زمانی و مجوزهای فروش) و calculations برای مدیریت پیچیده‌ی کلاس‌های قیمتی و ظرفیتی چارتر. این مدیریت شامل به‌روزرسانی کلاس‌های موجود، حذف کلاس‌هایی که فروش قطعی ندارند، و افزودن کلاس‌های جدید است. این تابع با بررسی‌های دقیق امنیتی، مانند جلوگیری از کاهش ظرفیت به میزانی کمتر از فروش قطعی، یکپارچگی داده‌ها را در حین عملیات ویرایش تضمین می‌کند و از بروز ناسازگاری در سیستم جلوگیری می‌نماید.

ویژگی‌ها	توضیحات
هدف کلی	اجرای عملیات‌های مختلف (مانند ویرایش اطلاعات پایه یا مدیریت کلاس‌های قیمتی) بر روی یک چارتر موجود.
ورودی هوشمند	استفاده از پارامتر `action` برای مسیریابی درخواست به منطق مربوطه در داخل یک تابع واحد.
ابزارهای اصلی	کوئری‌بیلدر لاراول (`DB::table`), استفاده از توابع کمکی (`ReservationController::capacityItemCharter`), مدیریت Redis برای پاک کردن کش.
فرمت خروجی	پاسخ‌های متنوع `JsonResponse` که شامل پیام موفقیت، خطا یا هشدارهای خاص (مثلاً عدم امکان حذف کلاس به دلیل فروش) است.
امنیت داده	شامل منطق‌های کنترلی برای جلوگیری از عملیات‌های مخرب، مانند حذف کلاسی که رزرو فعال دارد یا کاهش ظرفیت کلی به کمتر از تعداد فروخته شده.

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

توضیحات	نوع داده	نام پارمتر
آبجکت اصلی درخواست که حاوی تمام داده‌های ارسالی از سمت کلاینت است.	`Illuminate\Http\Request`	`$request`
مهم‌ترین کلید. نوع عملیات را مشخص می‌کند. مقادیر معتبر: `'base'` یا `'calculations'`.	`string`	`$request->action`
شناسه اصلی چارتری که عملیات روی آن انجام می‌شود.	`number`	`$request->main_id`
(در `action: 'base'`) ظرفیت کل جدید چارتر.	`number`	`$request->capacity`
(در `action: 'calculations'`) آرایه‌ای از آبجکت‌های کلاس‌های قیمتی برای به‌روزرسانی یا افزودن.	`array`	`$request->calculations`
(در `action: 'calculations'`) آبجکتی شامل آرایه‌ای از شناسه‌هایی که باید حذف شوند (مانند `calculations`, `taxes`, `financial`).	`object`	`$request->deleted`
سایر فیلدها مانند `capacity`, `description`, `permissions` و غیره.	`...`	`...`

· خروجی (Return):

توضیحات	نوع داده
یک پاسخ استاندارد در قالب JSON. در صورت موفقیت، معمولاً یک پیام ساده برمی‌گرداند. در صورت بروز خطا (مثلاً تلاش برای کاهش ظرفیت نامعتبر)، یک پاسخ با کد وضعیت HTTP `4xx` و پیام خطای دقیق برای کاربر ارسال می‌کند.	`Illuminate\Http\JsonResponse`

· مثال استفاده:

// سناریو ۱: به‌روزرسانی توضیحات و ظرفیت کلی یک چارتر
// POST /api/panel/v2/charter/operation
// Body (JSON):
{
    "action": "base",
    "main_id": 45,
    "description": "توضیحات جدید برای این چارتر",
    "capacity": 150
}

// خروجی مورد انتظار: یک پاسخ موفقیت‌آمیز با کد 200 و پیام تایید.

// ----------------------------------------------------------------

// سناریو ۲: حذف یک کلاس قیمتی و به‌روزرسانی یک کلاس دیگر
// POST /api/panel/v2/charter/operation
// Body (JSON):
{
    "action": "calculations",
    "main_id": 45,
    "type": "route",
    "deleted": {
        "calculations": [101] // درخواست حذف کلاس با شناسه 101
    },
    "calculations": [
        {
            "id": 102, // به‌روزرسانی کلاس با شناسه 102
            "financial": { "base": { "adult_price": 2500000 } }
            // ... سایر جزئیات
        }
    ]
}

// خروجی احتمالی (در صورت داشتن فروش در کلاس 101):
// HTTP Status 409 Conflict
{
    "error": {
        "code": 1000,
        "message": "کلاس [نام کلاس] دارای فروش قطعی (5) می باشد. لطفا قبل از انجام هر عملیاتی فروش ها را به کلاس دیگری انتقال دهید."
    }
}

Function updateCharter

· هدف:

این متد به عنوان یک نقطه پایانی چندمنظوره برای به‌روزرسانی وضعیت (status) و مجوزهای فروش (sell) یک چارتر موجود عمل می‌کند. منطق اصلی آن بر اساس پارامتر action در درخواست ورودی ('status' یا 'sell') شاخه‌بندی می‌شود. در حالت status، متد بررسی‌های امنیتی مهمی را انجام می‌دهد؛ به عنوان مثال، از حذف (تغییر وضعیت به 4) چارتری که دارای رزروهای فروخته شده است، جلوگیری می‌کند و همچنین تغییر وضعیت چارتری که قبلاً پایان یافته (وضعیت 3)، را غیرممکن می‌سازد. این کار پایداری و یکپارچگی داده‌های مالی و ظرفیتی را تضمین می‌کند. در حالت sell، این متد به سادگی مجوزهای فروش به همکار (colleague_sell) یا هاب (hub_sell) را بر اساس داده‌های ورودی، فعال یا غیرفعال می‌کند. در نهایت، پس از هر به‌روزرسانی موفق، کلید کش مربوط به عنوان چارتر در Redis را حذف می‌کند تا اطمینان حاصل شود که در درخواست‌های بعدی، اطلاعات به‌روز شده بازخوانی خواهد شد.

ویژگی‌ها	توضیحات
هدف کلی	مدیریت به‌روزرسانی‌های خاص و محدود برای یک چارتر، مانند وضعیت و مجوزهای فروش.
منطق اصلی	استفاده از `if-else` بر روی پارامتر `action` برای تفکیک عملیات.
بررسی‌های امنیتی	جلوگیری از حذف چارتری که فروش قطعی دارد (`status: 4`).
`...`	جلوگیری از تغییر وضعیت چارتری که پایان یافته است (`status: 3`).
مدیریت کش	حذف کلید `Redis` مربوط به عنوان چارتر (`charter:{id}:information:title`) پس از به‌روزرسانی برای اطمینان از تازگی داده‌ها.
خطایابی	بازگرداندن پاسخ‌های خطای `422` (Unprocessable Entity) و `404` (Not Found) با پیام‌های واضح در صورت نقض قوانین یا عدم وجود چارتر.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
آبجکت اصلی درخواست حاوی تمام داده‌های لازم برای ایجاد چارتر.	`Route/Body`	`integer`	`$request->id`
نوع عملیات را مشخص می‌کند. مقادیر معتبر: `'status'` یا `'sell'`.	Body	`string`	`$request->action`
آرایه‌ای حاوی داده‌های لازم برای به‌روزرسانی. ساختار آن به `action` بستگی دارد.	Body	`array`	`$request->data`

ساختار $request->data بر اساس action:

اگر action برابر با 'status' باشد:
$request->data['status']: integer - وضعیت جدید چارتر (مثلاً 0, 1, 2, 3, 4).
اگر action برابر با 'sell' باشد:
$request->data['colleague']: boolean - فعال یا غیرفعال کردن مجوز فروش به همکاران.
$request->data['hub']: boolean - فعال یا غیرفعال کردن مجوز فروش به هاب.

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content` بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا (مانند یافت نشدن چارتر یا نقض قوانین)، یک آبجکت `JSON` با کد `4xx` و پیام خطا بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو ۱: تغییر وضعیت یک چارتر به “کنسل شده”

Request:
id: 125
action: “status”
data: { "status": 4 }
Action:

متد ابتدا ظرفیت فروخته شده چارتر 125 را بررسی می‌کند.
فرض: هیچ بلیتی فروخته نشده است (capacity['total'] == capacity['capacity']).
وضعیت چارتر در دیتابیس به 4 تغییر می‌کند.
کلید Redis مربوط به charter:125:information:title حذف می‌شود.

Response:
HTTP Status: 204 No Content

سناریو ۲: تلاش برای کنسل کردن چارتری که فروش داشته است

Request:
id: 126
action: “status”
data: { "status": 4 }
Action:

متد ظرفیت فروخته شده چارتر 126 را بررسی می‌کند.
فرض: چند بلیت فروخته شده است (capacity['total'] != capacity['capacity']).
عملیات متوقف می‌شود.

Response:
HTTP Status: 422 Unprocessable Entity
Body:

json

        {
            "error": {
                "code": 1000,
                "message": "بر روی این چارتر رزرو انجام شده است و امکان حذف وجود ندارد."
            }
        }

سناریو ۳: فعال کردن فروش برای همکاران

Request:
id: 127
action: “sell”
data: { "colleague": true }
Action:

مقدار فیلد colleague_sell برای چارتر 127 در دیتابیس به 1 تغییر می‌کند.
کلید Redis مربوط به charter:127:information:title حذف می‌شود.

Response:
HTTP Status: 204 No Content

Function deleteCharter

· هدف:

این متد مسئولیت حذف کامل و دائمی یک چارتر و تمام داده‌های وابسته‌ی آن از سیستم را بر عهده دارد. عملکرد این تابع بسیار حساس و حیاتی است، زیرا قبل از اقدام به حذف، یک بررسی امنیتی کلیدی انجام می‌دهد: با فراخوانی تابع getCharterCapacity، ظرفیت فروخته‌شده‌ی چارتر را استعلام می‌کند. اگر حتی یک صندلی یا اتاق از چارتر فروخته شده باشد (یعنی ظرفیت کل با ظرفیت باقیمانده برابر نباشد)، متد عملیات را متوقف کرده و با یک خطای 409 Conflict به کاربر اطلاع می‌دهد که حذف به دلیل وجود رزروهای قطعی ممکن نیست. در صورت موفقیت‌آمیز بودن این بررسی، متد با استفاده از یک DB::transaction، حذف آبشاری داده‌ها را تضمین می‌کند. ابتدا خود رکورد چارتر از جدول charters حذف می‌شود، سپس تمام رکوردهای مرتبط در جداول charter_items و charter_calculations نیز پاک می‌شوند. این رویکرد تراکنشی، یکپارچگی دیتابیس را حفظ می‌کند و از باقی ماندن داده‌های یتیم (Orphaned Data) جلوگیری می‌نماید.

ویژگی‌ها	توضیحات
هدف کلی	حذف کامل و دائمی یک چارتر و تمام موجودیت‌های مرتبط با آن.
نوع حذف	حذف فیزیکی (Hard Delete) از دیتابیس، نه حذف منطقی (Soft Delete).
بررسی امنیتی	جلوگیری قاطع از حذف چارتری که دارای فروش قطعی است.
یکپارچگی داده	استفاده از `DB::transaction` برای تضمین حذف اتمیک (موفقیت یا شکست کامل عملیات).
حذف آبشاری	حذف رکوردهای وابسته از جداول `charter_items` و `charter_calculations`.
خطایابی	بازگرداندن خطای `409 Conflict` با پیام واضح در صورت نقض قانون فروش.
بازخورد موفقیت	ارسال پاسخ `204 No Content` در صورت موفقیت‌آمیز بودن عملیات حذف.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه منحصر به فرد چارتری که باید حذف شود.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content` بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`
در صورت وجود رزرو روی چارتر، یک آبجکت `JSON` با کد `409 Conflict` و پیام خطا بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`
در صورت بروز خطای غیرمنتظره در حین تراکنش دیتابیس، یک آبجکت `JSON` با کد `400 Bad Request` و جزئیات استثناء (Exception) بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو ۱: حذف موفق یک چارتر بدون فروش

Request:
id: 350
Action:

متد ظرفیت چارتر با شناسه 350 را بررسی می‌کند.
فرض: هیچ رزروی ثبت نشده است (capacity['total'] == capacity['capacity']).
یک تراکنش دیتابیس آغاز می‌شود.
رکوردها از charter_items و charter_calculations که main_id آن‌ها 350 است، حذف می‌شوند.
رکورد اصلی از جدول charters با شناسه 350 حذف می‌شود.
تراکنش با موفقیت commit می‌شود.

Response:
HTTP Status: 204 No Content

سناریو ۲: تلاش برای حذف چارتری که فروش داشته است

Request:
id: 351
Action:

متد ظرفیت چارتر با شناسه 351 را بررسی می‌کند.
فرض: تعدادی رزرو ثبت شده است (capacity['total'] != capacity['capacity']).
عملیات متوقف شده و هیچ تغییری در دیتابیس اعمال نمی‌شود.

Response:
HTTP Status: 409 Conflict
Body:

json

        {
            "error": {
                "code": 1000,
                "message": "بر روی این چارتر رزرو انجام شده است و امکان حذف وجود ندارد."
            }
        }

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:

متد listCharter اجرا می‌شود.
کوئری اصلی به جدول charters اعمال می‌شود.
فیلتر where('type', 'route') و where('subtype', 'aircraft') اعمال می‌شود.
فیلتر where('origin', 1) و where('destination', 2) اعمال می‌شود.
فیلتر whereBetween('start', ['2025-10-16 00:00:00', '2025-10-23 23:59:59']) اعمال می‌شود.
فیلتر whereIn('status', [1, 3]) برای وضعیت active اعمال می‌شود.
نتایج بر اساس تاریخ شروع مرتب شده و ۱۰ مورد اول بازگردانده می‌شود.

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
                }
            }
        }

Function listCharterReservation

· هدف:

این متد به عنوان یک مرکز گزارش‌گیری برای انواع مختلف رزروها و موجودیت‌های مرتبط با یک چارتر خاص عمل می‌کند. بر اساس پارامتر type که از طریق URL دریافت می‌شود، متد می‌تواند لیست رزروهای قطعی (definite)، موقت (temporary)، استرداد شده (refund)، حذف شده (deleted)، یا لیست گارانتی‌ها (warranty) و حتی مسافران بر اساس پلن اتاق‌بندی (plan) را استخراج کند. برای رزروهای قطعی (definite)، قابلیت فیلتر پیشرفته بر اساس بازه زمانی و نوع گزارش (check_in, check_out, guests) وجود دارد که امکان تهیه گزارش‌های دقیق از وضعیت حضور مسافران در یک هتل را فراهم می‌سازد. این تفکیک منطقی، پیچیدگی را کاهش داده و واکشی داده‌های مرتبط با یک چارتر را بسیار ساده و بهینه می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	واکشی لیست‌های مختلف مرتبط با یک چارتر (رزرو، گارانتی، استرداد و…).
مرکز عملیات	استفاده از پارامتر `type` در URL برای تعیین نوع داده درخواستی.
انواع گزارش	`definite`, `temporary`, `refund`, `warranty`, `deleted`, `plan`.
فیلتر پیشرفته (برای `definite`)	فیلتر بر اساس بازه زمانی (`from`, `to`) و نوع گزارش (`check_in`, `check_out`, `guests`).
انتخاب جدول پویا	استفاده از تابع کمکی `getTableCharter` برای یافتن جدول رزرو صحیح (بر اساس نوع چارتر).
یکپارچگی خروجی	استفاده از `ReservationResource::collection` برای فرمت‌دهی استاندارد لیست رزروها.
خطایابی	مدیریت خطا برای درخواست‌های نامعتبر (مثلاً درخواست `plan` برای چارتری غیر از اقامتگاه).

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی که گزارش‌ها از آن استخراج می‌شود.	`Route`	`Illuminate\Http\Request`	`$id`
نوع گزارش درخواستی. مقادیر معتبر: `definite`, `temporary`, `refund`, `warranty`, `deleted`, `plan`.	`Route`	`string`	`$type`
(اختیاری) تاریخ شروع بازه برای فیلتر رزروهای `definite`.	`Query`	`string (date)`	`advanced[from]`
(اختیاری) تاریخ پایان بازه برای فیلتر رزروهای `definite`.	`Query`	`string (date)`	`advanced[to]`
(اختیاری) نوع گزارش تاریخ برای `definite`. مقادیر: `check_in`, `check_out`, `guests`.	`Query`	`string`	`advanced[report_type]`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` حاوی کلید `items` (لیست نتایج) و `meta` (شامل `timestamp`). برای `definite`، نتایج با `ReservationResource` فرمت می‌شوند.	`Illuminate\Http\JsonResponse`
در صورت خطا (مثلاً درخواست `plan` برای چارتر مسیر)، یک پاسخ با کد `409 Conflict` و پیام خطا بازگردانده می‌شود.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو ۱: دریافت لیست مسافرانی که در یک هتل در بازه زمانی مشخصی اقامت دارند

Request URL: /api/panel/v2/charter/380/definite/list?advanced[from]=2025-10-20&advanced[to]=2025-10-25&advanced[report_type]=guests
Action:

متد با $id=380 و $type='definite' فراخوانی می‌شود.
جدول رزرو مربوط به چارتر 380 (فرضاً charter_accommodation_reservation) مشخص می‌شود.
کوئری برای واکشی رزروهای قطعی (refund_id و deleted_at برابر null) اجرا می‌شود.
شرط WHERE checkin_date <= '2025-10-25' AND checkout_date > '2025-10-20' اعمال می‌شود.
نتایج با ReservationResource فرمت شده و بازگردانده می‌شوند.

Response:
HTTP Status: 200 OK
Body: {"items": [{...reservation 1...}, {...reservation 2...}], "meta": {...}}

سناریو ۲: دریافت لیست گارانتی‌های ثبت شده برای یک چارتر

Request URL: /api/panel/v2/charter/412/warranty/list
Action:

متد با $id=412 و $type='warranty' فراخوانی می‌شود.
کوئری به جدول charter_warranties با شرط main_id = 412 اجرا می‌شود.

Response:
HTTP Status: 200 OK
Body: {"items": [{...warranty 1...}, {...warranty 2...}], "meta": {...}}

Function storeCharterReservation

· هدف:

این متد به عنوان نقطه ورودی اصلی برای ثبت رزروهای جدید (یک یا چند مسافر) بر روی یک چارتر عمل می‌کند. منطق اصلی آن شامل اعتبارسنجی‌های چند لایه است: ابتدا با استفاده از ReservationController::capacityItemCharter ظرفیت خالی چارتر را بررسی می‌کند. سپس برای هر مسافر، اعتبارسنجی داده‌های هویتی (کد ملی، پاسپورت) را با Validator::checkIdentity انجام می‌دهد و مسافر را در جدول passengers درج یا به‌روزرسانی می‌کند. متد می‌تواند رزروهای عادی (با محاسبه قیمت از ReservationController::financialCalculation) و رزروهای اعتباری/گارانتی (که اطلاعات مالی مستقیماً در ورودی ارائه شده) را مدیریت کند. تمام رزروهای موفق در یک آرایه جمع‌آوری شده و در پاسخ نهایی به همراه شناسه‌های رزرو و PNR محلی بازگردانده می‌شوند. در صورت بروز خطا برای هر مسافر، اطلاعات خطا به جای نتیجه موفق در آرایه خروجی قرار می‌گیرد.

ویژگی‌ها	توضیحات
هدف کلی	ثبت یک یا چند رزرو جدید برای یک آیتم چارتر مشخص.
اعتبارسنجی ظرفیت	بررسی ظرفیت باقیمانده قبل از هرگونه پردازش.
مدیریت مسافر	اعتبارسنجی و درج/به‌روزرسانی اطلاعات مسافر در جدول `passengers`.
رزرو گروهی	قابلیت پردازش و ثبت چندین مسافر در یک درخواست.
مدیریت مالی	پشتیبانی از رزروهای عادی (محاسبه قیمت) و اعتباری (قیمت از پیش تعیین‌شده).
مدیریت استرداد در فایل	قابلیت ثبت مسافر با وضعیت “استرداد شده” از طریق فایل اکسل (`status == 'refund'`).
ایجاد PNR	تولید شماره PNR محلی منحصر به فرد برای هر رزرو.
پاسخ تفصیلی	بازگرداندن آرایه‌ای از نتایج که هر آیتم وضعیت موفقیت یا شکست رزرو یک مسافر را نشان می‌دهد.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی.	`Body`	`integer`	`$request->main_id`
شناسه آیتم محاسباتی چارتر (کلاس پرواز/اتاق هتل).	`Body`	`integer`	`$request->item_id`
آرایه‌ای از آبجکت‌های مسافر برای ثبت.	`Body`	`array`	`$request->passengers`

ساختار آبجکت مسافر در آرایه $request->passengers:

identity: array - اطلاعات هویتی (کد ملی، پاسپورت، نام، …).
email: string - ایمیل مسافر.
mobile: string - شماره موبایل مسافر.
age_title: string - گروه سنی (adult, child, infant).
status: string - وضعیت رزرو (مثلاً definite, refund).
financial: array (اختیاری) - اگر ارائه شود، رزرو به صورت اعتباری/گارانتی با قیمت‌های مشخص ثبت می‌شود. شامل supplier, sale_price, commission.

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک آبجکت JSON با کلید `items` که آرایه‌ای از نتایج هر رزرو است. هر نتیجه موفق شامل `status: true` و آبجکت `pnr` (حاوی `local`, `original`, `id`) می‌باشد. نتایج ناموفق شامل `status: false` و جزئیات خطا هستند. کد پاسخ `201 Created`.	`Illuminate\Http\JsonResponse`
در صورت پر بودن ظرفیت، یک پاسخ با کد `422 Unprocessable Entity` و پیام خطا.	`Illuminate\Http\JsonResponse`
در صورت بروز خطای کلی، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: ثبت دو مسافر (یک عادی، یک اعتباری) روی یک پرواز

Request Body:

json

    {
        "main_id": 450,
        "item_id": 980,
        "passengers": [
            { "identity": {...}, "age_title": "adult", "status": "definite" },
            { "identity": {...}, "age_title": "adult", "status": "definite", "financial": { "supplier": 22, "sale_price": 1500000, "commission": 50000 } }
        ]
    }

Action:

ظرفیت آیتم 980 از چارتر 450 بررسی می‌شود. فرضاً ظرفیت کافی است.
مسافر اول: اطلاعات هویتی اعتبارسنجی می‌شود. financialCalculation برای محاسبه قیمت فراخوانی می‌شود. رزرو در جدول مربوطه درج می‌شود.
مسافر دوم: اطلاعات هویتی اعتبارسنجی می‌شود. چون financial وجود دارد، قیمت‌ها مستقیماً از ورودی خوانده شده و رزرو به عنوان اعتباری ثبت می‌شود.
برای هر دو رزرو موفق، PNR محلی تولید می‌شود.

Response:
HTTP Status: 201 Created
Body:

json

        {
            "items": [
                { "status": true, "pnr": { "local": "CH-101", "original": "...", "id": 11234 } },
                { "status": true, "pnr": { "local": "CH-102", "original": "...", "id": 11235 } }
            ],
            "meta": { "timestamp": ... }
        }

Function transferCharterReservation

· هدف:

این متد برای انتقال یک یا چند رزرو از یک آیتم چارتر (مثلاً یک کلاس پروازی) به آیتم چارتری دیگر (مثلاً کلاس پروازی متفاوت در همان پرواز یا پروازی دیگر) طراحی شده است. منطق اصلی آن بر پایه اعتبارسنجی ظرفیت مقصد استوار است. قبل از هر اقدامی، متد با فراخوانی ReservationController::capacityItemCharter، ظرفیت خالی آیتم مقصد (goal) را بررسی می‌کند. اگر ظرفیت مقصد برای پذیرش تعداد رزروهای در حال انتقال کافی باشد، متد در یک حلقه، شناسه‌های main_id و item_id هر رزرو را به شناسه‌های آیتم مقصد به‌روزرسانی می‌کند. این عملیات به صورت اتمیک برای هر رزرو انجام می‌شود. در صورتی که ظرفیت مقصد کافی نباشد، عملیات متوقف شده و یک خطای 422 بازگردانده می‌شود تا از ایجاد وضعیت ناهماهنگ در داده‌ها جلوگیری شود.

ویژگی‌ها	توضیحات
هدف کلی	انتقال رزرو(ها) از یک آیتم چارتر به آیتم دیگر.
اعتبارسنجی ظرفیت	بررسی دقیق ظرفیت آیتم مقصد قبل از شروع عملیات انتقال.
انتقال گروهی	قابلیت انتقال چندین رزرو در یک درخواست واحد.
عملیات اصلی	به‌روزرسانی فیلدهای `main_id` و `item_id` در رکوردهای جدول رزرو.
ایمنی	جلوگیری از انتقال در صورت عدم وجود ظرفیت کافی در مقصد.
خطایابی	بازگرداندن پاسخ `422 Unprocessable Entity` با پیام واضح در صورت کمبود ظرفیت.
پاسخ موفقیت	بازگرداندن پاسخ `204 No Content` در صورت انتقال موفقیت‌آمیز.

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

توضیحات		نوع داده	نام پارمتر
آرایه‌ای از شناسه‌های رزروهایی که باید منتقل شوند.	`Body`	`array`	`$request->items`
آبجکتی که آیتم مقصد را مشخص می‌کند.	`Body`	`array`	`$request->goal`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content`.	`Illuminate\Http\JsonResponse`
در صورت کمبود ظرفیت در مقصد، یک پاسخ با کد `422 Unprocessable Entity` و پیام خطا.	`Illuminate\Http\JsonResponse`
در صورت بروز خطای عمومی، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: انتقال دو مسافر از کلاس اکونومی به بیزنس در یک پرواز

Request Body:

json

    {
        "items": [5432, 5433],
        "goal": {
            "main_id": 450,
            "item_id": 981
        }
    }

Action:

متد ظرفیت آیتم 981 (کلاس بیزنس) از چارتر 450 را بررسی می‌کند.
فرض: ظرفیت خالی بیشتر از ۲ نفر است.
متد یک حلقه روی items اجرا می‌کند.
برای رزرو 5432: UPDATE charter_route_reservation SET main_id=450, item_id=981 WHERE id=5432.
برای رزرو 5433: UPDATE charter_route_reservation SET main_id=450, item_id=981 WHERE id=5433.

Response:
HTTP Status: 204 No Content

Function listWarrantyCharter

· هدف:

این متد وظیفه واکشی و آماده‌سازی لیست گارانتی‌های مرتبط با یک چارتر خاص را بر عهده دارد. پس از استخراج رکوردهای گارانتی از جدول charter_warranties، متد برای هر گارانتی، اطلاعات تکمیلی مهمی را از منابع دیگر واکشی و به آبجکت خروجی ضمیمه می‌کند. اولاً، اطلاعات گارانتی‌کننده (همکار) را با اولویت از کش Redis (colleagues:{id}) می‌خواند و در صورت عدم وجود، از دیتابیس استعلام کرده و در کش ذخیره می‌کند. ثانیاً، اگر چارتر از نوع اقامتی باشد، جزئیات اتاق‌های گارانتی شده (مانند تعداد، کلاس و…) را از جدول charter_warranty_accommodation_rooms استخراج می‌کند. در نهایت، با فراخوانی ReservationController::capacityItemCharter، ظرفیت فعلی آیتم‌های گارانتی شده را محاسبه کرده و به خروجی اضافه می‌کند. این فرآیند یک نمای کامل و جامع از هر گارانتی، شامل جزئیات مالی، اطلاعات گارانتی‌کننده، ظرفیت و اتاق‌های مرتبط را فراهم می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	واکشی و نمایش لیست کامل گارانتی‌های یک چارتر.
واکشی اصلی	استعلام از جدول `charter_warranties` بر اساس `main_id`.
بهینه‌سازی با کش	خواندن اطلاعات گارانتی‌کننده (همکار) از Redis و ذخیره‌سازی در صورت نیاز.
اطلاعات تکمیلی	ضمیمه کردن جزئیات اتاق‌های گارانتی شده برای چارتراهای اقامتی.
محاسبه ظرفیت	محاسبه و افزودن ظرفیت فعلی (کل، باقیمانده، فروخته‌شده) برای هر آیتم گارانتی.
خروجی جامع	تجمیع اطلاعات از جداول و کش‌های مختلف برای ارائه یک آبجکت کامل.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی که لیست گارانتی‌های آن مورد نیاز است.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `items` (آرایه‌ای از آبجکت‌های گارانتی) و `meta`. هر آبجکت گارانتی شامل اطلاعات اصلی، آبجکت `guarantor`، آرایه `rooms` (در صورت وجود) و آبجکت `capacity` است.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: مشاهده لیست گارانتی‌های یک چارتر هتل

Request:
id: 620
Action:

متد تمام رکوردها از charter_warranties با main_id=620 را واکشی می‌کند.
برای هر گارانتی (فرضاً شناسه گارانتی 15 و guarantor آن 22 است):

a. اطلاعات همکار 22 از Redis خوانده می‌شود.

b. تمام رکوردها از charter_warranty_accommodation_rooms با warranty_id=15 واکشی می‌شود.

c. ظرفیت آیتم‌های مرتبط با این گارانتی محاسبه می‌شود.

تمام این اطلاعات در یک آبجکت جامع تجمیع شده و به لیست خروجی اضافه می‌شود.

Response:
HTTP Status: 200 OK
Body:

json

        {
            "items": [
                {
                    "id": 15,
                    "main_id": 620,
                    "amount": 50000000,
                    "guarantor": { "id": 22, "title_fa": "آژانس الف", ... },
                    "rooms": [ { "item_id": 110, "capacity": 5, ... }, { "item_id": 112, "capacity": 3, ... } ],
                    "capacity": { "item_110": { "total": 5, "balance": 2, ... }, "item_112": { "total": 3, "balance": 3, ... } }
                }
            ],
            "meta": { "timestamp": ... }
        }

Function listPledgerCharter

· هدف:

این متد برای واکشی لیستی از “متعهدان” (Pledgers) فعال در یک شعبه خاص طراحی شده است. متعهدان در اینجا همکارانی (Colleagues) هستند که به صورت رسمی در جدول charter_pledgers ثبت شده‌اند. هدف اصلی، تهیه یک لیست ساده و کارآمد برای استفاده در فرم‌ها و منوهای کشویی است که نیاز به انتخاب یک متعهد دارند. کوئری به طور همزمان به جداول charter_pledgers و colleagues متصل می‌شود و فقط رکوردهایی را بازمی‌گرداند که هم متعهد و هم خود همکار فعال باشند (status=1). خروجی برای استفاده آسان در فرانت‌اند بهینه‌سازی شده و شامل شناسه متعهد، شناسه همکار و یک آبجکت title با نسخه‌های فارسی و انگلیسی نام دفتر و نام کامل شخص است.

ویژگی‌ها	توضیحات
هدف کلی	تهیه لیست متعهدان (همکاران) فعال یک شعبه برای استفاده در UI.
فیلتر وضعیت	واکشی متعهدانی که هم خودشان و هم پروفایل همکارشان فعال است.
فیلتر شعبه	محدود کردن نتایج به شعبه کاربر درخواست‌دهنده (`$request->get('branch')`).
بهینه‌سازی خروجی	فرمت‌دهی داده‌ها برای نمایش ساده در لیست‌ها (شامل `id` و `title`).
تجمیع نام	ایجاد عنوان فارسی و انگلیسی با ترکیب نام دفتر و نام و نام خانوادگی.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه شعبه کاربر که به صورت خودکار به درخواست اضافه می‌شود.	`Token/Middleware`	`integer`	`$request->get('branch')`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `items` (آرایه‌ای از آبجکت‌های متعهد) و `meta`. هر آبجکت متعهد شامل `id`, `colleague_id` و آبجکت `title` است.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: یک کاربر از شعبه ۲ درخواست لیست متعهدان را می‌کند

Request URL: /api/panel/v2/charter/pledger/list (با توکن کاربری از شعبه ۲)
Action:

یک کوئری JOIN بین charter_pledgers و colleagues اجرا می‌شود.
شرایط WHERE charter_pledgers.branch = 2, charter_pledgers.status = 1 و colleagues.status = 1 اعمال می‌شوند.
نتایج واکشی شده و برای هر رکورد، یک آبجکت با ساختار مشخص (id, colleague_id, title) ایجاد می‌شود.

Response:
HTTP Status: 200 OK
Body:

json

        {
            "items": [
                {
                    "id": 5,
                    "colleague_id": 48,
                    "title": {
                        "fa": "آژانس پرواز طلایی احمد محمدی",
                        "en": "Golden Flight Agency Ahmad Mohammadi"
                    }
                }
            ],
            "meta": { "timestamp": ... }
        }

Function storePledgerCharter

· هدف:

این متد یک عملکرد ساده و مشخص دارد: افزودن یک همکار (Colleague) به لیست متعهدان (Pledgers) یک شعبه. این کار با درج یک رکورد جدید در جدول charter_pledgers انجام می‌شود. اطلاعات لازم برای این کار، یعنی شناسه همکار (colleague_id) و شناسه شعبه (branch)، از ورودی درخواست و اطلاعات توکن کاربر استخراج می‌شود. این متد به عنوان یک نقطه پایانی سریع برای مدیریت لیست متعهدان عمل می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	ثبت یک همکار به عنوان متعهد جدید.
عملیات اصلی	درج یک رکورد جدید در جدول `charter_pledgers`.
منبع داده	شناسه همکار از بدنه درخواست و شناسه شعبه از توکن کاربر.
سادگی	عدم وجود منطق پیچیده؛ تنها یک عملیات `insert` ساده.
پاسخ موفقیت	بازگرداندن پاسخ `201 Created` در صورت درج موفقیت‌آمیز.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه همکاری که باید به عنوان متعهد ثبت شود.	`Body`	`integer`	`$request->colleague_id`
شناسه شعبه کاربر که به صورت خودکار به درخواست اضافه می‌شود.	`Token/Middleware`	`integer`	`$request->get('branch')`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `201 Created`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا (مثلاً خطای دیتابیس)، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: افزودن همکار با شناسه ۷۵ به لیست متعهدان شعبه ۲

Request Body:

json

    {
        "colleague_id": 75
    }

(درخواست از طرف کاربری در شعبه ۲ ارسال شده است)

Action:

یک آرایه insert با مقادیر branch: 2 و colleague_id: 75 ساخته می‌شود.
DB::table('charter_pledgers')->insert($insert) اجرا می‌شود.

Response:
HTTP Status: 201 Created

Function deletePledgerCharter

· هدف:

این متد برای حذف یک رکورد از لیست متعهدان (Pledgers) طراحی شده است. عملکرد آن بسیار ساده و مستقیم است: با دریافت شناسه رکورد متعهد (charter_pledgers.id)، آن را از جدول charter_pledgers حذف می‌کند. این یک عملیات حذف فیزیکی (Hard Delete) است و رکورد را به طور کامل از دیتابیس پاک می‌کند. این تابع نقطه مقابل storePledgerCharter برای مدیریت لیست متعهدان است.

ویژگی‌ها	توضیحات
هدف کلی	حذف یک متعهد از لیست متعهدان.
عملیات اتمی (Atomic)	حذف فیزیکی یک رکورد از جدول `charter_pledgers` بر اساس شناسه آن.
پشتیبانی از انواع چارتر	عدم وجود منطق پیچیده؛ تنها یک عملیات `delete` ساده.
موتور تکرار (Repeat Engine)	بازگرداندن پاسخ `204 No Content` در صورت حذف موفقیت‌آمیز.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه رکورد در جدول `charter_pledgers` که باید حذف شود.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: حذف متعهد با شناسه رکورد ۵ از لیست

Request:
id: 5
Action:

DB::table('charter_pledgers')->where('id', 5)->delete() اجرا می‌شود.

Response:
HTTP Status: 204 No Content

Function getFinancialCharter

· هدف:

این متد به عنوان یک موتور گزارش‌گیری مالی جامع برای یک چارتر خاص عمل می‌کند. هدف اصلی آن محاسبه و تجمیع تمام داده‌های مالی مرتبط با یک چارتر، از جمله درآمد، هزینه، سود، زیان، و مبالغ سوخت شده است. متد با واکشی تمام رزروهای قطعی، اطلاعات مالی هر رزرو را پردازش کرده و بر اساس کلاس (آیتم) و گروه سنی (adult, child, infant) دسته‌بندی می‌کند. همچنین، رزروهای گارانتی شده را شناسایی و در گروه‌های جداگانه‌ای بر اساس نوع گارانتی (pledgers, warranties) و شخص گارانتی‌کننده، دسته‌بندی می‌کند. در نهایت، متد مقادیر کلیدی مانند مبلغ پرداختی (paid), سود/زیان (profit), هزینه سوخت شده (burned) و تشخیص وضعیت کلی (diagnosis: creditor, debtor, neutral) را هم به تفکیک هر کلاس و هم به صورت مجموع برای کل چارتر محاسبه و ارائه می‌دهد.

ویژگی‌ها	توضیحات
هدف کلی	ارائه گزارش مالی کامل و دقیق از عملکرد یک چارتر.
تجمیع داده	پردازش و جمع‌بندی اطلاعات مالی از تمام رزروهای قطعی.
دسته‌بندی دقیق	تفکیک آمار بر اساس کلاس/آیتم، گروه سنی و نوع گارانتی.
محاسبات کلیدی	محاسبه `paid`, `payable`, `profit`, `burned`, `taxes`, `commissions`.
تشخیص وضعیت	تعیین وضعیت نهایی چارتر به عنوان بستانکار، بدهکار یا خنثی.
بهینه‌سازی	استفاده از یک حلقه برای پردازش تمام رزروها و تجمیع نتایج در یک ساختار داده واحد.
گزارش گارانتی	شناسایی و دسته‌بندی جداگانه رزروهای انجام شده تحت پوشش گارانتی.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی که گزارش مالی آن مورد نیاز است.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `payload`. این آبجکت شامل `information` (اطلاعات کلی چارتر)، `classes` (آرایه‌ای از کلاس‌ها با جزئیات مالی هر کدام)، `pledgers` و `warranties` (گروه‌بندی رزروهای گارانتی) و `total` (اعداد و ارقام مجموع) است.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: درخواست گزارش مالی برای چارتر پرواز با شناسه ۴۵۰

Request:
id: 450
Action:

اطلاعات اولیه چارتر ۴۵۰ و کلاس‌های آن واکشی می‌شود.
تمام رزروهای قطعی مربوط به این چارتر از دیتابیس خوانده می‌شوند.
متد روی هر رزرو حلقه می‌زند:

a. اطلاعات مالی (خرید، فروش، کمیسیون، …) و گروه سنی استخراج می‌شود.

b. این مقادیر به مجموع کل و مجموع کلاس مربوطه اضافه می‌شود.

c. اگر رزرو گارانتی باشد، در گروه pledgers یا warranties نیز ثبت می‌شود.

پس از پایان حلقه، محاسبات نهایی (سود، سوخت شده، …) روی مقادیر تجمیع شده انجام می‌شود.

Response:
HTTP Status: 200 OK
Body:

json

        {
            "payload": {
                "information": { ... },
                "classes": {
                    "980": { "title": "Economy", "financial": { "paid": 50000000, "payable": 48000000, "profit": -2000000, "burned": 5000000, "diagnosis": "debtor", ... }, ... },
                    "981": { ... }
                },
                "total": { "paid": 80000000, "payable": 79000000, "profit": -1000000, "burned": 5000000, "diagnosis": "debtor" },
                "pledgers": { ... },
                "warranties": { ... }
            },
            "meta": { "timestamp": ... }
        }

Function setCompletionFinancialCharter

· هدف:

این متد به عنوان یک نقطه پایانی (Endpoint) برای عملیات “تکمیل مالی” یک چارتر تعریف شده است. در نسخه فعلی کد، بدنه این تابع خالی است و صرفاً یک پاسخ موفقیت‌آمیز 204 No Content را بازمی‌گرداند. این ساختار نشان می‌دهد که این قابلیت در آینده پیاده‌سازی خواهد شد. هدف احتمالی این تابع در آینده، انجام اقداماتی مانند بستن حساب‌های مالی یک چارتر، تغییر وضعیت آن به “تکمیل شده”، تولید اسناد مالی نهایی یا بایگانی کردن داده‌های مالی آن خواهد بود. وجود این متد به عنوان یک Placeholder، معماری سیستم را برای توسعه‌های آتی آماده نگه می‌دارد.

ویژگی‌ها	توضیحات
هدف کلی	انجام عملیات نهایی‌سازی و تکمیل مالی یک چارتر.
وضعیت فعلی	پیاده‌سازی نشده (Placeholder).
عملکرد فعلی	تنها یک پاسخ موفقیت‌آمیز `204` بازمی‌گرداند.
کاربرد آینده (احتمالی)	بستن حساب‌ها، تغییر وضعیت چارتر، تولید گزارش نهایی، بایگانی.

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

توضیحات	نوع داده	نام پارمتر
`...`	`...`	`...`

· خروجی (Return):

توضیحات	نوع داده
یک پاسخ خالی با کد `204 No Content`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا (که در پیاده‌سازی فعلی رخ نمی‌دهد)، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: فراخوانی متد برای تکمیل مالی یک چارتر

Request URL: /api/panel/v2/charter/financial/completion
Action:

متد setCompletionFinancialCharter اجرا می‌شود.
هیچ عملیاتی انجام نمی‌شود.
پاسخ 204 بازگردانده می‌شود.

Response:
HTTP Status: 204 No Content

Function getAgeTitle

· هدف:

این متد یک ابزار کمکی ساده و کاربردی برای تعیین گروه سنی (adult, child, infant) یک شخص بر اساس تاریخ تولد و یک تاریخ مبنا (معمولاً تاریخ پرواز یا شروع اقامت) است. منطق آن بر اساس محاسبه اختلاف تعداد روزها بین دو تاریخ کار می‌کند. ابتدا تاریخ تولد را با استفاده از Functions::checkDatetime به فرمت استاندارد تبدیل کرده و سپس اختلاف آن با تاریخ مبنا را بر حسب روز محاسبه می‌کند. در نهایت، بر اساس قوانین استاندارد صنعت هوانوردی و گردشگری، گروه سنی را مشخص می‌کند: کمتر یا مساوی ۷۳۰ روز (۲ سال) به عنوان infant (نوزاد)، بین ۷۳۰ و ۴۳۸۰ روز (۲ تا ۱۲ سال) به عنوان child (کودک)، و بیشتر از ۴۳۸۰ روز (۱۲ سال) به عنوان adult (بزرگسال) در نظر گرفته می‌شود.

ویژگی‌ها	توضیحات
هدف کلی	تعیین گروه سنی (نوزاد، کودک، بزرگسال) بر اساس تاریخ تولد.
منطق اصلی	محاسبه اختلاف روز بین تاریخ تولد و تاریخ مبنا.
قوانین سنی	`infant` <= 2 سال, `child` > 2 و <= 12 سال, `adult` > 12 سال.
استانداردسازی ورودی	استفاده از `Functions::checkDatetime` برای مدیریت فرمت‌های مختلف تاریخ.
کاربرد	ابزار کمکی داخلی برای استفاده در سایر متدهای نیازمند به گروه سنی.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
تاریخ تولد شخص در فرمت‌های مختلف (مثلاً `1990-05-20`, `1369/02/30`).	`Parameter`	`string`	`$birth`
تاریخ مبنا برای محاسبه سن (مثلاً تاریخ پرواز).	`Parameter`	`string`	`$datetime`

· خروجی (Return):

توضیحات	نوع داده
یکی از سه رشته زیر: `'infant'`, `'child'`, `'adult'`.	`string`

· مثال استفاده / سناریو:

سناریو ۱: تعیین گروه سنی یک کودک

Call: getAgeTitle('2015-08-01', '2025-10-15 14:30:00')
Action:

اختلاف روز بین 2015-08-01 و 2025-10-15 محاسبه می‌شود که تقریباً ۳۷۲۷ روز است.
3727 بین 730 و 4380 قرار دارد.

Return: 'child'

سناریو ۲: تعیین گروه سنی یک نوزاد

Call: getAgeTitle('1402/11/10', '2025-10-15 14:30:00') -> (1402/11/10 معادل 2024-01-30)
Action:

checkDatetime تاریخ شمسی را به میلادی تبدیل می‌کند.
اختلاف روز بین 2024-01-30 و 2025-10-15 محاسبه می‌شود که تقریباً ۶۲۴ روز است.
624 کمتر از 730 است.

Return: 'infant'

Function listCommunicationsCharter

· هدف:

این متد برای جستجو و واکشی “ارتباطات” (Communications) بین چارترها طراحی شده است. یک ارتباط، اتصال منطقی بین دو چارتر یا آیتم‌های آن‌ها را نشان می‌دهد (مثلاً برای ساخت پکیج‌های تور رفت و برگشت از دو چارتر مجزا). هدف اصلی متد، فراهم کردن یک ابزار فیلترینگ قدرتمند برای یافتن این ارتباطات بر اساس پارامترهای مختلفی مانند شناسه چارتر مبدأ/مقصد، شناسه آیتم مبدأ/مقصد، یا حتی مبدأ و مقصد جغرافیایی است. برای فیلتر بر اساس مبدأ/مقصد جغرافیایی، متد ابتدا تمام چارترهای فعال با آن مبدأ/مقصد را پیدا کرده و سپس از شناسه‌های آن‌ها برای فیلتر کردن جدول charter_communications استفاده می‌کند. خروجی نهایی با استفاده از CharterResource غنی‌سازی شده و اطلاعات کاملی از هر دو طرف ارتباط (مبدأ و مقصد) را ارائه می‌دهد.

ویژگی‌ها	توضیحات
هدف کلی	جستجو و نمایش ارتباطات تعریف‌شده بین چارترها.
فیلترینگ جامع	قابلیت فیلتر بر اساس شناسه چارتر/آیتم مبدأ و مقصد.
فیلتر جغرافیایی	پشتیبانی از فیلتر بر اساس شهر مبدأ (`origin`) و مقصد (`destination`).
صفحه‌بندی	مدیریت خودکار صفحه‌بندی نتایج بر اساس پارامترهای ورودی.
غنی‌سازی خروجی	استفاده از `CharterResource::getInformation` برای افزودن جزئیات کامل چارترها به هر نتیجه.
کاربرد اصلی	مدیریت و نمایش پکیج‌های تور یا مسیرهای متصل به هم.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر مبدأ.	`Query`	`integer`	`main_id`
شناسه آیتم مبدأ.	`Query`	`integer`	`item_id`
شناسه چارتر مقصد در ارتباط.	`Query`	`integer`	`destination_main_id`
شناسه آیتم مقصد در ارتباط.	`Query`	`integer`	`destination_item_id`
شناسه شهر مبدأ برای جستجوی جغرافیایی.	`Query`	`integer`	`origin`
شناسه شهر مقصد برای جستجوی جغرافیایی.	`Query`	`integer`	`destination`
پارامترهای صفحه‌بندی (`length`, `start`).	`Query`	`array`	`paginate`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `items` (آرایه‌ای از آبجکت‌های ارتباط) و `meta`. هر آبجکت ارتباط شامل جزئیات کامل چارتر مبدأ (`charter`) و چارتر مقصد (`communication_charter`) است.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: یافتن تمام ارتباط‌هایی که از تهران شروع می‌شوند

Request URL: /api/panel/v2/charter/communication/list?origin=1
Action:

متد ابتدا تمام شناسه‌های چارترهای فعال که مبدأ آن‌ها 1 (تهران) است را از جدول charters استخراج می‌کند.
سپس یک کوئری به جدول charter_communications می‌زند و با استفاده از WHERE IN ('main_id', ...) نتایج را به چارترهای یافت‌شده در مرحله قبل محدود می‌کند.
نتایج صفحه‌بندی می‌شوند.
برای هر نتیجه، اطلاعات کامل چارتر مبدأ و مقصد واکشی و به خروجی اضافه می‌شود.

Response:
HTTP Status: 200 OK
Body: {"items": [{ "id": 1, "main_id": 101, "communication_main_id": 202, "charter": {...info for charter 101...}, "communication_charter": {...info for charter 202...} }, ...], "meta": {...}}

Function storeCommunicationCharter

· هدف:

این متد برای ایجاد یک “ارتباط” (Communication) جدید بین دو چارتر یا دو آیتم خاص از چارترها طراحی شده است. این ارتباطات برای ساختن پکیج‌ها (مثلاً تور رفت و برگشت با دو پرواز مجزا) کاربرد دارند. متد داده‌های مربوط به مبدأ (main_id, item_id) و مقصد (communication_main_id, communication_item_id) ارتباط را به همراه نوع اتصال (source_type, destination_type) از ورودی دریافت کرده و یک رکورد جدید در جدول charter_communications درج می‌کند. این یک عملیات ساده و اتمی برای تعریف پیوند بین موجودیت‌های مختلف چارتری است.

ویژگی‌ها	توضیحات
هدف کلی	ثبت یک ارتباط یا پیوند جدید بین دو چارتر/آیتم.
عملیات اصلی	درج یک رکورد در جدول `charter_communications`.
انعطاف‌پذیری	قابلیت اتصال چارتر به چارتر، آیتم به آیتم، چارتر به آیتم و آیتم به چارتر.
سادگی	عدم وجود منطق پیچیده، تنها یک عملیات `insert`.
پاسخ موفقیت	بازگرداندن پاسخ `201 Created` در صورت درج موفق.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر مبدأ.	`Body`	`integer`	`$request->main_id`
شناسه آیتم مبدأ (اختیاری).	`Body`	`integer`	`$request->item_id`
شناسه چارتر مقصد.	`Body`	`integer`	`$request->communication_main_id`
شناسه آیتم مقصد (اختیاری).	`Body`	`integer`	`$request->communication_item_id`
نوع مبدأ (`charter` یا `item`).	`Body`	`string`	`$request->source_type`
نوع مقصد (`charter` یا `item`).	`Body`	`string`	`$request->destination_type`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `201 Created`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: اتصال کلاس بیزنس پرواز رفت به کلاس بیزنس پرواز برگشت

Request Body:

json

    {
        "main_id": 101,
        "item_id": 501,
        "source_type": "item",
        "communication_main_id": 202,
        "communication_item_id": 601,
        "destination_type": "item"
    }

Action:

یک رکورد جدید در charter_communications با مقادیر فوق درج می‌شود.

Response:
HTTP Status: 201 Created

Function deleteCommunicationCharter

· هدف:

این متد برای حذف یک “ارتباط” (Communication) بین چارترها به کار می‌رود. عملکرد آن بسیار ساده است: با دریافت شناسه منحصر به فرد رکورد ارتباط از جدول charter_communications، آن رکورد را به صورت فیزیکی (Hard Delete) از دیتابیس حذف می‌کند. این تابع به عنوان ابزاری برای مدیریت و پاک‌سازی پیوندهای تعریف‌شده بین چارترها عمل می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	حذف یک رکورد ارتباط از جدول `charter_communications`.
نوع حذف	حذف فیزیکی (Hard Delete).
سادگی	تنها یک عملیات `delete` بر اساس `id`.
پاسخ موفقیت	بازگرداندن پاسخ `204 No Content` در صورت حذف موفق.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه رکورد در جدول `charter_communications` که باید حذف شود.	`Route/Body`	`integer`	`$request->id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: حذف ارتباط با شناسه ۱۲

Request:
id: 12
Action:

DB::table('charter_communications')->where('id', 12)->delete() اجرا می‌شود

Response:
HTTP Status: 204 No Content

Function getDetailsCharterItem

· هدف:

این متد استاتیک یک ابزار داخلی قدرتمند برای استخراج و فرمت‌دهی جزئیات یک آیتم از چارتر است. بر اساس نوع (method) آیتم (مانند route, accommodation, visa, insurance, service)، متد داده‌های خام ورودی را پردازش کرده و یک آبجکت ساختاریافته و تمیز را به عنوان خروجی بازمی‌گرداند. برای آیتم‌های از نوع route، متد جزئیات بیشتری مانند subtype (هوایی، ریلی، اتوبوس) را نیز در نظر گرفته و اطلاعات مربوط به شرکت حمل‌ونقل، شماره پرواز/قطار، ترمینال‌ها و زمان‌بندی را استخراج می‌کند. برای سایر انواع، اطلاعات مرتبط با خودشان مانند جزئیات هتل، کشور ویزا، یا نوع بیمه را بازمی‌گرداند. این تابع نقش کلیدی در استانداردسازی و پاک‌سازی داده‌های details قبل از ذخیره‌سازی در دیتابیس ایفا می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	پردازش و استانداردسازی آبجکت `details` یک آیتم چارتر.
متد استاتیک	قابل فراخوانی بدون نیاز به ساخت نمونه از کلاس (`CharterController::getDetailsCharterItem(...)`).
منطق شرطی	استفاده از `if-else` بر اساس `method` و `submethod` برای پردازش متفاوت انواع آیتم.
پاک‌سازی داده	استفاده از توابعی مانند `Functions::checkDatetime` و `Jalalian::fromFormat` برای تبدیل و فرمت‌دهی تاریخ‌ها.
ساختاردهی خروجی	تولید یک آبجکت JSON تمیز و قابل استفاده برای هر نوع آیتم.
کاربرد داخلی	عمدتاً در متد `storeCharter` برای آماده‌سازی فیلد `details` قبل از درج در `charter_items`.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
آبجکت آیتم از درخواست ورودی که شامل `method`, `submethod` و `details` است.	`Parameter`	`array`	`$item`
داده‌های پردازش‌شده مربوط به تاریخ و مسیر که در مراحل قبلی `storeCharter` تولید شده.	`Parameter`	`array`	`$data`
تاریخ و زمان دقیق آیتم.	`Parameter`	`string`	`$datetime`

· خروجی (Return):

توضیحات	نوع داده
یک آرایه انجمنی (associative array) که ساختار آن بسته به نوع آیتم متفاوت است و آماده‌ی تبدیل به JSON برای ذخیره‌سازی است.	`array`

· مثال استفاده / سناریو:

سناریو: پردازش جزئیات یک آیتم پرواز

Call (inside storeCharter):

php

    $item = [
        'method' => 'route',
        'submethod' => 'aircraft',
        'details' => [
            'origin' => ['id' => 1, 'terminal' => '2'],
            'destination' => ['id' => 2, 'terminal' => '1'],
            'company' => ['id' => 15],
            'vehicle' => ['number' => 'IR-456'],
            // ...
        ]
    ];
    $data = [ 'data' => ['duration' => '01:30'] ];
    $datetime = '2025-10-20 18:00:00';

    CharterController::getDetailsCharterItem($item, $data, $datetime);

Action:

متد وارد شاخه if ($type == 'route') و سپس if ($subType == 'aircraft') می‌شود.
اطلاعات مبدأ، مقصد، ترمینال، شرکت، شماره پرواز و مدت زمان را از ورودی‌ها استخراج می‌کند.
تاریخ و زمان را فرمت می‌کند.

Return:

php

    [
        'status' => true,
        'origin' => [ 'id' => 1, 'terminal' => '2' ],
        'destination' => [ 'id' => 2, 'terminal' => '1' ],
        'duration' => '01:30',
        'datetime' => '2025-10-20 18:00:00',
        'company' => [ 'id' => 15 ],
        'vehicle' => [ 'number' => 'IR-456' ]
    ]

Function getTableCharter

· هدف:

این متد استاتیک به عنوان یک ابزار کمکی حیاتی برای تعیین نام جداول مرتبط با یک چارتر عمل می‌کند. با توجه به اینکه سیستم از جداول متفاوتی برای ذخیره‌سازی رزروها و محاسبات بر اساس نوع چارتر (route یا accommodation) استفاده می‌کند، این تابع وظیفه دارد بر اساس ورودی (که می‌تواند شناسه چارتر یا نام نوع آن باشد)، نام صحیح جداول reservation و calculation را بازگرداند. این کار از تکرار کد جلوگیری کرده و قابلیت نگهداری سیستم را به شدت افزایش می‌دهد، زیرا منطق انتخاب نام جدول در یک مکان متمرکز شده است.

ویژگی‌ها	توضیحات
هدف کلی	تعیین نام جداول `reservation` و `calculation` بر اساس نوع چارتر.
متد استاتیک	قابل فراخوانی در سرتاسر پروژه بدون نیاز به نمونه‌سازی (`CharterController::getTableCharter(...)`).
ورودی منعطف	پذیرش شناسه عددی چارتر (برای واکشی نوع از دیتابیس) یا نام رشته‌ای نوع (`route`, `accommodation`).
متمرکزسازی منطق	جلوگیری از تکرار بلوک‌های `if-else` برای انتخاب نام جدول در متدهای مختلف.
خروجی ساختاریافته	بازگرداندن یک آرایه با کلیدهای ثابت (`type`, `reservation`, `calculation`).

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر یا نام نوع چارتر (مثلاً ‘route’).	`Parameter`	`integer or string`	`$data`
(استفاده نشده) این پارامتر در کد وجود دارد ولی در منطق فعلی استفاده نمی‌شود.	`Parameter`	`string`	`$subType`

· خروجی (Return):

توضیحات	نوع داده
یک آرایه انجمنی شامل سه کلید: `type` (نام نوع چارتر)، `reservation` (نام جدول رزروها)، و `calculation` (نام جدول محاسبات).	`array`

· مثال استفاده / سناریو:

سناریو ۱: دریافت نام جداول برای یک چارتر اقامتی با شناسه

Call: CharterController::getTableCharter(620)
Action:

متد تشخیص می‌دهد که ورودی عددی است.
SELECT type FROM charters WHERE id = 620 را اجرا می‌کند. فرضاً نتیجه accommodation است.
بر اساس type = 'accommodation'، نام جداول را تعیین می‌کند.

Return:

php

    [
        'type' => 'accommodation',
        'reservation' => 'charter_accommodation_reservation',
        'calculation' => 'charter_accommodation_calculation'
    ]

سناریو ۲: دریافت نام جداول با ارائه مستقیم نوع

Call: CharterController::getTableCharter('route')
Action:

متد تشخیص می‌دهد ورودی رشته‌ای است.
بر اساس type = 'route'، نام جداول را تعیین می‌کند.

Return:

php

    [
        'type' => 'route',
        'reservation' => 'charter_route_reservation',
        'calculation' => 'charter_route_calculation'
    ]

Function getConditionCharterItem

· هدف:

این متد استاتیک به عنوان یک ابزار کمکی برای پردازش و استانداردسازی شرایط (Conditions) و خدمات (Services) مرتبط با یک آیتم محاسباتی چارتر عمل می‌کند. هدف اصلی آن، تبدیل آرایه خام ورودی از شرایط (که معمولاً از فرم‌های فرانت‌اند می‌آید) به یک ساختار داده‌ی تمیز و یکپارچه قبل از ذخیره‌سازی در دیتابیس است. متد برای هر شرط، تنها اطلاعات ضروری مانند شناسه (id), نوع (type) و مقدار (value) را استخراج کرده و در یک آرایه جدید جمع‌آوری می‌کند. این کار باعث می‌شود که داده‌های اضافی یا نامرتبط حذف شده و تنها اطلاعات کلیدی در فیلد services جدول محاسبات به صورت JSON ذخیره شود.

ویژگی‌ها	توضیحات
هدف کلی	پاک‌سازی و استانداردسازی آرایه شرایط/خدمات یک آیتم.
عملیات اتمی (Atomic)	قابل فراخوانی به صورت عمومی (`CharterController::getConditionCharterItem(...)`).
پشتیبانی از انواع چارتر	حلقه زدن روی آرایه ورودی و استخراج فیلدهای کلیدی (`id`, `type`, `value`).
موتور تکرار (Repeat Engine)	حذف داده‌های غیرضروری و ایجاد یک ساختار داده‌ی بهینه برای ذخیره‌سازی.
ساختار داده پیچیده	عمدتاً در متد `storeCharter` برای پردازش فیلد `services` قبل از درج در جداول `calculation`.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
آرایه‌ای از آبجکت‌های شرط/خدمت که هر کدام شامل جزئیات مختلفی هستند.	`Parameter`	`array`	`$conditions`

· خروجی (Return):

توضیحات	نوع داده
آرایه‌ای از آبجکت‌های شرط/خدمت که هر کدام فقط شامل کلیدهای `id`, `type`, و `value` هستند.	`array`

· مثال استفاده / سناریو:

سناریو: پردازش شرایط کنسلی یک آیتم

Call (inside storeCharter):

php

    $inputConditions = [
        [ 'id' => 1, 'type' => ['id' => 'penalty'], 'value' => '10', 'title' => 'جریمه ۱۰ درصد', 'is_active' => true ],
        [ 'id' => 2, 'type' => ['id' => 'duration'], 'value' => '48', 'title' => 'تا ۴۸ ساعت قبل', 'is_active' => true ]
    ];
    CharterController::getConditionCharterItem($inputConditions);

Action:

متد روی آرایه inputConditions حلقه می‌زند.
برای هر آیتم، یک آبجکت جدید با استخراج مقادیر id, type['id'] و value می‌سازد.

Return:

php

    [
        [ 'id' => 1, 'type' => 'penalty', 'value' => '10' ],
        [ 'id' => 2, 'type' => 'duration', 'value' => '48' ]
    ]

Function listPlanCharter

· هدف:

این متد برای واکشی و نمایش لیست پلن‌های اتاق‌بندی (plan) مرتبط با یک چارتر اقامتی طراحی شده است. هدف اصلی آن، ارائه یک نمای کلی از تخصیص اتاق‌ها به مسافران بر اساس یک پلن از پیش تعریف‌شده است. متد ابتدا چارتر را بر اساس شناسه پیدا کرده و بررسی می‌کند که آیا چارتری از نوع اقامتی و دارای پلن است یا خیر. سپس، با استفاده از ReservationController::getPlanDetails, جزئیات کامل پلن (شامل لیست اتاق‌ها و مسافران تخصیص‌یافته به هر کدام) را واکشی می‌کند. در نهایت، با فراخوانی ReservationController::getPlanPassengers, لیست تمام مسافران مرتبط با آن پلن را نیز استخراج کرده و هر دو لیست (جزئیات پلن و لیست مسافران) را در خروجی بازمی‌گرداند.

ویژگی‌ها	توضیحات
هدف کلی	نمایش جزئیات پلن اتاق‌بندی و لیست مسافران مرتبط با آن.
اعتبارسنجی	بررسی اینکه چارتر از نوع اقامتی بوده و دارای `plan_id` است.
استفاده از کنترلر دیگر	فراخوانی متدهای `getPlanDetails` و `getPlanPassengers` از `ReservationController` برای واکشی داده‌ها.
خروجی دو بخشی	بازگرداندن هم جزئیات تخصیص اتاق‌ها (`details`) و هم لیست کلی مسافران (`passengers`).
خطایابی	بازگرداندن خطای `404` در صورت عدم وجود چارتر یا پلن.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اقامتی که پلن آن مورد نظر است.	`Route`	`integer`	`$id`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `payload` که خود شامل دو کلید `details` (آرایه‌ای از اتاق‌ها و مسافرانشان) و `passengers` (لیست کلی مسافran) است.	`Illuminate\Http\JsonResponse`
در صورت یافت نشدن چارتر یا پلن، یک پاسخ با کد `404 Not Found` و پیام خطا.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: مشاهده پلن اتاق‌بندی چارتر هتل با شناسه ۶۲۰

Request URL: /api/panel/v2/charter/620/plan/list
Action:

متد چارتر ۶۲۰ را از دیتابیس می‌خواند. فرضاً type='accommodation' و plan=5 است.
ReservationController::getPlanDetails(5, 620) فراخوانی می‌شود تا جزئیات تخصیص اتاق‌ها را برگرداند.
ReservationController::getPlanPassengers(5) فراخوانی می‌شود تا لیست تمام مسافران آن پلن را برگرداند.
نتایج در یک آبجکت payload ترکیب می‌شوند.

Response:
HTTP Status: 200 OK
Body:

json

        {
            "payload": {
                "details": [ { "room_number": "101", "passengers": [ {...} ] }, ... ],
                "passengers": [ {...passenger_1...}, {...passenger_2...} ]
            },
            "meta": { "timestamp": ... }
        }

Function setRoomingPlanCharter

· هدف:

این متد به عنوان نقطه پایانی برای تخصیص یک مسافر به یک اتاق خاص در یک پلن اتاق‌بندی عمل می‌کند. هدف اصلی آن، ثبت یا به‌روزرسانی رکورد مربوط به “رومینگ” (تخصیص اتاق) در جدول charter_plans_rooming است. متد ابتدا بررسی می‌کند که آیا مسافر از قبل به اتاق دیگری در همین پلن تخصیص داده شده است یا خیر. اگر چنین باشد، آن تخصیص قبلی را حذف می‌کند تا از تخصیص دوگانه یک مسافر جلوگیری شود. سپس، رکورد جدیدی برای تخصیص مسافر (reserve_id) به اتاق (room_id) در پلن (plan_id) درج می‌کند. این فرآیند اطمینان می‌دهد که هر مسافر در هر لحظه فقط به یک اتاق در یک پلن مشخص متصل است.

ویژگی‌ها	توضیحات
هدف کلی	تخصیص یک مسافر (رزرو) به یک اتاق در یک پلن اتاق‌بندی.
جلوگیری از تخصیص دوگانه	حذف تخصیص قبلی مسافر در همان پلن قبل از ایجاد تخصیص جدید.
عملیات اصلی	درج یک رکورد در جدول `charter_plans_rooming`.
یکپارچگی داده	تضمین اینکه هر مسافر فقط یک جایگاه در پلن دارد.
پاسخ موفقیت	بازگرداندن پاسخ `201 Created` در صورت موفقیت.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر.	`Route`	`integer`	`$request->id`
شناسه پلن اتاق‌بندی.	`Body`	`integer`	`$request->plan_id`
شناسه اتاق در پلن.	`Body`	`integer`	`$request->room_id`
شناسه رزرو مسافری که باید به اتاق تخصیص داده شود.	`Body`	`integer`	`$request->reserve_id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `201 Created`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: انتقال مسافر با رزرو شناسه ۵۴۳۲ به اتاق با شناسه ۱۰۱ در پلن ۵

Request Body:

json

    {
        "plan_id": 5,
        "room_id": 101,
        "reserve_id": 5432
    }

Action:

DELETE FROM charter_plans_rooming WHERE plan_id = 5 AND reserve_id = 5432 اجرا می‌شود تا هرگونه تخصیص قبلی پاک شود.
INSERT INTO charter_plans_rooming (plan_id, room_id, reserve_id) VALUES (5, 101, 5432) اجرا می‌شود.

Response:
HTTP Status: 201 Created

Function deleteRoomingPlanCharter

· هدف:

این متد برای حذف تخصیص یک مسافر از یک اتاق در یک پلن اتاق‌بندی (رومینگ) طراحی شده است. عملکرد آن بسیار ساده و مستقیم است: با دریافت شناسه پلن (plan_id) و شناسه رزرو مسافر (reserve_id)، رکورد متناظر را از جدول charter_plans_rooming حذف می‌کند. این کار به معنی آزاد کردن جایگاه آن مسافر در پلن است و به او اجازه می‌دهد تا به اتاق دیگری تخصیص یابد یا به طور کلی از پلن حذف شود.

ویژگی‌ها	توضیحات
هدف کلی	حذف تخصیص یک مسافر به یک اتاق در پلن (un-rooming).
عملیات اصلی	حذف یک رکورد از جدول `charter_plans_rooming`.
شرایط حذف	حذف بر اساس ترکیب `plan_id` و `reserve_id`.
سادگی	عدم وجود منطق پیچیده، تنها یک عملیات `delete`.
پاسخ موفقیت	بازگرداندن پاسخ `204 No Content`.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه پلن اتاق‌بندی.	`Body`	`integer`	`$request->plan_id`
شناسه رزرو مسافری که تخصیص او باید حذف شود.	`Body`	`integer`	`$request->reserve_id`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ خالی با کد `204 No Content`.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: حذف مسافر با رزرو شناسه ۵۴۳۲ از پلن ۵

Request Body:

json

    {
        "plan_id": 5,
        "reserve_id": 5432
    }

Action:

DELETE FROM charter_plans_rooming WHERE plan_id = 5 AND reserve_id = 5432 اجرا می‌شود.

Response:
HTTP Status: 204 No Content

Function getAccommodationRooms

· هدف:

این متد برای واکشی و نمایش وضعیت اتاق‌های یک چارتر اقامتی در یک بازه زمانی مشخص طراحی شده است. هدف اصلی آن، ارائه یک نمای گرافیکی یا جدولی از در دسترس بودن اتاق‌ها در طول زمان است. متد ابتدا یک دوره زمانی (CarbonPeriod) بین تاریخ شروع و پایان ورودی ایجاد می‌کند. سپس، برای هر اتاق (room_id) مربوط به چارتر، وضعیت رزرو آن را در هر روز از دوره زمانی مشخص شده بررسی می‌کند. برای هر روز، وضعیت اتاق می‌تواند یکی از سه حالت باشد: available (آزاد)، unavailable (مثلاً برای تعمیرات)، یا reserved (رزرو شده). در حالت reserved، اطلاعات رزرو مربوطه نیز به خروجی ضمیمه می‌شود. این ساختار داده خروجی برای رندر کردن تقویم وضعیت اتاق‌ها در فرانت‌اند بسیار مناسب است.

ویژگی‌ها	توضیحات
هدف کلی	نمایش وضعیت روزانه اتاق‌های یک هتل در یک بازه زمانی.
پردازش زمانی	ایجاد یک دوره زمانی روزانه با `CarbonPeriod`.
بررسی وضعیت	ایجاد یک دوره زمانی روزانه با `CarbonPeriod`.
واکشی اطلاعات رزرو	در صورت رزرو بودن، جزئیات رزرو را از دیتابیس استعلام می‌کند.
بهینه‌سازی	تولید یک ساختار داده تودرتو (اتاق -> روز -> وضعیت) برای نمایش آسان.
بهینه‌سازی	واکشی تمام اتاق‌ها و رزروهای مرتبط در ابتدای کار برای کاهش تعداد کوئری‌ها در حلقه.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اقامتی.	`Route`	`integer`	`$request->id`
تاریخ شروع بازه زمانی (مثلاً `2025-10-01`).	`Query`	`string (date)`	`$request->from`
تاریخ پایان بازه زمانی (مثلاً `2025-10-31`).	`Query`	`string (date)`	`$request->to`

· خروجی (Return):

توضیحات	نوع داده
یک آبجکت `JSON` با کلید `payload` که آرایه‌ای از آبجکت‌های اتاق است. هر آبجکت اتاق شامل اطلاعات اتاق و یک کلید `dates` است که وضعیت اتاق را در هر روز از بازه زمانی نشان می‌دهد.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request`.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: مشاهده وضعیت اتاق‌های هتل در ماه اکتبر

Request URL: /api/panel/v2/charter/620/accommodation/rooms?from=2025-10-01&to=2025-10-31
Action:

یک CarbonPeriod از اول تا آخر اکتبر ایجاد می‌شود.
تمام اتاق‌های چارتر ۶۲۰ و تمام رزروهای آن در این بازه واکشی می‌شوند.
برای هر اتاق، متد روی تمام روزهای اکتبر حلقه می‌زند.
برای هر روز، بررسی می‌کند که آیا رزروی آن روز را پوشش می‌دهد یا خیر.

Response:
HTTP Status: 200 OK
Body:

json

        {
            "payload": [
                {
                    "room_id": 201, "number": "101", ...,
                    "dates": {
                        "2025-10-15": { "status": "available" },
                        "2025-10-16": { "status": "reserved", "reservation": {...} },
                        "2025-10-17": { "status": "reserved", "reservation": {...} },
                        // ...
                    }
                }
            ],
            "meta": { "timestamp": ... }
        }

Function setAccommodationRooms

· هدف:

این متد برای تغییر وضعیت یک یا چند اتاق در یک چارتر اقامتی طراحی شده است. هدف اصلی آن، امکان خارج کردن اتاق‌ها از دسترس (status = 2) یا بازگرداندن آن‌ها به حالت در دسترس (status = 1) است. یک منطق امنیتی مهم در این متد وجود دارد: قبل از خارج کردن یک اتاق از دسترس، بررسی می‌کند که آیا آن اتاق در بازه زمانی درخواستی (from, to) دارای رزرو قطعی است یا خیر. اگر رزروی وجود داشته باشد، عملیات متوقف شده و با یک خطای 400 به کاربر اطلاع داده می‌شود. این کار از ایجاد تداخل و از دسترس خارج کردن اتاقی که به مسافری فروخته شده است، جلوگیری می‌کند و یکپارچگی داده‌های رزرو را تضمین می‌نماید.

ویژگی‌ها	توضیحات
هدف کلی	تغییر وضعیت در دسترس بودن اتاق‌های هتل.
بررسی امنیتی	جلوگیری از خارج کردن اتاقی که دارای رزرو است.
عملیات گروهی	قابلیت تغییر وضعیت چندین اتاق در یک درخواست.
عملیات اصلی	به‌روزرسانی فیلد `status` در جدول `charter_accommodation_rooms`.
خطایابی	بازگرداندن پیام خطای واضح در صورت وجود رزرو روی اتاق.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
آبجکت اصلی درخواست حاوی تمام داده‌های لازم برای ایجاد چارتر.	`Route`	`integer`	`$request->id`
کلید اصلی. نوع چارتر را مشخص می‌کند. مقادیر معتبر: `'route'` یا `'accommodation'`.	`Body`	`array`	`$request->items`
(برای `type: 'route'`) نوع وسیله نقلیه را مشخص می‌کند: `'aircraft'`, `'train'`, `'bus'`.	`Body`	`integer`	`$request->status`
آرایه‌ای حاوی جزئیات اصلی چارتر، مانند مبدأ، مقصد، تاریخ و اطلاعات وسیله نقلیه.	`Body`	`string (date)`	`$request->from`
مهم. آرایه‌ای از آبجکت‌ها که کلاس‌های مختلف قیمتی و ظرفیتی چارتر را تعریف می‌کنند.	`Body`	`string (date)`	`$request->to`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک آبجکت `JSON` با `payload: true`.	`Illuminate\Http\JsonResponse`
در صورت وجود رزرو روی یکی از اتاق‌ها، یک پاسخ با کد `400 Bad Request` و پیام خطا.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: تلاش برای خارج کردن اتاقی که رزرو دارد

Request Body:

json

    {
        "items": [201],
        "status": 2,
        "from": "2025-10-15",
        "to": "2025-10-25"
    }

Action:

متد روی items حلقه می‌زند (برای اتاق 201).
کوئری برای یافتن رزروهای اتاق 201 در بازه زمانی مشخص شده اجرا می‌شود.
فرض: یک رزرو پیدا می‌شود.
عملیات متوقف می‌شود.

Response:
HTTP Status: 400 Bad Request
Body: {"error": {"message": "این اتاق در بازه درخواستی شما دارای رزرو می باشد..."}}

Function getCommunicationsCalculation

· هدف:

این متد استاتیک یک ابزار کمکی برای واکشی جزئیات یک “آیتم محاسباتی” (Calculation Item) خاص است که در یک ارتباط (Communication) استفاده شده. هدف اصلی آن، فراهم کردن اطلاعات لازم برای نمایش جزئیات آیتم (مانند کلاس پرواز یا نوع واگن قطار) در UI مدیریت ارتباطات است. متد بر اساس نوع چارتر (route) و زیرنوع آن (aircraft, train)، اطلاعات را از جداول مربوطه واکشی و فرمت‌دهی می‌کند. برای پرواز، کلاس یاتا (IATA) و نام انگلیسی و فارسی آن را برمی‌گرداند. برای قطار، جزئیات نوع واگن (مانند ستاره و نوع کوپه) را از جدول train_types استخراج می‌کند. این تابع به متمرکز کردن منطق واکشی جزئیات آیتم کمک می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	واکشی و فرمت‌دهی جزئیات یک آیتم محاسباتی برای استفاده در ماژول ارتباطات.
متد استاتیک	قابل فراخوانی به صورت عمومی (`CharterController::getCommunicationsCalculation(...)`).
منطق شرطی	پردازش متفاوت بر اساس `subtype` چارتر (`aircraft` یا `train`).
واکشی داده	استعلام از جداول `charter_calculations_route` و `train_types`.
خروجی ساختاریافته	بازگرداندن یک آبجکت `calculation` با جزئیات کامل `class`.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی.	`Parameter`	`integer`	`$mainId`
شناسه چارتر اصلی.	`Parameter`	`integer`	`$itemId`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک آرایه حاوی اطلاعات آیتم (`id`, `main_id`, `class`). در صورت عدم وجود آیتم یا نوع نامعتبر، `false` بازگردانده می‌شود.	`array or false`

· مثال استفاده / سناریو:

سناریو: واکشی جزئیات کلاس پرواز با شناسه آیتم ۵۰۱

Call: CharterController::getCommunicationsCalculation(101, 501)
Action:

اطلاعات چارتر ۱۰۱ واکشی می‌شود (فرضاً type='route', subtype='aircraft').
اطلاعات آیتم ۵۰۱ از charter_calculations_route خوانده می‌شود (فرضاً title='Y').
چون subtype برابر aircraft است، نام کلاس از Functions::getClassName('Y') استخراج می‌شود.

Return:

php

    [
        'id' => 501,
        'main_id' => 101,
        'class' => [
            "iata" => "Y",
            "title_en" => "Economy",
            "title_fa" => "اکونومی"
        ]
    ]

Function getCommunicationsCharter

· هدف:

این متد استاتیک برای واکشی اطلاعات اولیه و ضروری یک چارتر برای استفاده در ماژول “ارتباطات” (Communications) طراحی شده است. هدف آن، فراهم کردن یک لیست از آیتم‌های محاسباتی (کلاس‌ها/اتاق‌ها) موجود در آن چارتر به همراه اطلاعات کلی چارتر (مانند مبدأ، مقصد و تاریخ) است. متد نوع چارتر را تشخیص داده و بر اساس آن، کوئری را به جدول محاسبات مربوطه (charter_calculations_route یا charter_calculations_accommodation) ارسال می‌کند. خروجی شامل اطلاعات اصلی چارتر و لیستی از شناسه‌های آیتم‌های آن است که می‌تواند برای ساخت منوهای کشویی در فرم‌های ایجاد ارتباط استفاده شود.

ویژگی‌ها	توضیحات
هدف کلی	واکشی اطلاعات کلی و لیست آیتم‌های یک چارتر برای ماژول ارتباطات.
متد استاتیک	قابل فراخوانی به صورت عمومی (`CharterController::getCommunicationsCharter(...)`).
انتخاب جدول پویا	تشخیص خودکار جدول محاسبات بر اساس نوع چارتر.
خروجی ساده	بازگرداندن اطلاعات ضروری (`information`) و لیستی از شناسه‌های آیتم‌ها (`calculations`).
ساختار داده پیچیده	تأمین داده برای UI ایجاد و ویرایش ارتباطات.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
شناسه چارتر اصلی که اطلاعات آن مورد نیاز است.	`Parameter`	`integer`	`mainId`

· خروجی (Return):

توضیحات	نوع داده
یک آرایه انجمنی با دو کلید `information` (شامل `origin`, `destination`, `start`) و `calculations` (مجموعه‌ای از آبجکت‌ها که هر کدام شناسه یک آیتم را دارند).	`array`

· مثال استفاده / سناریو:

سناریو: واکشی اطلاعات چارتر پرواز با شناسه ۱۰۱

Call: CharterController::getCommunicationsCharter(101)
Action:

اطلاعات چارتر ۱۰۱ از جدول charters واکشی می‌شود.
چون نوع آن route است، تمام شناسه‌های آیتم از charter_calculations_route که main_id=101 دارند، واکشی می‌شوند.

Return:

php

    [
        'information' => [
            "origin" => "THR",
            "destination" => "MHD",
            "start" => "2025-10-20 18:00:00"
        ],
        'calculations' => [
            (object)['id' => 501],
            (object)['id' => 502]
        ]
    ]

Function updateCharterReservation

· هدف:

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

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

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

توضیحات	موقعیت	نوع داده	نام پارمتر
آرایه‌ای از آبجکت‌های رزرو که هر کدام شامل شناسه رزرو و فیلدهای مورد نظر برای ویرایش است.	`Body`	`array`	`$request->reservations`
(اجباری) شناسه رزرو (`reservation_id`) که قرار است ویرایش شود.	`Body`	`integer`	`$reservation['id']`
(اختیاری) آبجکتی شامل اطلاعات جدید مسافر (مانند `fullname`, `identity`, `birth`, `mobile`, `email`).	`Body`	`object`	`$reservation['passenger']`
(اختیاری) کد وضعیت جدید رزرو (مثلاً `1` برای قطعی، `2` برای کنسل).	`Body`	`integer`	`$reservation['status']`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت کامل، یک پاسخ خالی با کد وضعیت `204 No Content` برمی‌گرداند.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا در حین پردازش (مثلاً پیدا نشدن یکی از رزروها)، یک پاسخ با کد `400 Bad Request` حاوی جزئیات خطا برمی‌گرداند.	`Illuminate\Http\JsonResponse`
در صورت وجود خطای اعتبارسنجی در داده‌های ورودی، یک پاسخ با کد `422 Unprocessable Entity` برمی‌گرداند.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: اصلاح نام خانوادگی مسافر در رزرو شماره ۱۲۳۴۵ و تغییر وضعیت رزرو شماره ۱۲۳۴۶ به کنسل شده.

Request Body:

json

    {
        "reservations": [
            {
                "id": 12345,
                "passenger": {
                    "fullname": {
                        "last_name": { "fa": "اکبری", "en": "Akbari" }
                    }
                }
            },
            {
                "id": 12346,
                "status": 2
            }
        ]
    }

Action:

متد درخواست را دریافت کرده و حلقه را روی آرایه reservations شروع می‌کند.
برای رزرو 12345، آبجکت passenger را در دیتابیس پیدا کرده، نام خانوادگی را آپدیت و مجدداً به صورت JSON ذخیره می‌کند.
برای رزرو 12346، فیلد status را در دیتابیس به 2 تغییر می‌دهد.

Response:
کد وضعیت: 204 No Content
Body: (خالی)

Function deleteCharterReservation

· هدف:

این متد برای حذف منطقی (Soft Delete) یک یا چند رزرو از یک چارتر مشخص به کار می‌رود. به جای حذف فیزیکی رکوردها از دیتابیس، این تابع ستون deleted_at را برای رزروهای انتخاب شده با زمان حال پر می‌کند. این کار به سیستم اجازه می‌دهد تا رزروها را آرشیو کرده و در صورت نیاز در آینده قابل بازیابی باشند، اما دیگر در لیست رزروهای فعال نمایش داده نشوند. این عملیات به صورت دسته‌ای برای تمام شناسه‌های ارسال شده انجام می‌شود.

ویژگی‌ها	توضیحات
هدف کلی	حذف موقت و غیرفیزیکی (Soft Delete) رزروهای چارتر.
عملیات اتمی (Atomic)	قابلیت حذف چندین رزرو با یک درخواست واحد.
پشتیبانی از انواع چارتر	اطلاعات رزرو در دیتابیس باقی می‌ماند و فقط از دسترس خارج می‌شود.
موتور تکرار (Repeat Engine)	تمام رزروهای مشخص شده در یک تراکنش حذف می‌شوند.
ساختار داده پیچیده	متد به صورت هوشمند جدول رزرو مربوط به نوع چارتر (مسیر یا اقامتگاه) را تشخیص می‌دهد.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
(اجباری) شناسه اصلی چارتر (`charter_id`) که رزروها به آن تعلق دارند.	`Body`	`integer`	`$request->main_id`
(اجباری) آرایه‌ای از شناسه‌های رزرو (`reservation_id`) که باید حذف شوند.	`Body`	`array`	`$request->ids`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت کامل، یک پاسخ خالی با کد وضعیت `204 No Content` برمی‌گرداند.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا در حین پردازش، یک پاسخ با کد `400 Bad Request` حاوی جزئیات خطا برمی‌گرداند.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: حذف دو رزرو با شناسه‌های ۵۰۱ و ۵۰۲ از چارتر با شناسه ۱۰۰.

Request Body:

json

    {
        "main_id": 100,
        "ids": [501, 502]
    }

Action:

متد ابتدا با استفاده از main_id: 100، نوع چارتر را تشخیص داده و نام جدول رزرو صحیح (مثلاً charter_reservations_route) را پیدا می‌کند.
سپس یک کوئری UPDATE روی این جدول اجرا می‌کند تا برای رکوردهایی که id آن‌ها در آرایه [501, 502] وجود دارد، ستون deleted_at را با تاریخ و زمان فعلی پر کند.

Response:
کد وضعیت: 204 No Content
Body: (خالی)

Function operationWarrantyCharter

· هدف:

این متد به منظور مدیریت گارانتی‌کنندگان (تضامین) یک چارتر خاص طراحی شده است. بر اساس پارامتر action که در درخواست ارسال می‌شود، این تابع می‌تواند یک یا چند گارانتی‌کننده جدید را به چارتر اضافه کند (add) یا گارانتی‌کنندگان موجود را از آن حذف نماید (remove). این قابلیت به مدیر سیستم اجازه می‌دهد تا به صورت پویا لیست همکارانی که فروش صندلی‌ها یا اتاق‌ها را تضمین کرده‌اند، مدیریت کند.

ویژگی‌ها	توضیحات
هدف کلی	افزودن یا حذف گارانتی‌کنندگان (تضامین) برای یک چارتر.
عملیات دوگانه	با استفاده از پارامتر `action`، هم کار `add` و هم `remove` را انجام می‌دهد.
پردازش دسته‌ای	قابلیت افزودن یا حذف چندین گارانتی‌کننده با یک درخواست.
جلوگیری از تکرار	هنگام افزودن، بررسی می‌کند که گارانتی‌کننده قبلاً برای آن چارتر ثبت نشده باشد.
عملیات اتمی	عملیات افزودن یا حذف در یک تراکنش واحد انجام می‌شود.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
(اجباری) شناسه اصلی چارتر (`charter_id`) که عملیات روی آن انجام می‌شود.	`Body`	`integer`	`$request->main_id`
(اجباری) نوع عملیات. باید یکی از مقادیر `add` یا `remove` باشد.	`Body`	`string`	`$request->action`
(اجباری) آرایه‌ای از شناسه‌ها. در حالت `add`، این آرایه شامل `guarantor_id` (شناسه همکار) است. در حالت `remove`، این آرایه شامل `warranty_id` (شناسه رکورد تضمین در جدول `charter_warranties`) است.	`Body`	`array`	`$request->items`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت کامل، یک پاسخ خالی با کد وضعیت `204 No Content` برمی‌گرداند.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا (مثلاً ارسال `action` نامعتبر)، یک پاسخ با کد `400 Bad Request` حاوی جزئیات خطا برمی‌گرداند.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو ۱: افزودن دو همکار با شناسه‌های ۲۰۰۱ و ۲۰۰۲ به عنوان گارانتی‌کننده برای چارتر ۱۰۰.

Request Body:

json

    {
        "main_id": 100,
        "action": "add",
        "items": [2001, 2002]
    }

Action:

متد درخواست را با action: "add" دریافت می‌کند.
به ازای هر id در آرایه items، یک رکورد جدید در جدول charter_warranties با charter_id = 100 و guarantor = id ایجاد می‌کند (به شرطی که از قبل وجود نداشته باشد).

Response:
کد وضعیت: 204 No Content

سناریو ۲: حذف دو تضمین با شناسه‌های ۳۵ و ۳۶ از چارتر مربوطه.

Request Body:

json

    {
        "main_id": 100, // در این سناریو main_id استفاده نمی‌شود ولی ارسال آن الزامی است
        "action": "remove",
        "items": [35, 36]
    }

Action:

متد درخواست را با action: "remove" دریافت می‌کند.
رکوردهایی از جدول charter_warranties که id آن‌ها در آرایه [35, 36] موجود است را حذف فیزیکی (delete) می‌کند.

Response:
کد وضعیت: 204 No Content

Function listServicesCharter

· هدف:

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

ویژگی‌ها	توضیحات
هدف کلی	دریافت لیست سرویس‌های موجود بر اساس نوع چارتر.
عملیات اتمی (Atomic)	نمایش سرویس‌های مرتبط با `route` (مسیر) یا `accommodation` (اقامتگاه).
پشتیبانی از انواع چارتر	ارائه خروجی در قالب استاندارد شامل شناسه و عنوان سرویس.
موتور تکرار (Repeat Engine)	با افزودن انواع جدید سرویس در دیتابیس، خروجی این متد نیز به روز می‌شود.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
(اجباری) نوع چارتر که سرویس‌ها برای آن درخواست شده است. مقادیر معتبر `route` یا `accommodation` هستند.	`Query String`	`string`	`$request->type`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت، یک پاسخ با کد `200 OK` حاوی آرایه‌ای از آبجکت‌های سرویس برمی‌گرداند. هر آبجکت شامل `id` و `title` سرویس است.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` حاوی جزئیات خطا برمی‌گرداند.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: دریافت لیست تمام سرویس‌های قابل ارائه برای یک چارتر از نوع “مسیر” (route).

Request URL:

GET /api/panel/v2/charter/list-services?type=route

Action:

1. متد پارامتر `type=route` را دریافت می‌کند.
2. به جدول `charter_services_types` کوئری می‌زند و تمام رکوردهایی که ستون `route` آن‌ها برابر با `1` است را انتخاب می‌کند.
3. فیلدهای `id` و `title` را از نتایج استخراج کرده و در قالب یک آرایه JSON برمی‌گرداند.

Response Body (مثال):

```json
{
"payload": [
{
"id": 1,
"title": "ترانسفر فرودگاهی"
},
{
"id": 3,
"title": "بیمه مسافرتی"
},
{
"id": 5,
"title": "راهنمای تور"
}
],
"meta": {
"timestamp": 1678886400
}
}

Function storeRefundCharterReservation

· هدف:

این متد فرآیند استرداد (Refund) یک یا چند رزرو را مدیریت می‌کند. این تابع به صورت دسته‌ای عمل کرده و می‌تواند لیستی از رزروها را دریافت و برای هر یک، عملیات استرداد را بر اساس قوانین و جریمه‌های تعریف شده انجام دهد. این تابع با محاسبه مبلغ جریمه، به‌روزرسانی وضعیت رزرو به “مسترد شده” (status=3) و ثبت یک رکورد در جدول charter_refunds، فرآیند استرداد را به صورت کامل و اتمی پیاده‌سازی می‌کند.

ویژگی‌ها	توضیحات
هدف کلی	ثبت درخواست استرداد برای یک یا چند رزرو چارتر.
پردازش دسته‌ای	قابلیت استرداد چندین رزرو با یک درخواست واحد.
محاسبه جریمه	محاسبه خودکار مبلغ جریمه بر اساس درصد (`percent`) یا مبلغ ثابت (`amount`).
ثبت تراکنش	ثبت تمام جزئیات استرداد شامل مبلغ جریمه و مبلغ قابل بازگشت در جدول `charter_refunds`.
به‌روزرسانی وضعیت	تغییر وضعیت رزروهای مسترد شده به `3` (Refund) و ثبت `refund_id`.
اعتبارسنجی	بررسی می‌کند که آیا رزرو قبلاً مسترد شده است یا خیر.

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

توضیحات	موقعیت	نوع داده	نام پارمتر
(اجباری) آرایه‌ای از آبجکت‌ها. هر آبجکت نماینده یک رزرو برای استرداد است.	`Body`	`array`	`$request->items`
(اجباری) شناسه رزرو (`charter_reservations.id`) که باید مسترد شود.	`Body (items)`	`integer`	`item.id`
(اجباری) نوع جریمه. باید یکی از مقادیر `percent` (درصدی) یا `amount` (مبلغی) باشد.	`Body (items)`	`string`	`item.penalty_type`
(اجباری) مقدار جریمه. اگر `penalty_type` برابر `percent` باشد، این مقدار یک عدد بین ۰ تا ۱۰۰ است. اگر `amount` باشد، یک مبلغ ثابت است.	`Body (items)`	`numeric`	`item.penalty`
(اختیاری) توضیحات مربوط به دلیل استرداد.	`Body (items)`	`string`	`item.description`

· خروجی (Return):

توضیحات	نوع داده
در صورت موفقیت کامل، یک پاسخ خالی با کد وضعیت `204 No Content` برمی‌گرداند.	`Illuminate\Http\JsonResponse`
در صورت بروز خطا (مانند یافت نشدن رزرو یا استرداد تکراری)، یک پاسخ با کد `400 Bad Request` یا `409 Conflict` به همراه پیام خطا برمی‌گرداند.	`Illuminate\Http\JsonResponse`

· مثال استفاده / سناریو:

سناریو: استرداد دو رزرو با شناسه‌های ۵۰۱ و ۵۰۲.

رزرو ۵۰۱ با ۱۰٪ جریمه.
رزرو ۵۰۲ با جریمه ثابت ۵۰۰,۰۰۰ ریال.
Request Body:

json

    {
        "items": [
            {
                "id": 501,
                "penalty_type": "percent",
                "penalty": 10,
                "description": "کنسلی توسط مسافر"
            },
            {
                "id": 502,
                "penalty_type": "amount",
                "penalty": 500000,
                "description": "تغییر برنامه پرواز"
            }
        ]
    }

Action:

تابع یک حلقه روی آرایه items اجرا می‌کند.
برای id: 501، رزرو را از دیتابیس می‌خواند، مبلغ کل آن را برمی‌دارد و ۱۰٪ آن را به عنوان جریمه محاسبه می‌کند.
برای id: 502، رزرو را می‌خواند و مبلغ ۵۰۰,۰۰۰ را مستقیماً به عنوان جریمه در نظر می‌گیرد.
برای هر دو، یک رکورد در جدول charter_refunds ایجاد می‌کند و جزئیات مالی و جریمه را ثبت می‌کند.
وضعیت هر دو رزرو را در جدول charter_reservations به 3 تغییر داده و refund_id مربوطه را در آن ذخیره می‌کند.

Response:
کد وضعیت: 204 No Content