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