Skip to main content
#P1482

POST /base/accommodation/room/update

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/base/accommodation/rooms/update V2BaseController@accommodationRoomsUpdate authWithJwt بروزرسانی نگاشت (Mapping) و اطلاعات اتاق‌های اقامتگاه از طریق سرویس‌های خارجی نظیر SnappTrip.

منطق عملکرد تابع

تابع accommodationRoomsUpdate وظیفه دارد لیست اتاق‌های متصل به اقامتگاه را بازسازی کند. این مسیر فقط برای سرویس‌های خاص فعال است—به‌طور پیش‌فرض برای سرویس snapptrip. پس از حذف اتاق‌های قبلی از جداول accommodation_roomtypes و mapping_roomtypes، کش Redis مربوطه تخلیه شده و از طریق CronController::updateSnapptripMappedAccommodation() عمل بازسازی انجام می‌شود. در سایر سرویس‌ها، تابع با خطای 404 پاسخ می‌دهد.
  • دریافت متغیر service و accommodation_id.
  • بررسی شرط: اگر سرویس برابر با snapptrip باشد → ادامه‌ی عملیات.
  • واکشی شناسه اتاق‌های مرتبط از دو جدول با استفاده از JOIN.
  • حذف رکوردها از هر دو جدول.
  • پاک‌سازی کش Redis مربوط به اقامتگاه هدف.
  • فراخوانی بروزرسانی CronController و بازگرداندن نتیجه آن در قالب کلید payload.
  • در غیر این صورت، بازگشت خطای 404 Not Supported Service.

ورودی‌ها

نام پارامتر نوع داده منبع الزامی توضیح
accommodation_id integer Body بله شناسه اقامتگاه مقصد که اتاق‌های آن بروزرسانی می‌شوند.
service string Body بله نام سرویس هماهنگ‌سازی اتاق‌ها (در حال حاضر فقط snapptrip معتبر است).

نمونه درخواست:

POST /api/v2/base/accommodation/rooms/update
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "accommodation_id": 2231,
  "service": "snapptrip"
}

خروجی (Response)

فیلد نوع داده توضیح
payload boolean نتیجه نهایی عملیات بروزرسانی؛ true در صورت موفقیت.
meta.timestamp integer زمان یونیکس ثبت پاسخ.

نمونه پاسخ موفق:

{
  "payload": true,
  "meta": {
    "timestamp": 1750669200
  }
}

نمونه پاسخ خطا برای سرویس نامعتبر:

{
  "error": {
    "code": 404,
    "message": "امکان بروزرسانی این آیتم از طریق سرویس انتخاب شده امکان‌پذیر نیست."
  },
  "meta": {
    "timestamp": 1750669200
  }
}

نکات امنیتی

  • نیاز به احراز هویت JWT معتبر دارد.
  • در صورت اجرا در سطح سرویس خارجی، باید ورودی service از لیست سفید داخلی تأیید شود.
  • اجراهای هم‌زمان با Redis ممکن است نیاز به قفل توزیع‌شده داشته باشند (Distributed Locking).

نکات عملکردی

  • در هر فراخوانی، دو عملیات حذف عمده روی DB و یک پاک‌سازی Redis انجام می‌شود.
  • برای پیشگیری از فشار روی سرور، پیشنهاد می‌شود عملیات در صف (Queue) قرار گیرد.
  • بهینه‌سازی قابل‌توجه با اجرای CronController::updateSnapptripMappedAccommodation() در Job async قابل انجام است.
  • TTL کش پیشنهادی بعد از بروزرسانی: ۶ ساعت.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use App\Http\Controllers\CronController;
  • use Carbon\Carbon;
  • use Exception;

کدهای خطا

کد شرح خطا منبع
404 سرویس واردشده پشتیبانی نمی‌شود. accommodationRoomsUpdate()
500 خرابی در فراخوانی CronController یا ارتباط Redis/DB. CronController / DB Facade

پیشنهادهای امنیتی

  • اضافه‌کردن Role محدودکننده برای بروزرسانی داده‌های اقامتگاه (مثلاً "DataSupervisor").
  • ثبت دقیق operator_id و branch در لاگ.
  • اضافه‌کردن لایه تأیید دو مرحله‌ای برای عملیات حذف/بازسازی گروهی.

پیشنهادهای بهبود

  • حمایت از سرویس‌های دیگر مانند Booking یا Expedia برای آینده.
  • جایگزینی پاک‌سازی Redis با Pipeline commands جهت افزایش سرعت.
  • نمایش وضعیت جزئی از تعداد اتاق‌های حذف‌شده و افزوده‌شده در پاسخ.
  • توسعه لاگ تفکیکی برای هر اقامتگاه با timestamp و branch.

ممیزی و لاگ‌ها

  • نوع ثبت لاگ پیشنهادی: UpdateRoomMapping.
  • فیلدهای اجباری در لاگ: service، accommodation_id، operator_id، status.
  • سطح لاگ توصیه‌شده: Info / Warning بسته به نتیجه CronController.

جمع‌بندی

مسیر /base/accommodation/rooms/update عملیات حیاتی بروزرسانی نگاشت اتاق‌ها با سرویس‌های خارجی مانند SnappTrip را انجام می‌دهد. در فعلی‌ترین پیاده‌سازی فقط برای SnappTrip فعال است؛ حذف و بازسازی همه‌ی داده‌های مربوطه همراه با پاک‌سازی Redis انجام می‌شود. در نسخه بعدی این سیستم باید مفهوم Transactional Safety و Service Expandability اضافه گردد تا برای سایر سرویس‌ها نیز قابل توسعه باشد.
Back to top