# PATCH /v2/charter/reservation/undo

# Charter: Undo Reservation Deletion

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

<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/undo`</div><div>**Method:** <span class="method-patch">PATCH</span></div><div>**Controller:** CharterController@undoDeleteCharterReservation</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>reserves\_id</td><td>integer</td><td>**(الزامی)** شناسه رزرو مشخصی که باید بازگردانی شود. (توجه: با وجود نام جمع، این فیلد فقط یک شناسه را می‌پذیرد).</td></tr></tbody></table>

</div>## Logic Details

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

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

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

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

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

<div class="api-docs" id="bkmrk-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%85%D8%B3%D8%A7%D9%81%D8%B1%D8%A7%D9%86-%D8%A8%D8%B2%D8%B1%DA%AF%D8%B3%D8%A7%D9%84">- **برای مسافران بزرگسال و کودک (Non-Infant):**   
    سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده `>= 0` است. از آنجایی که ظرفیت نمی‌تواند منفی باشد، این شرط **همیشه درست است**. این یعنی بازگردانی رزرو بزرگسال/کودک به بررسی ظرفیت نیازی ندارد و همیشه موفقیت‌آمیز خواهد بود. فرض بر این است که ظرفیت این مسافر قبلاً اشغال شده بوده و اکنون صرفاً به حالت فعال بازمی‌گردد.
- **برای مسافران نوزاد (Infant):**   
    سیستم بررسی می‌کند که آیا ظرفیت باقی‌مانده `>= 1` است. این بدان معناست که برای بازگرداندن یک رزرو نوزاد، باید حداقل یک جای خالی وجود داشته باشد. این منطق نشان می‌دهد که نوزادان ممکن است ظرفیت متفاوتی (مثلاً ظرفیت صندلی پرواز) را اشغال کنند که باید مجدداً بررسی شود.

</div>### ۳. عملیات پایگاه داده

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1-%D8%B5%D9%88%D8%B1%D8%AA-%D9%85%D9%88%D9%81%D9%82%DB%8C%D8%AA%E2%80%8C%D8%A2%D9%85%DB%8C%D8%B2-">- **در صورت موفقیت‌آمیز بودن بررسی ظرفیت:** سیستم یک دستور `UPDATE` اجرا کرده و مقادیر زیر را برای رزرو مورد نظر تنظیم می‌کند: 
    - `status` به **1** (قطعی)
    - `updated_at` به زمان فعلی
    - `deleted_at` به **NULL**
- **در صورت شکست در بررسی ظرفیت (فقط برای نوزاد):** عملیات متوقف شده و یک خطای مشخص به کاربر بازگردانده می‌شود.

</div><div class="api-docs" id="bkmrk--1"></div>## Response Structure

### پاسخ موفق

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

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

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

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28patch-%2Freserv"><div class="flowchart"><div class="flow-item">Start (PATCH /reservation/undo)</div><div class="flow-arrow">↓</div><div class="flow-item">Find reservation using `main_id` &amp; `reserves_id`.</div><div class="flow-arrow">↓</div><div class="flow-decision">Reservation Found?</div><div class="flow-split"><div class="flow-path"><div class="flow-arrow">↓ Yes</div><div class="flow-item-process" style="background-color: #e3f2fd;">Check remaining capacity via `capacityItemCharter`</div><div class="flow-arrow">↓</div><div class="flow-decision">Is passenger an infant?</div><div class="flow-split"><div class="flow-path"><div class="flow-arrow">↓ No (Adult/Child)</div><div class="flow-item" style="background-color: #f1f8e9;">Proceed to update (Capacity check is bypassed)</div></div><div class="flow-path"><div class="flow-arrow">↓ Yes (Infant)</div><div class="flow-decision" style="background-color: #fff9c4;">Capacity &gt;= 1?</div><div class="flow-arrow">No → Return 400 (Code 1008)</div><div class="flow-arrow">Yes ↓</div></div></div><div class="flow-join">  
</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e8f5e9;">**DB UPDATE:**  
<small> SET status = 1  
SET updated\_at = NOW()  
SET deleted\_at = NULL </small></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">Exception Occurs  
(e.g., Cannot read property of null)</div><div class="flow-arrow">↓</div><div class="flow-item-error">Return 400 Bad Request  
with trace</div></div></div></div></div>