# GET /v2/travel_requests

# Travel Requests List

این اندپوینت لیست درخواست‌های سفر (مانند پرواز، هتل، قطار و ...) را با قابلیت‌های پیشرفته فیلترینگ و **غنی‌سازی (Data Enrichment)** بازمی‌گرداند.   
نکته متمایز این کنترلر، منطق **Scoping** (تعیین سطح دسترسی بر اساس گروه کاربری) و همچنین اتصال به چندین جدول (Operators, Customers, Colleagues, Cities, Factors) و دیتابیس **Redis** برای ساخت یک آبجکت پاسخ کامل است.

<div class="api-docs" id="bkmrk-">  ---

</div>## List Requests (Index)

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Ftravel_requ"><div class="endpoint-info"><div>**URL:** `/v2/travel_requests`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** TravelRequestsController@index</div></div></div>### Query Parameters

<div class="api-docs" id="bkmrk-parameter-type-descr"><table class="schema-table" dir="rtl"><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>branch</td><td>integer</td><td>**(الزامی)** شناسه شعبه.</td></tr><tr><td>group</td><td>string</td><td>تعیین کننده سطح دسترسی (`requester\_id`): - `base` / `b2e`: دسترسی ادمین به درخواست‌های یک کاربر خاص (نیاز به ارسال `requester\_id`).
- `colleague` / `b2b`: لیست درخواست‌های خود اپراتور B2B.
- `agent` / `b2c`: لیست درخواست‌های خود اپراتور B2C.

</td></tr><tr><td>requester\_id</td><td>integer</td><td>در صورتی که `group` برابر با `base` باشد، برای فیلتر کردن درخواست‌های یک کاربر خاص استفاده می‌شود.</td></tr><tr><td>operator\_id</td><td>integer</td><td>فیلتر بر اساس اپراتور هندل‌کننده درخواست.</td></tr><tr><td>method</td><td>string</td><td>فیلتر نوع اصلی خدمت (مثلاً `flight`, `hotel`).</td></tr><tr><td>submethod</td><td>string</td><td>فیلتر زیرمجموعه خدمت.</td></tr><tr><td>status</td><td>string</td><td>فیلتر وضعیت درخواست.</td></tr><tr><td>payment\_status</td><td>string</td><td>فیلتر وضعیت پرداخت.</td></tr><tr><td>paginate\[length\]</td><td>integer</td><td>تعداد آیتم در صفحه (پیش‌فرض: ۳۰).</td></tr><tr><td>paginate\[start\]</td><td>integer</td><td>آفست شروع (پیش‌فرض: ۰). شماره صفحه به صورت دینامیک محاسبه می‌شود.</td></tr></tbody></table>

</div>### Logic Details

<div class="api-docs" id="bkmrk-%D9%85%D9%86%D8%B7%D9%82-%D8%B5%D9%81%D8%AD%D9%87%E2%80%8C%D8%A8%D9%86%D8%AF%DB%8C-%28pagi">1. **منطق صفحه‌بندی (Pagination Calculation):**   
    سیستم از متد استاندارد `page` لاراول استفاده نمی‌کند، بلکه شماره صفحه را بر اساس `start` و `length` محاسبه می‌کند:   
    `Current Page = (start + length) / length`   
    اگر `start=0` باشد، صفحه ۱ در نظر گرفته می‌شود.
2. **منطق Scoping (تعیین Requester):**
    - اگر `group` برابر **base/b2e** باشد: کوئری روی `requester\_id` ورودی فیلتر می‌شود.
    - اگر **colleague/b2b** یا **agent/b2c** باشد: کوئری روی `operator-&gt;id` (کاربر لاگین شده) قفل می‌شود.
    - در غیر این صورت: همه درخواست‌ها نمایش داده می‌شوند.
3. **غنی‌سازی داده‌ها (Data Enrichment Loop):** پس از دریافت داده‌های خام از جدول `travel\_requests`، روی هر آیتم عملیات زیر انجام می‌شود: 
    - **Polymorphic Requester:** بسته به `operator\_group`، اطلاعات درخواست‌دهنده از جدول `customers` (برای B2C) یا `colleagues` (برای B2B از طریق جدول واسط `colleague\_auth`) واکشی می‌شود.
    - **Cities:** نام فارسی و انگلیسی `origin` و `destination` از جدول `cities` جوین می‌شود.
    - **Operator:** جزئیات اپراتور هندل‌کننده (شامل آواتار) اضافه می‌شود.
    - **Reference (Factor):**
        - سریال فاکتور از جدول `factors` خوانده شده و با **10000** جمع می‌شود.
        - عنوان فاکتور از **Redis** با کلید `reference:{id}:information:title:fa` استعلام می‌شود.
    - **Accommodation:** اگر هتل باشد، اطلاعات آن از طریق متد استاتیک `StaticController::getAccommodation` دریافت می‌شود.
    - **Dynamic Title Construction:** یک عنوان توصیفی شامل "مبدا + مقصد + هتل + تاریخ‌ها" ساخته می‌شود. (تاریخ‌ها برای نمایش صحیح در متون فارسی با کاراکتر کنترل یونیکد `\u{200E}` محصور می‌شوند).
    - **Details:** فیلد `details` که JSON است، دیکد می‌شود.

</div>### Flowchart (Request Processing)

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-calc"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Calc Pagination**  
Page = (Start + Length) / Length</div><div class="flow-arrow">↓</div><div class="flow-item-decision">Check 'group' param</div><div style="display: flex; justify-content: space-between; margin-top: 10px;"><div style="width: 30%; text-align: center;"><div class="flow-arrow-label-left">base/b2e</div><div class="flow-item-process" style="font-size: 0.7em;">Filter by Input  
Requester_ID</div></div><div style="width: 30%; text-align: center;"><div class="flow-arrow-label-left">b2b/b2c</div><div class="flow-item-process" style="font-size: 0.7em;">Filter by Auth  
Operator ID</div></div><div style="width: 30%; text-align: center;"><div class="flow-arrow-label-right">Others</div><div class="flow-item-process" style="font-size: 0.7em;">No Filter  
(Admin View)</div></div></div><div class="flow-arrow">↓</div><div class="flow-item-process">**DB Query &amp; Filters**  
Apply branch, method, status...</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fff3e0;">**Data Mapping (Loop)**  
Fetch Cities, Operator, Factor (Redis), Hotel info</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #f3e5f5;">**Generate Title**  
Origin + Dest + Hotel + Dates</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return JSON (Items + Meta)</div></div></div>### Response Structure

```json
{
  "items": [
    {
      "id": 123,
      "branch": 1,
      "requester_id": { "id": 50, "first_name": "...", "last_name": "..." }, // Object (Customer or Colleague)
      "origin": { "id": 1, "fa_name": "تهران", "en_name": "Tehran" },
      "destination": { "id": 2, "fa_name": "مشهد", "en_name": "Mashhad" },
      "reference": {
         "id": 99,
         "serial": 10055, // Original + 10000
         "title": "تور مشهد" // From Redis
      },
      "accommodation": {
         "title": { "fa": "هتل درویشی" },
         "category": { "title": "hotel", "subtitle": false }
      },
      "title": "تهران به مشهد هتل درویشی از 1403/01/01 تا 1403/01/04", // Generated String
      "details": { ... } // Decoded JSON
      // ... other fields
    }
  ],
  "meta": {
    "timestamp": 1715000000,
    "table": {
      "total": 100,
      "per_page": 30,
      "current_page": 1,
      "last_page": 4,
      "from": 1,
      "to": 30,
      "next_page": 2
    }
  }
}
```