Skip to main content
#P1676

PATCH /character/reservation/refund

Charter: Process Reservation Refund

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

Request Overview

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

Access Control

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

Request Body (JSON)

Field Type Description
type string (الزامی) نوع چارتر را مشخص می‌کند تا جداول پایگاه داده مربوطه هدف قرار گیرند. مقادیر مجاز: "accommodation" یا "route".
items array[integer] (الزامی) آرایه‌ای از شناسه‌های رزروهایی که باید مسترد شوند.
financial object (الزامی) آبجکتی شامل جزئیات جریمه کنسلی.
financial.value_type string (الزامی) نوع محاسبه جریمه. مقادیر مجاز: "percent" (درصدی از مبلغ قابل پرداخت) یا "currency" (مبلغ ثابت).
financial.value number (الزامی) مقدار جریمه. اگر value_type برابر percent باشد، این عدد بین 0 تا 100 است.
financial.description string (الزامی) توضیحی برای دلیل استرداد و جریمه.

Logic Details

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

فاز ۱: اعتبارسنجی و محاسبه جریمه (در یک حلقه)

سیستم در یک حلقه، هر شناسه رزرو ارسال شده در آرایه items را پردازش می‌کند:

  1. دریافت اطلاعات رزرو: ابتدا رزرو مربوط به item فعلی از پایگاه داده خوانده می‌شود.
    • اگر رزرو یافت نشود: عملیات فوراً متوقف شده و خطای 422 با کد 1000 و پیام "آیتم [ID+10000] یافت نشد" بازگردانده می‌شود.
  2. بررسی وضعیت رزرو: وضعیت (status) رزرو بررسی می‌شود.
    • اگر وضعیت برابر 1 (قطعی) نباشد: عملیات متوقف شده و خطای 422 با کد 1000 و پیام "آیتم [ID+10000] در وضعیت خرید قطعی نمی باشد" بازگردانده می‌شود.
  3. محاسبه جریمه (Penalty):
    • اطلاعات مالی فعلی رزرو از فیلد financial (که به صورت JSON ذخیره شده) استخراج می‌شود.
    • بر اساس request->financial['value_type']:
      • اگر percent باشد: penalty = (original_payable * value) / 100
      • اگر currency باشد: penalty = value
  4. آماده‌سازی داده‌های جدید: یک آبجکت اطلاعاتی جدید برای این رزرو ساخته شده و به صورت موقت در یک آرایه به نام $queryInsert نگهداری می‌شود. این آبجکت شامل اطلاعاتی است که باید در جدول charter_refunds درج شود، از جمله آبجکت مالی جدید که در آن مبلغ قابل پرداخت (payable) به صورت original_payable - penalty محاسبه شده است.

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

فاز ۲: اجرای تغییرات در پایگاه داده

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

  1. سیستم روی آرایه $queryInsert (که در فاز اول آماده شده) حلقه می‌زند.
  2. درج رکورد استرداد: برای هر آیتم، یک رکورد جدید در جدول charter_refunds با اطلاعات محاسبه شده درج می‌شود و شناسه (ID) رکورد جدید دریافت می‌گردد ($refundId).
  3. به‌روزرسانی رزرو اصلی: رزرو اصلی در جدول charter_reservations به‌روزرسانی می‌شود:
    • فیلد status به 3 (مسترد شده) تغییر می‌کند.
    • فیلد refund_id با شناسه رکورد استرداد ($refundId) پر می‌شود.
  4. عملیات ویژه برای اقامتگاه: اگر نوع چارتر accommodation باشد، یک عملیات اضافی انجام می‌شود:
    • رکورد(های) مرتبط با این رزرو در جدول charter_reservation_accommodation_rooms نیز حذف نرم (soft delete) می‌شوند (status به 2 تغییر کرده و deleted_at تنظیم می‌شود). این کار باعث آزاد شدن اتاق‌های اختصاص داده شده به این رزرو می‌شود.

Response Structure

پاسخ موفق

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

پاسخ‌های خطا

  • کد 422 Unprocessable Entity: این خطا در یکی از دو حالت زیر در فاز اعتبارسنجی رخ می‌دهد:
    - code: 1000, message: "آیتم [ID] یافت نشد." (زمانی که شناسه رزرو نامعتبر است)
    - code: 1000, message: "آیتم [ID] در وضعیت خرید قطعی نمی باشد." (زمانی که رزرو قبلاً کنسل، حذف یا مسترد شده است)
  • پاسخ استثنا (Exception): در صورت بروز هرگونه خطای پیش‌بینی نشده در حین اجرای منطق (مانند خطای پایگاه داده)، یک پاسخ با ساختار سفارشی بازگردانده می‌شود که برای اشکال‌زدایی مفید است. (معمولاً با کد وضعیت 500 یا 400) 
    {
    "status": false,
    "time": 1670154000,
    "message": "Error message details...",
    "trace": [...]
}

Flowchart

Start (PATCH /reservation/refund)
↓
Receive Request Body:
type, items, financial
↓
Start Loop: For each `id` in `items`
↓
Reservation with `id` exists?
↓ Yes
Reservation `status` == 1?
↓ Yes
1. Calculate penalty
2. Prepare new financial data
3. Add to temporary `$queryInsert` array
↓ No
Return 422: Invalid Status
↓ No
Return 422: Not Found
↓
End Loop
↓
Is `$queryInsert` array not empty?
↓ Yes
Start DB Update Loop:
For each item in `$queryInsert`
↓
1. Insert into `charter_refunds` table
2. Update `charter_reservations`: `status=3`, `refund_id=new_id`
↓
Is `type` == 'accommodation'?
↓ Yes
Soft-delete from `..._rooms` table
↓ No
↓
End DB Update Loop
↓ No
↓
Return 204 No Content
Back to top