Skip to main content
#P1651

POST /v2/core/accommodations/list

Core Accommodations List

این اندپوینت لیست اقامتگاه‌ها (هتل‌ها) را با پشتیبانی از فیلترهای پیشرفته، صفحه‌بندی پویا، بارگذاری داده‌های تکمیلی از Redis، اطلاعات جغرافیایی از دیتابیس، و استخراج Supplier Mapping برگشت می‌دهد. این سرویس صرفاً در اختیار کاربرانی قرار می‌گیرد که دسترسی Core داشته باشند (operator.branch == "[0]").

Request Overview

URL: /v2/core/accommodations/list
Method: POST
Controller: CoreController@accommodationsList
Middleware Stack: authWithJwt → core

Authentication & Access Control

مانند سایر سرویس‌های هسته Core:

  • authWithJwt: بررسی JWT، بازیابی اپراتور از DB، بررسی status=1
  • core: اجازه فقط اگر $request->operator->branch == "[0]"

در صورت عدم دسترسی:

{
  "status": false,
  "time": 1710000000,
  "error": {
    "code": 5005,
    "message": "Access to the [core center] requires special access."
  },
  "support": { ... }
}

Request Body

ورودی با کلید json در Body ارسال می‌شود و توسط کد json_decode تبدیل می‌شود.

Field Type Required Description
draw integer yes شماره سریال درخواست (برای DataTables)
start integer yes نقطه شروع صفحه‌بندی. اگر 0 باشد: مقدار برابر length قرار داده می‌شود اگر >0 باشد: مقدار += length
length integer yes تعداد رکورد در هر صفحه
advanced.country string no فیلتر کشور
advanced.state string no فیلتر استان
advanced.city string no فیلتر شهر
advanced.rate string no فیلتر تعداد ستاره
advanced.r string no جستجوی آزاد روی id، عنوان فارسی، عنوان انگلیسی، آدرس

Database Query Logic

کوئری اصلی روی جدول hotels اعمال می‌شود:

  • فیلتر کشور، استان، شهر، rate در صورت مقدار داشتن
  • فیلتر full-text (جزیی) روی:
    • id
    • en_title
    • fa_title
    • address
  • where status = 1
  • OrderBy id DESC
  • paginate با page = $Data->start / $Data->length
paginate(
    $perPage = length,
    columns = "*",
    pageName = "hotels",
    currentPage = (start / length)
)

Enrichment Pipeline (per-item)

برای هر accommodation مراحل زیر اجرا می‌شود:

Step Description
1. Load Country (Redis → DB fallback) تلاش برای خواندن countries:{id} از Redis در صورت نبود: خواندن از DB و ذخیره در Redis
2. Load City Info join cities + states خروجی شامل title_fa و group_by (عنوان استان)
3. Supplier Mapping خواندن mapping از جدول mapping_colleagues سپس دریافت colleague از جدول colleagues
4. Media (Logo) Media::where('related_id', $request->get('id')) **نکته:** این مقدار از request->id دریافت می‌شود، نه id اقامتگاه — رفتار دقیقاً مطابق کد ثبت شد.

Response Schema

Field Type Description
status boolean true
time integer UNIX timestamp
draw integer echo همان draw ورودی
recordsTotal integer result->total() از paginate
recordsFiltered integer مقدار ورودی length (طبق کد، نه تعداد واقعی فیلتر شده)
data array لیست اقامتگاه‌ها با اطلاعات کامل enrich شده

Sample Successful Response

{
  "status": true,
  "time": 1710000000,
  "draw": 3,
  "recordsTotal": 1295,
  "recordsFiltered": 20,
  "data": [
    {
      "id": 554,
      "title": "Tehran Grand Hotel",
      "title_fa": "هتل بزرگ تهران",
      "rate": 5,
      "country": {
        "id": 102,
        "fa_name": "ایران",
        "en_name": "Iran",
        "fa_nationality": "ایرانی",
        "en_nationality": "Iranian"
      },
      "state": "تهران",
      "city": "تهران",
      "location": "35.7000,51.4000",
      "address": "خیابان ولیعصر ...",
      "logo": "/media/accommodations/554/logo.png",
      "status": 1,
      "supplier": {
        "system_serial": 88,
        "serial": "C-4401"
      }
    }
  ]
}

Process Flow

AuthWithJWT → Validate Token
↓
CoreAccess → Check branch == "[0]"
↓
Decode Body.json
↓
Compute Pagination (start/length)
↓
Query hotels with Advanced Filters
↓
For Each Hotel → Enrichment Pipeline (Redis Country, City join, Mapping, Media)
↓
Return Final JSON Payload
Back to top