Skip to main content
#P1674

PATCH /v2/charter/reservation/undo

Charter: Undo Reservation Deletion

این اندپوینت برای بازگردانی یک رزرو که قبلاً به صورت نرم (soft delete) حذف شده است، استفاده می‌شود. عملیات اصلی، تغییر وضعیت (status) رزرو از 2 (حذف شده) به 1 (قطعی) و پاک کردن مقدار فیلد deleted_at است. نکته بسیار مهم در این فرآیند، بررسی مجدد ظرفیت خالی قبل از بازگردانی است که دارای منطق متفاوتی برای مسافران نوزاد و غیرنوزاد می‌باشد.

Request Overview

URL: /v2/charter/reservation/undo
Method: PATCH
Controller: CharterController@undoDeleteCharterReservation
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT

Request Body (JSON)

Field Type Description
main_id integer (الزامی) شناسه چارتر اصلی. این شناسه برای تشخیص نوع چارتر (مثلاً 'route' یا 'accommodation') و پیدا کردن جدول صحیح رزروها به کار می‌رود.
reserves_id integer (الزامی) شناسه رزرو مشخصی که باید بازگردانی شود. (توجه: با وجود نام جمع، این فیلد فقط یک شناسه را می‌پذیرد).

Logic Details

فرآیند بازگردانی با یک بررسی ظرفیت حیاتی همراه است تا از فروش بیش از حد جلوگیری شود.

۱. یافتن رزرو و بررسی اولیه

ابتدا سیستم با استفاده از main_id و reserves_id، رکورد رزرو حذف شده را از جدول مربوطه پیدا می‌کند. اگر رکوردی یافت نشود، یک خطای عمومی رخ داده و پاسخ 400 بازگردانده می‌شود.

۲. بررسی ظرفیت (Capacity Check)

این مهم‌ترین بخش منطق است. سیستم متد ReservationController::capacityItemCharter را فراخوانی می‌کند تا ظرفیت باقی‌مانده واقعی را محاسبه کند. این متد با کسر کردن رزروهای قطعی، گارانتی و قفل‌های موقت از ظرفیت کل، عدد نهایی را به دست می‌آورد. سپس، یک شرط بر اساس نوع مسافر اعمال می‌شود:

  • برای مسافران بزرگسال و کودک (Non-Infant):
    سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده >= 0 است. از آنجایی که ظرفیت نمی‌تواند منفی باشد، این شرط همیشه درست است. این یعنی بازگردانی رزرو بزرگسال/کودک به بررسی ظرفیت نیازی ندارد و همیشه موفقیت‌آمیز خواهد بود. فرض بر این است که ظرفیت این مسافر قبلاً اشغال شده بوده و اکنون صرفاً به حالت فعال بازمی‌گردد.
  • برای مسافران نوزاد (Infant):
    سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده >= 1 است. این بدان معناست که برای بازگرداندن یک رزرو نوزاد، باید حداقل یک جای خالی وجود داشته باشد. این منطق نشان می‌دهد که نوزادان ممکن است ظرفیت متفاوتی (مثلاً ظرفیت صندلی پرواز) را اشغال کنند که باید مجدداً بررسی شود.

۳. عملیات پایگاه داده

 

  • در صورت موفقیت‌آمیز بودن بررسی ظرفیت: سیستم یک دستور UPDATE اجرا کرده و مقادیر زیر را برای رزرو مورد نظر تنظیم می‌کند:
    • status به 1 (قطعی)
    • updated_at به زمان فعلی
    • deleted_at به NULL
  • در صورت شکست در بررسی ظرفیت (فقط برای نوزاد): عملیات متوقف شده و یک خطای مشخص به کاربر بازگردانده می‌شود.

 

Response Structure

پاسخ موفق

اگر بازگردانی با موفقیت انجام شود، سرور یک پاسخ خالی با کد وضعیت 204 No Content ارسال می‌کند.

پاسخ‌های خطا

  • کد 400 Bad Request با code: 1008: این خطا فقط زمانی رخ می‌دهد که یک رزرو نوزاد در حال بازگردانی باشد اما ظرفیت آیتم تکمیل شده باشد.
    متن خطا: "ظرفیت این آیتم تکمیل شده است"
  • کد 400 Bad Request (عمومی): در صورت بروز هر خطای پیش‌بینی نشده دیگر، مانند یافت نشدن رزرو، یک پاسخ خطای عمومی شامل جزئیات استثنا (trace) برای اشکال‌زدایی بازگردانده می‌شود.

Flowchart

Start (PATCH /reservation/undo)
↓
Find reservation using `main_id` & `reserves_id`.
↓
Reservation Found?
↓ Yes
Check remaining capacity via `capacityItemCharter`
↓
Is passenger an infant?
↓ No (Adult/Child)
Proceed to update (Capacity check is bypassed)
↓ Yes (Infant)
Capacity >= 1?
No → Return 400 (Code 1008)
Yes ↓

↓
DB UPDATE:
SET status = 1
SET updated_at = NOW()
SET deleted_at = NULL
↓
Return 204 No Content
↓ No
Exception Occurs
(e.g., Cannot read property of null)
↓
Return 400 Bad Request
with trace
Back to top