Function operationCharter

·  هدف:

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

ویژگی‌ها	توضیحات
هدف کلی	ایجاد یک یا چند چارتر بر اساس تنظیمات ورودی، شامل نوع، جزئیات مسیر/اقامتگاه و الگوی تکرار.
عملیات اتمی (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

---

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

// سناریو: ایجاد یک چارتر پرواز هفتگی برای روزهای شنبه و دوشنبه
// 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, ...] // شناسه‌های اطلاعات مالی
}