# POST /v2/core/airports/list

# Core Airports List

این اندپوینت برای دریافت لیست فرودگاه‌ها با فیلترهای پیشرفته، Pagination مشابه DataTables، و غنی‌سازی داده‌ها (Country از Redis/DB و City از DB) استفاده می‌شود. خروجی کاملاً استاندارد و سازگار با سیستم‌های مدیریت داده (DataTables‑Compatible Response) است.

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

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

<div class="api-docs" id="bkmrk-jwt-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-middleware">- JWT معتبر
- middleware core فقط وقتی اجازه می‌دهد که: <div class="code-inline">operator.branch == "[0]"</div>

</div>## Request Body Schema

<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>json</td><td>string (JSON)</td><td>yes</td><td>حاوی پارامترهای DataTables (start, length, draw, advanced filters)</td></tr><tr><td>lang.id</td><td>string|integer</td><td>optional</td><td>شناسه زبان (در این متد استفاده عملی ندارد)</td></tr></tbody></table>

</div>### Structure Inside json

<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>start</td><td>integer</td><td>Offset اولیه</td></tr><tr><td>length</td><td>integer</td><td>اندازه هر صفحه</td></tr><tr><td>draw</td><td>integer</td><td>شاخص درخواست DataTables</td></tr><tr><td>advanced.country</td><td>string</td><td>فیلتر کشور</td></tr><tr><td>advanced.state</td><td>string</td><td>فیلتر استان</td></tr><tr><td>advanced.city</td><td>string</td><td>فیلتر شهر</td></tr><tr><td>advanced.iata</td><td>string</td><td>فیلتر IATA</td></tr><tr><td>advanced.type</td><td>string</td><td>فیلتر نوع فرودگاه</td></tr><tr><td>advanced.r</td><td>string</td><td>جستجوی آزاد روی title, title\_fa, description, address</td></tr></tbody></table>

</div>## Pagination Logic

<div class="api-docs" id="bkmrk-%D8%A7%DA%AF%D8%B1-start-%3D-0-%E2%86%92-star">- اگر start = 0 → start = length
- در غیر این صورت → start = start + length
- page = (start / length)
- کوئری paginate با pageName = "airports"

</div>## Filtering Logic

تمام فیلترها داخل Closure:

<div class="api-docs" id="bkmrk-country-%E2%86%92-where%28%27cou">- country → where('country')
- state → where('state')
- city → where('city')
- iata → where('iata')
- type → where('type')
- r → applied on: 
    - title LIKE %r%
    - title\_fa LIKE %r%
    - description LIKE %r%
    - address LIKE %r%
- status = 1
- ORDER BY id DESC

</div>## Country &amp; City Enrichment

### Country (Redis → DB Fallback)

<div class="api-docs" id="bkmrk-redis-key%3A-countries">- Redis key: `countries:{country_id}`
- اگر موجود نبود: 
    - اطلاعات از DB خوانده می‌شود (جدول countries)
    - در Redis ذخیره می‌شود
- در خروجی: فقط fa\_name (در صورت نبود → id اصلی)

</div>### City Resolution

Lookup مستقیم DB:

<div class="api-docs" id="bkmrk-%D8%AC%D8%AF%D9%88%D9%84-cities-%D8%A8%D8%A7-join-">- جدول cities با join روی states
- خروجی شامل: 
    - city.title\_fa → نمایش نام فارسی شهر
    - state.fa\_name → نمایش استان
- اگر City یافت نشد → فیلدهای state و city از DB اصلی airport (city/state ID) استفاده می‌شود.

</div>## Final Output Mapping

```
{
  "id": airport.id,
  "title": airport.title,
  "title_fa": airport.title_fa,
  "iata": airport.iata,
  "country": resolved_country,
  "state": resolved_state_name,
  "city": resolved_city_name,
  "location": airport.location,
  "description": airport.description,
  "logo": airport.logo,
  "image": airport.image,
  "status": airport.status
}
  
```

<div class="api-docs" id="bkmrk--1"></div>## Response (Success)

```
{
  "status": true,
  "time": 1710000000,
  "draw": ,
  "recordsTotal": ,
  "recordsFiltered": ,
  "data": [...]
}
  
```

<div class="api-docs" id="bkmrk--2"></div>## Response (Error)

```
{
  "status": false,
  "code": "1003",
  "message": "(Exception message)",
  "trace": [...]
}
  
```

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

<div class="api-docs" id="bkmrk-validate-jwt-%26-core-"><div class="flowchart"><div class="flow-item">Validate JWT &amp; Core Access</div><div class="flow-arrow">↓</div><div class="flow-item">Parse json → Data object</div><div class="flow-arrow">↓</div><div class="flow-item">Compute Pagination (start / length)</div><div class="flow-arrow">↓</div><div class="flow-item">Apply Filters (country/state/city/iata/type/r)</div><div class="flow-arrow">↓</div><div class="flow-item">Query airports with paginate</div><div class="flow-arrow">↓</div><div class="flow-item">Resolve Country (Redis → DB)</div><div class="flow-arrow">↓</div><div class="flow-item">Resolve City + State from tables</div><div class="flow-arrow">↓</div><div class="flow-item">Assemble Response Array</div><div class="flow-arrow">↓</div><div class="flow-item">Return DataTables-Compatible JSON</div></div></div>