Skip to main content
#P1680

POST /v2/charter/reservation/plan/update

Charter: Update Accommodation Reservation Room Plan

این اندپوینت برای تغییر چینش اتاق‌های تخصیص داده شده به یک رزرو اقامتگاهی موجود استفاده می‌شود. کاربرد اصلی آن این است که به اپراتور اجازه می‌دهد اتاق فیزیکی (`room_id`) مربوط به یک یا چند تاریخ (`date`) خاص از یک رزرو (`reservation_id`) را تغییر دهد. برای مثال، اگر یک رزرو برای سه شب در اتاق ۱۰۱ ثبت شده، می‌توان با استفاده از این اندپوینت، شب دوم اقامت را به اتاق ۱۰۵ منتقل کرد.
نکته مهم تجاری: شناسه‌های ورودی (id و room_id) شناسه‌های عمومی هستند و سیستم به صورت داخلی عدد 10,000 را از آن‌ها کم می‌کند تا به شناسه‌های واقعی در پایگاه داده دسترسی پیدا کند.

Request Overview

URL: /v2/charter/reservation/plan/update
Method: POST
Controller: CharterController@updatePlanCharterReservation
Middleware Stack: authWithJwt

Access Control

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

Request Body (JSON)

بدنه درخواست باید شامل یک فیلد data باشد که آرایه‌ای از اشیاء است. هر شیء در این آرایه نشان‌دهنده یک تغییر در تخصیص اتاق برای یک تاریخ مشخص است.

Field Type Description
data array of objects (الزامی) آرایه‌ای از دستورات به‌روزرسانی. هر شیء در این آرایه باید شامل فیلدهای زیر باشد.

ساختار شیء در آرایه `data`

Field Type Description
id integer (الزامی) شناسه عمومی رزرو. سیستم به صورت خودکار مقدار 10,000 را از این عدد کم می‌کند تا reservation_id واقعی را به دست آورد.
date string (الزامی) تاریخ مشخصی که تخصیص اتاق برای آن باید تغییر کند. فرمت باید YYYY-MM-DD باشد.
room_id integer (الزامی) شناسه عمومی اتاق جدید. سیستم به صورت خودکار مقدار 10,000 را از این عدد کم می‌کند تا شناسه واقعی اتاق در جدول charter_accommodation_rooms را به دست آورد.

Example Request Body

در مثال زیر، برای رزرو با شناسه عمومی 10123، اتاق تخصیص داده شده برای تاریخ 2025-10-20 به اتاقی با شناسه عمومی 10055 تغییر می‌کند. همچنین برای همین رزرو، اتاق تاریخ 2025-10-21 به اتاق 10056 منتقل می‌شود.

{
  "data": [
    {
      "id": 10123,
      "date": "2025-10-20",
      "room_id": 10055
    },
    {
      "id": 10123,
      "date": "2025-10-21",
      "room_id": 10056
    }
  ]
}

Logic Details

فرآیند در یک بلوک try...catch برای مدیریت خطاها اجرا می‌شود.

۱. اعتبارسنجی ورودی

  • سیستم ابتدا بررسی می‌کند که آیا فیلد data در درخواست وجود دارد و خالی نیست (isset($request->data) && $request->data).
  • اگر data وجود نداشته باشد یا یک آرایه خالی باشد، یک خطای 400 Bad Request با پیام مشخص بازگردانده می‌شود.

۲. پردازش حلقه به‌روزرسانی

  • اگر اعتبارسنجی موفقیت‌آمیز باشد، سیستم بر روی هر شیء (`$data`) در آرایه request->data یک حلقه اجرا می‌کند.
  • در هر تکرار، یک دستور UPDATE در پایگاه داده بر روی جدول charter_reservation_accommodation_rooms اجرا می‌شود.
  • شرط‌های به‌روزرسانی (WHERE Clause):
    • 'reservation_id' باید برابر با $data['id'] - 10000 باشد.
    • 'date' باید برابر با $data['date'] باشد.

    این دو شرط با هم، رکورد دقیق مربوط به یک شب خاص از یک رزرو خاص را هدف قرار می‌دهند.

  • مقادیر جدید (UPDATE Clause):
    • ستون room_id به مقدار $data['room_id'] - 10000 به‌روزرسانی می‌شود.
    • ستون updated_at با تاریخ و زمان فعلی پر می‌شود.

۳. مدیریت خطا

  • اگر در هر مرحله از اجرای کوئری‌های پایگاه داده خطایی (مانند عدم وجود رکورد، خطای کلید خارجی و...) رخ دهد، اجرای کد به بلوک catch منتقل شده و یک پاسخ خطای 400 Bad Request با جزئیات کامل استثنا (Exception) بازگردانده می‌شود.

Response Structure

پاسخ موفق

در صورتی که تمام دستورات به‌روزرسانی با موفقیت اجرا شوند، سرور یک پاسخ 200 OK با ساختار زیر بازمی‌گرداند.

  • Status Code: 200 OK
  • Body: 
    {
  "payload": true,
  "meta": {
    "timestamp": 1733286000
  }
}

پاسخ خطا (ورودی نامعتبر)

اگر فیلد data در درخواست ارسال نشود یا خالی باشد.

  • Status Code: 400 Bad Request
  • Body: 
    {
  "error": {
    "message": "The data field is required."
  },
  "meta": {
    "timestamp": 1733286005
  }
}

پاسخ خطا (استثنای عمومی)

در صورت بروز هرگونه خطای پایگاه داده یا خطای دیگر در حین اجرا.

  • Status Code: 400 Bad Request
  • Body: 
    {
  "error": {
    "code": "23000",
    "message": "SQLSTATE[23000]: Integrity constraint violation: ... (or any other DB error)",
    "trace": [
      // ... Stack trace for debugging ...
    ]
  }
}

Flowchart

Start (POST /reservation/plan/update)
↓
Receive Request Body
↓
Is `data` field present & not empty?
↓ Yes
Loop through each item in `data` array:
- Execute `UPDATE charter_reservation_accommodation_rooms`
- `SET room_id = (item.room_id - 10000)`
- `WHERE reservation_id = (item.id - 10000) AND date = item.date`
↓
Return 200 OK with `{"payload": true, ...}`
↓ No
Return 400 with `{"error": {"message": "The data field is required."}, ...}`
→ On Any DB Exception
Return 400 with Full Exception Trace
Back to top