# PATCH /v2/charter/reservation/refund/undo

# Charter: Undo Reservation Refund

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter%2Fres"><div class="endpoint-info"><div>**URL:** `/v2/charter/reservation/refund/undo`</div><div>**Method:** <span class="method-patch">PATCH</span></div><div>**Controller:** CharterController@undoRefundCharterReservation</div><div>**Middleware Stack:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-jwt">- دسترسی معتبر JWT

</div>## Request Body (JSON)

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>main\_id</td><td>integer</td><td>**(الزامی)** شناسه چارتر اصلی. این فیلد برای تعیین نوع چارتر (route یا accommodation) و انتخاب جدول صحیح از پایگاه داده استفاده می‌شود.</td></tr><tr><td>reserve\_id</td><td>integer</td><td>**(الزامی)** شناسه رزروی که عملیات استرداد آن باید لغو شود.</td></tr></tbody></table>

</div>## Logic Details

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

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

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

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

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

<div class="api-docs" id="bkmrk-%D9%85%D8%AA%D8%AF-reservationcontr">- متد `ReservationController::capacityItemCharter` فراخوانی می‌شود تا ظرفیت باقی‌مانده آیتمی که رزرو در اصل به آن تعلق داشته، محاسبه گردد.
- **منطق شرطی بر اساس سن مسافر:**
    - **اگر مسافر بزرگسال یا کودک باشد (`passenger_age_title != 'infant'`):** سیستم بررسی ظرفیت را نادیده می‌گیرد و فرض می‌کند که بازگرداندن رزرو همیشه امکان‌پذیر است. در واقع، این مسافران فضایی را اشغال نکرده بودند که اکنون نیاز به بازپس‌گیری آن باشد.
    - **اگر مسافر نوزاد باشد (`passenger_age_title == 'infant'`):** سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده آیتم (`$capacity['total']`) حداقل `1` است یا خیر. این بدان معناست که برای بازگرداندن یک رزرو نوزاد، باید حتماً یک جای خالی وجود داشته باشد.

</div>### ۳. اجرای عملیات

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1-%D8%B5%D9%88%D8%B1%D8%AA-%D9%88%D8%AC%D9%88%D8%AF-%D8%B8%D8%B1%D9%81%DB%8C%D8%AA-%DA%A9">- **در صورت وجود ظرفیت کافی (یا عدم نیاز به بررسی):**
    1. **به‌روزرسانی رزرو اصلی:** در جدول رزروها، رکورد مربوط به `reserve_id` به‌روزرسانی می‌شود: 
        - `status` به `1` (قطعی) بازمی‌گردد.
        - `refund_id` به `NULL` تغییر می‌کند تا ارتباط با رکورد استرداد قطع شود.
    2. **به‌روزرسانی رکورد استرداد:** در جدول `charter_refunds`، رکوردی که قبلاً برای این رزرو ثبت شده بود، وضعیتش به `2` تغییر می‌کند. این کار به معنای "باطل شدن" یا "لغو شدن" آن رکورد استرداد است.
    
    **نکته:** رکورد استرداد حذف نمی‌شود، بلکه وضعیت آن تغییر می‌کند تا سوابق عملیات حفظ شود.
- **در صورت عدم وجود ظرفیت کافی (فقط برای نوزادان):**
    - عملیات متوقف شده و یک خطای `400 Bad Request` با کد `1008` بازگردانده می‌شود که نشان‌دهنده تکمیل بودن ظرفیت است.

</div>## Response Structure

### پاسخ موفق

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

### پاسخ‌های خطا

<div class="api-docs" id="bkmrk-%DA%A9%D8%AF-400-bad-request%3A-">- **کد `400 Bad Request`:** این خطا در یکی از دو حالت زیر رخ می‌دهد:   
    \- \*\*کمبود ظرفیت برای نوزاد:\*\* 
    - `code`: 1008
    - `message`: "ظرفیت آیتم مورد نظر تکمیل شده است." (یا پیام مشابه از تابع `staticGetErrorDetails`)
    
      
    \- \*\*خطای عمومی یا استثنا (Exception):\*\* 
    - اگر `reserve_id` نامعتبر باشد یا هر خطای دیگری در پایگاه داده رخ دهد.
    - ساختار پاسخ شامل جزئیات کامل خطا برای اشکال‌زدایی خواهد بود.

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28patch-%2Freserv"><div class="flowchart"><div class="flow-item">Start (PATCH /reservation/refund/undo)</div><div class="flow-arrow">↓</div><div class="flow-item">Receive Request Body:  
<small>`main_id`, `reserve_id`</small></div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">Fetch the full reservation record using `reserve_id`</div><div class="flow-arrow">↓</div><div class="flow-decision" style="background-color: #fff9c4;">Is capacity check required?  
<small>(Only if `passenger\_age\_title` is 'infant')</small></div><div class="flow-split"><div class="flow-path"><div class="flow-arrow">↓ Yes (Infant)</div><div class="flow-decision" style="background-color: #fff9c4;">Is `capacity['total']` &gt;= 1?</div><div class="flow-split"><div class="flow-path"><div class="flow-arrow">↓ Yes</div><div class="flow-item-process" style="background-color: #e8f5e9;">1. Update reservation: `status=1`, `refund_id=NULL`  
2. Update refund record: `status=2`</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 204 No Content</div></div><div class="flow-path"><div class="flow-arrow">↓ No</div><div class="flow-item-error">Return 400 - Code 1008 (Capacity Full)</div></div></div></div><div class="flow-path"><div class="flow-arrow">↓ No (Adult/Child)</div><div class="flow-item-process" style="background-color: #e8f5e9;">1. Update reservation: `status=1`, `refund_id=NULL`  
2. Update refund record: `status=2`</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 204 No Content</div></div></div><div class="flow-error-path" style="margin-top: 20px; clear: both;"><div class="flow-arrow-error">→ On Any General Exception</div><div class="flow-item-error">Return 400 Bad Request with Error Trace</div></div></div></div>