# POST /api/v2/customers/list

<div id="bkmrk-" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"><table border="1" style="width: 96%; margin: auto; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td style="direction: ltr;">POST</td><td style="direction: ltr;">/api/v2/customers/list</td><td style="direction: ltr;">UserController@passengersList</td><td style="direction: ltr;">authWithJwt</td><td style="direction: rtl; text-align: right;">دریافت فهرست مشتریان (مسافران) با قابلیت جستجا و صفحه‌بندی</td></tr></tbody></table>

</div>### منطق عملکرد

<div id="bkmrk-%D8%AF%D8%A7%D8%AF%D9%87-%D9%88%D8%B1%D9%88%D8%AF%DB%8C-%D8%AF%D8%B1-%D9%81%DB%8C%D9%84%D8%AF-j" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- داده ورودی در فیلد `json` به‌صورت string JSON ارسال می‌شود و Parse می‌گردد.
- محاسبه اندیس شروع لیست (`start`) و ارزش شمارش (`length`) برای صفحه‌بندی.
- فیلتر اصلی بر اساس مقدار `Data->search->value` تنظیم می‌شود: 
    - اگر مقدار عددی باشد: جستجو بر اساس id، national\_code، mobile، phone.
    - اگر رشته باشد: جستجو بر مبنای نام فارسی یا انگلیسی، یا فیلد office.
- اعمال شرط `whereJsonContains('branch', $request->get('branch'))` برای محدودکردن نمایش به شعبه جاری.
- دریافت داده‌ها با `paginate()` براساس طول و اندیس.
- برای هر رکورد: 
    - واکشی داده ملیت از Redis تحت کلید `countries:{country_id}`.
    - در صورت عدم وجود، کوئری DB و سپس کش‌گذاری در Redis.
    - تبدیل تاریخ تولد و تاریخ انقضای پاسپورت با تابع `Functions::int2DateTime`.
- بازگرداندن داده در قالب DataTables سازگار با `draw`, `recordsTotal`, `recordsFiltered` و آرایه `data`.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%86%D9%88%D8%B9-%D8%B6%D8%B1%D9%88%D8%B1%DB%8C-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD-" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"><table border="1" style="width: 94%; margin: auto; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>نوع</td><td>ضروری</td><td>توضیح</td></tr><tr><td>json</td><td>stringified JSON</td><td>بله</td><td>داده‌های صفحه‌بندی و جستجو شامل `start`, `length`, `search->value`, `draw`.</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td>شناسه شعبه جاری برای فیلتر رکوردها</td></tr></tbody></table>

</div>```
POST /api/v2/customers/list
{
  "json": "{\"start\":0,\"length\":10,\"search\":{\"value\":\"علیرضا\"},\"draw\":1}",
  "branch": 12
}
```

<div id="bkmrk--1" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>### نمونه خروجی موفق

```
{
  "draw": 1,
  "recordsTotal": 1052,
  "recordsFiltered": 1052,
  "data": [
    {
      "passenger_id": 4021,
      "national_code": "1234567890",
      "birthday": "1383/12/10",
      "name_fa": "علیرضا",
      "lastname_fa": "ایرانپور",
      "citizenship": {
        "id": 118,
        "fa_name": "ایران",
        "fa_nationality": "ایرانی"
      },
      "sex": true
    }
  ]
}
```

<div id="bkmrk--2" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>### امنیت

<div id="bkmrk-jwt-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- JWT معتبر برای دسترسی الزامی است.
- فیلتر رکوردها محدود به شعبه کاربر.

</div>### Dependencies

<div id="bkmrk-customer-model-redis" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- Customer Model
- Redis
- DB::table('countries')
- Functions::int2DateTime

</div>### کارایی

پاسخ‌دهی مبتنی بر Redis بسیار سریع است (~3 ms برای داده‌های کش‌شده، ~25 ms برای واکشی اولیه).

<div class="align-right" id="bkmrk--3" style="font-family: Vazir, Tahoma; line-height: 1.85;"></div>### مدیریت خطا

در صورت دریافت ورودی نامعتبر JSON یا branch خالی، منجر به پاسخ ناقص بدون code خاص می‌شود؛ بهتر است اعتبارسنجی اضافه شود.

<div class="align-right" id="bkmrk--4" style="font-family: Vazir, Tahoma; line-height: 1.85;"></div>### اثرات جانبی

کش‌گذاری کشورها در Redis برای آیتم‌های جدید.

<div class="align-right" id="bkmrk--5" style="font-family: Vazir, Tahoma; line-height: 1.85;"></div>### ردپای حسابرسی

ثبت لاگ مستقیم ندارد.

<div class="align-right" id="bkmrk--6" style="font-family: Vazir, Tahoma; line-height: 1.85;"></div>### پیشنهاد بهبود

<div class="align-right" id="bkmrk-%D8%A7%D8%B6%D8%A7%D9%81%D9%87%E2%80%8C%DA%A9%D8%B1%D8%AF%D9%86-ttl-%D8%A8%D9%87-re" style="font-family: Vazir, Tahoma; line-height: 1.85;">- اضافه‌کردن TTL به Redis برای تازه‌سازی خودکار ملیت‌ها.
- بهینه‌سازی جستجو با ایندکس‌های ترکیبی روی فیلدهای اسمی.

</div>### جمع‌بندی

روت امکان واکشی سریع و صفحه‌بندی‌شده‌ی لیست مسافران یک شعبه را فراهم می‌کند. طراحی آن برای محیط‌های DataTables بسیار مناسب است.

<div id="bkmrk-customers-list" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>