Skip to main content
#P1677

PATCH /v2/charter/reservation/refund/undo

Charter: Undo Reservation Refund

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

Request Overview

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

Access Control

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

Request Body (JSON)

Field Type Description
main_id integer (الزامی) شناسه چارتر اصلی. این فیلد برای تعیین نوع چارتر (route یا accommodation) و انتخاب جدول صحیح از پایگاه داده استفاده می‌شود.
reserve_id integer (الزامی) شناسه رزروی که عملیات استرداد آن باید لغو شود.

Logic Details

فرآیند لغو استرداد شامل سه گام اصلی است: دریافت اطلاعات، بررسی ظرفیت، و اجرای به‌روزرسانی‌ها.

۱. دریافت اطلاعات رزرو

با استفاده از main_id و reserve_id ارسالی، سیستم ابتدا رکورد کامل رزرو مورد نظر را از جدول مربوطه (charter_route_reservations یا charter_accommodation_reservations) استخراج می‌کند. اگر رزرو یافت نشود، یک استثنا (Exception) رخ داده و عملیات متوقف می‌شود.

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

این مهم‌ترین بخش منطق است.

  • متد ReservationController::capacityItemCharter فراخوانی می‌شود تا ظرفیت باقی‌مانده آیتمی که رزرو در اصل به آن تعلق داشته، محاسبه گردد.
  • منطق شرطی بر اساس سن مسافر:
    • اگر مسافر بزرگسال یا کودک باشد (passenger_age_title != 'infant'): سیستم بررسی ظرفیت را نادیده می‌گیرد و فرض می‌کند که بازگرداندن رزرو همیشه امکان‌پذیر است. در واقع، این مسافران فضایی را اشغال نکرده بودند که اکنون نیاز به بازپس‌گیری آن باشد.
    • اگر مسافر نوزاد باشد (passenger_age_title == 'infant'): سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده آیتم ($capacity['total']) حداقل 1 است یا خیر. این بدان معناست که برای بازگرداندن یک رزرو نوزاد، باید حتماً یک جای خالی وجود داشته باشد.

۳. اجرای عملیات

  • در صورت وجود ظرفیت کافی (یا عدم نیاز به بررسی):
    1. به‌روزرسانی رزرو اصلی: در جدول رزروها، رکورد مربوط به reserve_id به‌روزرسانی می‌شود:
      • status به 1 (قطعی) بازمی‌گردد.
      • refund_id به NULL تغییر می‌کند تا ارتباط با رکورد استرداد قطع شود.
    2. به‌روزرسانی رکورد استرداد: در جدول charter_refunds، رکوردی که قبلاً برای این رزرو ثبت شده بود، وضعیتش به 2 تغییر می‌کند. این کار به معنای "باطل شدن" یا "لغو شدن" آن رکورد استرداد است.

    نکته: رکورد استرداد حذف نمی‌شود، بلکه وضعیت آن تغییر می‌کند تا سوابق عملیات حفظ شود.

  • در صورت عدم وجود ظرفیت کافی (فقط برای نوزادان):
    • عملیات متوقف شده و یک خطای 400 Bad Request با کد 1008 بازگردانده می‌شود که نشان‌دهنده تکمیل بودن ظرفیت است.

Response Structure

پاسخ موفق

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

پاسخ‌های خطا

  • کد 400 Bad Request: این خطا در یکی از دو حالت زیر رخ می‌دهد:
    - **کمبود ظرفیت برای نوزاد:**
    • code: 1008
    • message: "ظرفیت آیتم مورد نظر تکمیل شده است." (یا پیام مشابه از تابع `staticGetErrorDetails`)

    - **خطای عمومی یا استثنا (Exception):**
    • اگر reserve_id نامعتبر باشد یا هر خطای دیگری در پایگاه داده رخ دهد.
    • ساختار پاسخ شامل جزئیات کامل خطا برای اشکال‌زدایی خواهد بود.

Flowchart

Start (PATCH /reservation/refund/undo)
↓
Receive Request Body:
main_id, reserve_id
↓
Fetch the full reservation record using `reserve_id`
↓
Is capacity check required?
(Only if `passenger_age_title` is 'infant')
↓ Yes (Infant)
Is `capacity['total']` >= 1?
↓ Yes
1. Update reservation: `status=1`, `refund_id=NULL`
2. Update refund record: `status=2`
↓
Return 204 No Content
↓ No
Return 400 - Code 1008 (Capacity Full)
↓ No (Adult/Child)
1. Update reservation: `status=1`, `refund_id=NULL`
2. Update refund record: `status=2`
↓
Return 204 No Content
→ On Any General Exception
Return 400 Bad Request with Error Trace
Back to top