#P1672
PUT /v2/charter/reservation
Charter: Update Reservation(s)
این اندپوینت دو قابلیت مجزا اما مرتبط را فراهم میکند. بسته به پارامتر apply_all، میتوان یک رزرو خاص را با تمام جزئیاتش بهروزرسانی کرد، یا فقط اطلاعات مالی (مبلغ) را برای تمام رزروهای فعال یک چارتر به صورت یکجا تغییر داد. این متد برای اصلاح اطلاعات مسافر یا اعمال تغییرات قیمت کلی بسیار کاربردی است.
Request Overview
URL:
/v2/charter/reservationMethod: PUT
Controller: CharterController@updateCharterReservation
Middleware Stack: authWithJwt
Access Control
- دسترسی معتبر JWT
Request Body (JSON)
ساختار بدنه درخواست بسته به مقدار فیلد apply_all متفاوت است.
| Field | Type | Description | Mode |
|---|---|---|---|
| main_id | integer | (الزامی) شناسه چارتر اصلی | هر دو |
| apply_all | boolean | اگر true باشد، حالت بهروزرسانی گروهی فعال میشود. در غیر این صورت (یا عدم وجود)، حالت تکی فعال است. |
هر دو |
| reserve_id | integer | (الزامی در حالت تکی) شناسه رزرواسیون مورد نظر برای ویرایش. | تکی |
| passenger | object | (الزامی در حالت تکی) آبجکت کامل و بهروز شده اطلاعات مسافر. | تکی |
| financial | object | (الزامی) شامل کلید payable برای بهروزرسانی مبلغ. |
هر دو |
| mobile | string | شماره موبایل جدید (اختیاری). | تکی |
| string | ایمیل جدید (اختیاری). | تکی | |
| guarantor | string | شناسه ضامن (در صورت وجود). این فیلد اطلاعات warranty را تنظیم میکند. |
تکی |
Logic Details
این متد بر اساس فیلد apply_all به دو شاخه منطقی اصلی تقسیم میشود:
۱. حالت بهروزرسانی تکی (apply_all: false)
این حالت پیشفرض است و برای ویرایش جزئیات یک رزرو مشخص به کار میرود.
- یافتن رزرو: ابتدا سیستم با استفاده از
main_idوreserve_idرزرو مورد نظر را در جدول مربوطه جستجو میکند. اگر یافت نشود، خطای422با پیام "آیتم یافت نشد" بازگردانده میشود. - بررسی وضعیت: یک شرط حیاتی وجود دارد: رزرو فقط در صورتی قابل ویرایش است که وضعیت (
status) آن1(خرید قطعی) یا3(استفاده شده) باشد. در غیر این صورت، خطای422با پیام "آیتم در وضعیت خرید قطعی نمی باشد" بازگردانده میشود. - آمادهسازی دادهها:
- آبجکت
passengerبه صورت JSON در فیلد مربوطه ذخیره میشود. - مبلغ نهایی از
financial.payableاستخراج و در فیلدamountذخیره میشود. - فیلدهای
mobileوemailبهروزرسانی میشوند. - اگر فیلد
guarantorارسال شده باشد، فیلدwarranty_typeبه 'colleague' و فیلدwarrantyبا مقدارguarantorپر میشود.
- آبجکت
- عملیات پایگاه داده: اطلاعات جدید در رکورد مربوطه در پایگاه داده جایگزین میشود.
۲. حالت بهروزرسانی گروهی (apply_all: true)
این حالت برای تغییر یکپارچه قیمت تمام رزروهای یک چارتر استفاده میشود.
- هدفگیری رزروها: سیستم تمام رکوردهایی را که
main_idآنها با مقدار ارسالی برابر است و استرداد نشدهاند (refund_id IS NULL) انتخاب میکند. این شرط تضمین میکند که رزروهای کنسل شده تحت تأثیر قرار نگیرند. - آمادهسازی دادهها: تنها فیلدهایی که برای بهروزرسانی آماده میشوند عبارتند از:
amountکه ازfinancial.payableگرفته میشود.updated_atکه با زمان فعلی تنظیم میشود.
- عملیات پایگاه داده: یک دستور
UPDATEگروهی بر روی تمام رکوردهای انتخاب شده اجرا میشود و مبلغ آنها را تغییر میدهد.
Response Structure
پاسخ موفق
در صورت موفقیتآمیز بودن هر یک از دو حالت، سرور یک پاسخ خالی با کد وضعیت 204 No Content باز میگرداند که به معنای انجام موفقیتآمیز عملیات بدون نیاز به بازگرداندن محتوا است.
پاسخهای خطا
- کد
422 Unprocessable Entity: در صورتی که رزرو یافت نشود یا وضعیت آن برای ویرایش مناسب نباشد. - کد
400 Bad Request: در صورت بروز هرگونه خطای پیشبینی نشده در سرور. این پاسخ شامل جزئیات خطا (trace) برای اشکالزدایی است.
Flowchart
Start (PUT /reservation)
↓
apply_all == true?
↓ No
Mode: Single Update
Find reservation by `reserve_id`
Find reservation by `reserve_id`
↓
Reservation Found?
No → Return 422 (Not Found)
Yes ↓
Status == 1 OR 3?
No → Return 422 (Invalid Status)
Yes ↓
Prepare data:
passenger, amount, mobile, email, warranty...
passenger, amount, mobile, email, warranty...
↓
DB: UPDATE single record
↓ Yes
Mode: Bulk Update
Prepare data: `amount`, `updated_at`
Prepare data: `amount`, `updated_at`
↓
DB: UPDATE all records
WHERE main_id = ? AND refund_id IS NULL
WHERE main_id = ? AND refund_id IS NULL
↓
Return 204 No Content