# POST /v2/core/accommodations/list

# Core Accommodations List

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

<div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcore%2Faccomm"><div class="endpoint-info"><div>**URL:** `/v2/core/accommodations/list`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** CoreController@accommodationsList</div><div>**Middleware Stack:** authWithJwt → core</div></div></div>## Authentication &amp; Access Control

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

<div class="api-docs" id="bkmrk-authwithjwt%3A-%D8%A8%D8%B1%D8%B1%D8%B3%DB%8C-j">- **authWithJwt**: بررسی JWT، بازیابی اپراتور از DB، بررسی status=1
- **core**: اجازه فقط اگر `$request->operator->branch == "[0]"`

</div>در صورت عدم دسترسی:

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

<div class="api-docs" id="bkmrk--1"></div>## Request Body

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

<div class="api-docs" id="bkmrk-field-type-required-"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>`draw`</td><td>integer</td><td>yes</td><td>شماره سریال درخواست (برای DataTables)</td></tr><tr><td>`start`</td><td>integer</td><td>yes</td><td>نقطه شروع صفحه‌بندی. اگر 0 باشد: مقدار برابر length قرار داده می‌شود اگر &gt;0 باشد: مقدار += length</td></tr><tr><td>`length`</td><td>integer</td><td>yes</td><td>تعداد رکورد در هر صفحه</td></tr><tr><td>`advanced.country`</td><td>string</td><td>no</td><td>فیلتر کشور</td></tr><tr><td>`advanced.state`</td><td>string</td><td>no</td><td>فیلتر استان</td></tr><tr><td>`advanced.city`</td><td>string</td><td>no</td><td>فیلتر شهر</td></tr><tr><td>`advanced.rate`</td><td>string</td><td>no</td><td>فیلتر تعداد ستاره</td></tr><tr><td>`advanced.r`</td><td>string</td><td>no</td><td>جستجوی آزاد روی id، عنوان فارسی، عنوان انگلیسی، آدرس</td></tr></tbody></table>

</div>## Database Query Logic

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

<div class="api-docs" id="bkmrk-%D9%81%DB%8C%D9%84%D8%AA%D8%B1-%DA%A9%D8%B4%D9%88%D8%B1%D8%8C-%D8%A7%D8%B3%D8%AA%D8%A7%D9%86%D8%8C-%D8%B4">- فیلتر کشور، استان، شهر، rate در صورت مقدار داشتن
- فیلتر full-text (جزیی) روی: 
    - id
    - en\_title
    - fa\_title
    - address
- where status = 1
- OrderBy id DESC
- **paginate** با page = `$Data->start / $Data->length`

</div>```
paginate(
    $perPage = length,
    columns = "*",
    pageName = "hotels",
    currentPage = (start / length)
)
  
```

<div class="api-docs" id="bkmrk--2"></div>## Enrichment Pipeline (per-item)

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

<div class="api-docs" id="bkmrk-step-description-1.-"><table class="schema-table"><thead><tr><th>Step</th><th>Description</th></tr></thead><tbody><tr><td>1. Load Country (Redis → DB fallback)</td><td>تلاش برای خواندن `countries:{id}` از Redis در صورت نبود: خواندن از DB و ذخیره در Redis</td></tr><tr><td>2. Load City Info</td><td>join cities + states خروجی شامل title\_fa و group\_by (عنوان استان)</td></tr><tr><td>3. Supplier Mapping</td><td>خواندن mapping از جدول mapping\_colleagues سپس دریافت colleague از جدول colleagues</td></tr><tr><td>4. Media (Logo)</td><td>`Media::where('related_id', $request->get('id'))` \*\*نکته:\*\* این مقدار از request-&gt;id دریافت می‌شود، نه id اقامتگاه — رفتار دقیقاً مطابق کد ثبت شد.</td></tr></tbody></table>

</div>## Response Schema

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>`status`</td><td>boolean</td><td>true</td></tr><tr><td>`time`</td><td>integer</td><td>UNIX timestamp</td></tr><tr><td>`draw`</td><td>integer</td><td>echo همان draw ورودی</td></tr><tr><td>`recordsTotal`</td><td>integer</td><td>result-&gt;total() از paginate</td></tr><tr><td>`recordsFiltered`</td><td>integer</td><td>مقدار ورودی length (طبق کد، نه تعداد واقعی فیلتر شده)</td></tr><tr><td>`data`</td><td>array</td><td>لیست اقامتگاه‌ها با اطلاعات کامل enrich شده</td></tr></tbody></table>

</div>## 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"
      }
    }
  ]
}
  
```

<div class="api-docs" id="bkmrk--3"></div>## Process Flow

<div class="api-docs" id="bkmrk-authwithjwt-%E2%86%92-valida"><div class="flowchart"><div class="flow-item">AuthWithJWT → Validate Token</div><div class="flow-arrow">↓</div><div class="flow-item">CoreAccess → Check branch == "[0]"</div><div class="flow-arrow">↓</div><div class="flow-item">Decode Body.json</div><div class="flow-arrow">↓</div><div class="flow-item">Compute Pagination (start/length)</div><div class="flow-arrow">↓</div><div class="flow-item">Query hotels with Advanced Filters</div><div class="flow-arrow">↓</div><div class="flow-item">For Each Hotel → Enrichment Pipeline (Redis Country, City join, Mapping, Media)</div><div class="flow-arrow">↓</div><div class="flow-item">Return Final JSON Payload</div></div></div>