# 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`**
--- #### · مثال استفاده: ```php // سناریو ۱: به‌روزرسانی توضیحات و ظرفیت کلی یک چارتر // 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) می باشد. لطفا قبل از انجام هر عملیاتی فروش ها را به کلاس دیگری انتقال دهید." } } ```