# PUT /v2/charter/reservation/transfer

# Charter: Transfer Reservations

این اندپوینت یک قابلیت مدیریتی قدرتمند برای انتقال یک یا چند رزرو از یک چارتر/آیتم به چارتر/آیتم دیگر فراهم می‌کند. فرآیند انتقال تنها در صورتی انجام می‌شود که چارتر مقصد ظرفیت کافی برای پذیرش تمام رزروهای درخواستی را داشته باشد. این عملیات برای جابجایی مسافران بین پروازها یا اتاق‌های مختلف بسیار کاربردی است.

<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/transfer`</div><div>**Method:** <span class="method-put">PUT</span></div><div>**Controller:** CharterController@transferCharterReservation</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>goal</td><td>object</td><td>**(الزامی)** آبجکتی که اطلاعات چارتر و آیتم مقصد را مشخص می‌کند.</td></tr><tr><td>goal.main\_id</td><td>integer</td><td>شناسه چارتر مقصد.</td></tr><tr><td>goal.item\_id</td><td>integer</td><td>شناسه آیتم (مانند اتاق یا پرواز) در چارتر مقصد.</td></tr><tr><td>items</td><td>array\[integer\]</td><td>**(الزامی)** آرایه‌ای شامل شناسه‌های رزروهایی که باید به مقصد جدید منتقل شوند.</td></tr></tbody></table>

</div>## Logic Details

منطق اصلی این اندپوینت بر پایه یک بررسی ظرفیت و سپس اجرای یک سری به‌روزرسانی‌های متوالی استوار است.

### ۱. بررسی ظرفیت مقصد

اولین و مهم‌ترین گام، فراخوانی متد `ReservationController::capacityItemCharter` برای چارتر و آیتم مقصد (`goal.main_id` و `goal.item_id`) است. این متد ظرفیت کل را محاسبه کرده و تعداد رزروهای قطعی، گارانتی و قفل‌های موقت را از آن کم می‌کند تا ظرفیت باقی‌مانده واقعی (`balance`) را به دست آورد.

### ۲. تصمیم‌گیری بر اساس ظرفیت

سپس، سیستم ظرفیت باقی‌مانده (`$capacity['balance']`) را با تعداد رزروهایی که قرار است منتقل شوند (`count($request->items)`) مقایسه می‌کند.

<div class="api-docs" id="bkmrk-%D8%A7%DA%AF%D8%B1-%D8%B8%D8%B1%D9%81%DB%8C%D8%AA-%DA%A9%D8%A7%D9%81%DB%8C-%D8%A8%D8%A7%D8%B4%D8%AF-">- **اگر ظرفیت کافی باشد (`balance >= count(items)`):**   
    عملیات انتقال ادامه می‌یابد. سیستم برای هر شناسه رزرو در آرایه `items`، یک دستور `UPDATE` مجزا در پایگاه داده اجرا می‌کند. در هر دستور، فیلدهای زیر برای رکورد رزرو مربوطه به‌روزرسانی می‌شوند: 
    - `main_id` به شناسه چارتر مقصد تغییر می‌کند.
    - `item_id` به شناسه آیتم مقصد تغییر می‌کند.
    - `updated_at` با زمان فعلی سرور تنظیم می‌شود.
    
    **نکته:** به‌روزرسانی‌ها به صورت تکی در یک حلقه (loop) انجام می‌شوند، نه به صورت یک دستور گروهی (bulk update).
- **اگر ظرفیت کافی نباشد:**   
    عملیات متوقف شده و یک خطای `422 Unprocessable Entity` به کاربر بازگردانده می‌شود تا اعلام کند که مقصد فضای کافی برای پذیرش این تعداد رزرو را ندارد.

</div>## Response Structure

### پاسخ موفق

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

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

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

</div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28put-%2Freservat"><div class="flowchart"><div class="flow-item">Start (PUT /reservation/transfer)</div><div class="flow-arrow">↓</div><div class="flow-item">Receive Request Body:  
<small>`goal` (main\_id, item\_id) and `items` (array of IDs)</small></div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">Calculate available capacity (`balance`) for destination item (`goal.item_id`)</div><div class="flow-arrow">↓</div><div class="flow-decision" style="background-color: #fff9c4;">Is `balance` &gt;= `count(items)`?</div><div class="flow-split"><div class="flow-path"><div class="flow-arrow">↓ Yes</div><div class="flow-item-process" style="background-color: #e8f5e9;">**Loop through each `item` ID:**  
<small> `UPDATE reservation_table`  
`SET main_id = goal.main_id,`  
`item_id = goal.item_id`  
`WHERE id = item_id` </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">Return 422 Unprocessable Entity  
<small>Message: "ظرفیت چارتر مورد نظر تکمیل می باشد."</small></div></div></div><div class="flow-error-path" style="margin-top: 20px;"><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>