Skip to main content
#P1480

GET /base/accommodations/list

Route Info

Method Endpoint Controller Middleware Purpose
GET /api/v2/base/accommodations/list V2BaseController@accommodationsList authWithJwt دریافت لیست اقامتگاه‌ها (هتل‌ها) براساس فیلترهای جغرافیایی و ویژگی‌های پیشرفته، همراه با جزئیات تأمین‌کننده و رسانه.

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

تابع accommodationsList از پارامتر JSON در بدنه درخواست استفاده می‌کند تا جزئیات فیلتر و صفحه‌بندی را تعیین کند. سپس فیلترهایی بر اساس کشور، استان، شهر، امتیاز و جستجوی عمومی (با کلید r) اعمال کرده و نتیجه را از جدول hotels استخراج می‌کند.
منطق کلی تابع:
  • خواندن پارامتر JSON از بدنه درخواست: $Data = json_decode($request->get('json'));
  • مدیریت صفحه‌بندی با فیلدهای start و length.
  • اعمال فیلترهای چندلایه (کشور، استان، شهر، درجه و عبارت جستجو).
  • دریافت اقامتگاه‌های فعال where('status', 1) و مرتب‌سازی نزولی براساس شناسه.
  • برای هر اقامتگاه، داده‌های کشور، شهر و تأمین‌کننده از Redis یا DB واکشی می‌شوند.
  • ساخت پاسخ شامل جزئیات لوکیشن، آدرس، درجه، وضعیت، و مسیر رسانه.

پارامترهای ورودی

نام پارامتر نوع داده منبع الزامی توضیح
json string (JSON) Body بله شامل فیلدهای صفحه‌بندی و فیلترها.
advanced.country integer json → advanced اختیاری شناسه کشور فیلترشده.
advanced.state integer json → advanced اختیاری شناسه استان فیلترشده.
advanced.city integer json → advanced اختیاری شناسه شهر فیلترشده.
advanced.rate integer json → advanced اختیاری امتیاز کیفیت اقامتگاه.
advanced.r string json → advanced اختیاری عبارت جستجوی عمومی (نام یا آدرس هتل).
length integer json بله تعداد سطر در هر صفحه.
start integer json بله شماره شروع صفحه.
draw integer json اختیاری شناسه داخلی برای درخواست‌های Datatable.

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

GET /api/v2/base/accommodations/list
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "json": {
    "length": 10,
    "start": 0,
    "draw": 1,
    "advanced": {
      "country": 118,
      "state": 31,
      "city": 548,
      "rate": 5,
      "r": "مشهد"
    }
  }
}

خروجی (Response)

فیلد نوع داده توضیح
items[].id integer شناسه داخلی اقامتگاه.
items[].title_fa / title string نام فارسی و انگلیسی اقامتگاه.
items[].rate integer امتیاز عددی هتل.
items[].country object داده‌های کشور مقصد، شامل نام فارسی و کد ISO.
items[].state string نام استان مرتبط.
items[].city string نام شهر مرتبط.
items[].address string آدرس هتل.
items[].logo string مسیر رسانه لوگوی اقامتگاه.
items[].supplier object اطلاعات تأمین‌کننده (colleague mapping).
meta.recordsTotal integer تعداد کل رکوردها.
meta.recordsFiltered integer تعداد فیلترشده.
meta.timestamp integer (unix) زمان تولید پاسخ.

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

{
  "items": [
    {
      "id": 102,
      "title_fa": "هتل پارس مشهد",
      "rate": 5,
      "country": { "id": 118, "fa_name": "ایران", "iso": "IR" },
      "state": "خراسان رضوی",
      "city": "مشهد",
      "address": "خیابان امام رضا",
      "logo": "https://storage.service01.ir/media/hotels/pars.jpg",
      "supplier": { "system_serial": 11, "serial": "CLG992" }
    }
  ],
  "meta": { "timestamp": 1750669000, "recordsTotal": 150, "recordsFiltered": 10 }
}

نکات امنیتی

  • دسترسی فقط با JWT معتبر امکان‌پذیر است.
  • فیلترهای فیلد قابل تزریق SQL نیستند، چون از where() و paginate() ایمن استفاده شده.
  • در حال حاضر کنترل سطح دسترسی برای شعب مختلف تعریف نشده، پیشنهاد اضافه گردد.

نکات عملکردی

  • Redis برای کش‌کردن نام کشورها استفاده می‌شود (کلید countries:{id}).
  • بهتر است کش شهرها نیز افزوده شود تا فشار به DB کاهش یابد.
  • در هر فراخوانی، بیش از ۳ جدول مرتبط (hotels، cities، states، colleagues) درگیر هستند.
  • پیشنهاد TTL کش = 4 ساعت.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use App\Models\Media;
  • use Carbon\Carbon;

کدهای خطا

کد شرح خطا منبع
400 فرمت نادرست JSON یا فیلدهای ناقص. Decoder JSON
404 هیچ اقامتگاهی برای فیلترهای واردشده یافت نشد. Query hotels
500 خطا در اتصال Redis یا پایگاه داده. DB Facade / Redis

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

  • فیلتر دسترسی مبتنی بر نقش (RBAC) برای شعب مختلف.
  • اضافه کردن rate-limit برای درخواست لیست متوالی.
  • پنهان‌سازی مسیر انبار رسانه هنگام پاسخ.

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

  • افزودن ویژگی مرتب‌سازی پویا براساس امتیاز یا کشور.
  • نمایش داده‌های تأمین‌کننده با نماد و نام تجاری.
  • افزودن قابلیت فیلتر براساس وضعیت فعال/غیرفعال.
  • پشتیبانی از lazy-loading برای مدیا (logo).

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

  • هر درخواست در جدول system_log با نوع ReadAccommodationList ثبت شود.
  • مقادیر چون branch_id، filters و operator_id باید در لاگ ذخیره شوند.
  • سطح لاگ توصیه‌شده: Info.

جمع‌بندی

مسیر /base/accommodations/list یکی از اصلی‌ترین نقاط برای واکشی اقامتگاه‌های سیستم است. با تکیه بر Redis، سیستم بهینه‌تر عمل می‌کند ولی برای نسخه Enterprise نیاز به توسعه کش شهر/استان و امنیت سطح دسترسی دارد. پاسخ استاندارد JSON‌ شامل متادیتا زمان و شمارنده‌های صفحه‌بندی، ساختار کاملاً تمیز و قابل‌درک برای فرانت‌اند فراهم می‌کند.
Back to top