Skip to main content
#P1675

PUT /v2/charter/reservation/transfer

Charter: Transfer Reservations

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

Request Overview

URL: /v2/charter/reservation/transfer
Method: PUT
Controller: CharterController@transferCharterReservation
Middleware Stack: authWithJwt

Access Control

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

Request Body (JSON)

Field Type Description
goal object (الزامی) آبجکتی که اطلاعات چارتر و آیتم مقصد را مشخص می‌کند.
goal.main_id integer شناسه چارتر مقصد.
goal.item_id integer شناسه آیتم (مانند اتاق یا پرواز) در چارتر مقصد.
items array[integer] (الزامی) آرایه‌ای شامل شناسه‌های رزروهایی که باید به مقصد جدید منتقل شوند.

Logic Details

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

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

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

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

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

  • اگر ظرفیت کافی باشد (balance >= count(items)):
    عملیات انتقال ادامه می‌یابد. سیستم برای هر شناسه رزرو در آرایه items، یک دستور UPDATE مجزا در پایگاه داده اجرا می‌کند. در هر دستور، فیلدهای زیر برای رکورد رزرو مربوطه به‌روزرسانی می‌شوند:
    • main_id به شناسه چارتر مقصد تغییر می‌کند.
    • item_id به شناسه آیتم مقصد تغییر می‌کند.
    • updated_at با زمان فعلی سرور تنظیم می‌شود.

    نکته: به‌روزرسانی‌ها به صورت تکی در یک حلقه (loop) انجام می‌شوند، نه به صورت یک دستور گروهی (bulk update).

  • اگر ظرفیت کافی نباشد:
    عملیات متوقف شده و یک خطای 422 Unprocessable Entity به کاربر بازگردانده می‌شود تا اعلام کند که مقصد فضای کافی برای پذیرش این تعداد رزرو را ندارد.

Response Structure

پاسخ موفق

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

پاسخ‌های خطا

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

Flowchart

Start (PUT /reservation/transfer)
↓
Receive Request Body:
goal (main_id, item_id) and items (array of IDs)
↓
Calculate available capacity (`balance`) for destination item (`goal.item_id`)
↓
Is `balance` >= `count(items)`?
↓ Yes
Loop through each `item` ID:
UPDATE reservation_table
SET main_id = goal.main_id,
item_id = goal.item_id
WHERE id = item_id
↓
Return 204 No Content
↓ No
Return 422 Unprocessable Entity
Message: "ظرفیت چارتر مورد نظر تکمیل می باشد."
→ On Any General Exception
Return 400 Bad Request with Error Trace
Back to top