#P1078
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) می باشد. لطفا قبل از انجام هر عملیاتی فروش ها را به کلاس دیگری انتقال دهید."
}
}