Skip to main content
#P1742

GET /v2/core/hub/reservation

Hub: Get Master Reservation List

این اندپوینت یک لیست جامع و صفحه‌بندی شده از تمام رزروهای ثبت شده در سیستم مرکزی (Hub) را برمی‌گرداند. برای هر رزرو، اطلاعات از جداول مختلفی مانند offices، factor_items، colleagues، و wallet استخراج و با داده‌های اصلی ادغام می‌شود تا یک خروجی کامل و غنی‌شده ارائه دهد.

Request Overview

URL: /v2/core/hub/reservation
Method: GET
Controller: HubController@hubReservation
Middleware: authWithJwt

Access Control

  • نیاز به توکن احراز هویت (JWT) دارد.

Query Parameters (Custom Pagination)

این اندپوینت از یک ساختار صفحه‌بندی سفارشی استفاده می‌کند که معمولاً توسط کتابخانه‌های جدولی مانند (jQuery DataTables) ارسال می‌شود. پارامترها باید در یک آبجکت به نام paginate ارسال شوند.

Field Type Description
paginate[length] integer (الزامی) تعداد آیتم‌های مورد نظر در هر صفحه.
paginate[start] integer (الزامی) آفست (offset) شروع رکوردها. برای صفحه اول 0، برای صفحه دوم (با length=10)، 10 و به همین ترتیب.

Example URL: /v2/core/hub/reservation?paginate[length]=15&paginate[start]=0

Logic Details

فرآیند دریافت و پردازش رزروها بسیار گسترده است و شامل مراحل زیر می‌شود:

  1. کوئری اولیه و صفحه‌بندی:
    • یک کوئری اصلی به جدول hub_reservation زده می‌شود.
    • این کوئری با جدول offices بر اساس hub_reservation.branch جوین می‌شود تا نام فارسی شعبه (brand_fa) استخراج شود.
    • نتایج بر اساس id به صورت نزولی مرتب می‌شوند.
    • با استفاده از پارامترهای length و start، صفحه‌بندی سفارشی روی نتایج اعمال می‌شود.
  2. حلقه غنی‌سازی داده‌ها (Data Enrichment Loop):
    • سیستم روی هر یک از رزروهای برگشتی از کوئری اصلی، یک حلقه اجرا کرده و برای هرکدام، مجموعه‌ای از عملیات و کوئری‌های اضافی را انجام می‌دهد:
    • نکته عملکردی (Performance Consideration): این رویکرد (کوئری در حلقه) به مشکل N+1 Query منجر می‌شود و ممکن است با افزایش تعداد آیتم‌ها در هر صفحه، عملکرد را تحت تأثیر قرار دهد.
  3. مراحل داخل حلقه برای هر رزرو:
    1. واکشی آیتم فاکتور: از جدول factor_items، آیتم مربوط به رزرو (item_id) واکشی می‌شود. اگر آیتم یافت نشود، کل آن رزرو از خروجی نهایی حذف می‌شود.
    2. واکشی نام سرویس‌ها: شناسه‌های عددی service و sub_service با اجرای کوئری روی جدول colleagues به نام متنی (فیلد office) تبدیل می‌شوند.
    3. تولید عنوان آیتم (title_item): با فراخوانی متد پیچیده TradeController::getReferenceItemTitle، یک عنوان توصیفی و قابل فهم برای آیتم (مانند "هواپیما تهران به مشهد | ۱۴۰۴/۰۹/۱۸ ۱۲:۳۰") تولید می‌شود. این متد به شدت از کش Redis برای بهینه‌سازی عملکرد استفاده می‌کند.
    4. واکشی اطلاعات اپراتور: با فراخوانی متد StaticController::getOperators، شناسه اپراتور به یک آبجکت کامل شامل نام، نام خانوادگی و سایر مشخصات تبدیل می‌شود. در صورت عدم وجود اپراتور، مقدار false بازگردانده می‌شود.
    5. پردازش فیلدهای JSON: رشته‌های JSON موجود در فیلدهای supplier_details و details به آبجکت/آرایه تبدیل می‌شوند.
    6. ضمیمه کردن داده‌های جدید: اطلاعات پردازش شده (نام سرویس، عنوان، اطلاعات اپراتور و...) به آبجکت اصلی رزرو اضافه می‌شوند.
    7. بررسی استرداد (Refund): سیستم در جدول wallet جستجو می‌کند تا ببیند آیا تراکنش استردادی (target_type='refund') برای این رزرو ثبت شده است یا خیر. در صورت وجود، جزئیات آن به فیلد refund اضافه می‌شود؛ در غیر این صورت، این فیلد مقدار false می‌گیرد.

Response Structure

پاسخ موفق

  • Status Code: 200 OK
  • فیلد items حاوی آرایه‌ای از آبجکت‌های رزرو غنی‌شده است.
  • فیلد meta.table حاوی جزئیات کامل صفحه‌بندی است.
{
    "items": [
        {
            "id": 12345,
            "branch": "آژانس تابان", // از جدول offices
            "item_id": 54321,
            "operator": { // از متد getOperators
                "id": 101,
                "text": "1100 - علی اکبری",
                "query": { /* ... details ... */ }
            },
            "service": "Ghasreshirin", // نام تبدیل شده
            "sub_service": "Parsian System", // نام تبدیل شده
            "supplier_details": { /* آبجکت JSON */ },
            "details": { /* آبجکت JSON */ },
            "status": "issued",
            "created_at": "2025-12-09T12:00:00.000000Z",
            
            // --- Fields added in the loop ---
            "title_item": "هواپیما تهران به مشهد | ۱۴۰۴/۰۹/۱۸ ۱۲:۳۰ | W5065 | ماهان", // از getReferenceItemTitle
            "item": { // آبجکت کامل از factor_items
                "id": 54321,
                "product": "online",
                "byproduct": "aircraft",
                "details": { /* ... */ },
                "buy": 5400000,
                "sell": 5500000
                /* ... */
            },
            "refund": { // یا false اگر وجود نداشته باشد
                "id": 789,
                "credit": 5000000,
                "description": "استرداد بابت کنسلی پرواز"
            }
        }
    ],
    "meta": {
        "timestamp": 1733737200,
        "table": {
            "total": 500,
            "per_page": 15,
            "current_page": 1,
            "last_page": 34,
            "from": 1,
            "to": 15
        }
    }
}

Flowchart

Start Request (GET /v2/core/hub/reservation)
↓
Execute Paginated Query on `hub_reservation` with JOIN on `offices`.
(Using custom `start`/`length` params)
↓
For each reservation in results:
Query `factor_items` using `item_id`
↓
Item Found?
No
Skip to next reservation
↓ (Yes)
Query `colleagues` for Service & Sub-Service names
↓
Call `getReferenceItemTitle` (Cached Title Generation)
↓
Call `getOperators` to format operator data
↓
Query `wallet` to find refund details
↓
Assemble all new data into the final reservation object
↓
Return 200 OK with `items` array & `meta.table`
Back to top