Function operationCharter

·  هدف:

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

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

---

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

 

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

---

·     خروجی (Return):

 

توضیحات

نوع داده

یک پاسخ JSONاستاندارد کهدر قالب JSON. در صورت موفقیت، حاویمعمولاً یک آرایهپیام باساده کلیدهای main، calculations، taxes و financial است. این کلیدها به ترتیب شناسه‌های ایجاد شده برای چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و اطلاعات مالی را در خود جای داده‌اند.برمی‌گرداند. در صورت بروز خطا،خطا (مثلاً تلاش برای کاهش ظرفیت نامعتبر)، یک پاسخ با کد وضعیت HTTP 5004xx و پیام خطاخطای برگرداندهدقیق برای کاربر ارسال می‌شود.کند.

Illuminate\Http\JsonResponse

---

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

// سناریو:سناریو ایجاد۱: به‌روزرسانی توضیحات و ظرفیت کلی یک چارتر پرواز هفتگی برای روزهای شنبه و دوشنبه
// POST /api/panel/v2/charter/storeoperation
// 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",
    "subtype": "aircraft",
    "capacity": 180,
    "description": "چارتر هفتگی تهران-مشهد",
    "permissions": { /* ... */ },
    "repeat"deleted": {
        "type": "weekly",
        "from": "1404/08/01",
        "to": "1404/08/30",
        "days"calculations": [6, 1]101] // شنبهدرخواست وحذف دوشنبهکلاس با شناسه 101
    },
    "items": [
        {
            "details": {
                "origin": { "id": 1, "name": "THR" },
                "destination": { "id": 2, "name": "MHD" },
                "datetime": "1404/08/04 10:30", // تاریخ یکی از روزهای الگو (یک‌شنبه)
                "vehicle": { /* ... */ }
            }
        }
    ],
    "calculations": [
        {
            "name"id": "اکونومی",102, "capacity":// 150,به‌روزرسانی کلاس با شناسه 102
            "financial": { "base": { "adult_price": 2500000 } }
            /*/ ... */سایر }
        },
        {
            "name": "بیزنس",
            "capacity": 30,
            "financial": { /* ... */ }جزئیات
        }
    ]
}

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