# POST /api/v2/passengers/search

<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/passengers/search</td><td style="direction: ltr;">UserController@searchPassengers</td><td style="direction: ltr;">authWithJwt</td><td style="direction: rtl; text-align: right;">جست‌وجوی سریع مسافران (مشتریان) با تطبیق نام، کد ملی یا پاسپورت</td></tr></tbody></table>

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

<div id="bkmrk-%D8%A7%DA%AF%D8%B1-%D9%85%D9%82%D8%AF%D8%A7%D8%B1-like-%D8%A8%D8%A7-%C2%AB%DB%B9" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- اگر مقدار `like` با «۹۹۹» شروع نشود، جست‌وجو آغاز می‌شود.
- از جدول `customers` داده‌ها بر اساس `first_name`، `last_name`، `national_code`، `passport_code`، `mobile` و … واکشی می‌شوند.
- در صورتی که `action == 'passport'` باشد فقط مسافرانی نمایش داده می‌شوند که پاسپورت ثبت‌شده دارند.
- در هر نتیجه، تابع کمکی `replaceWithStars()` برای سانسور بخش‌هایی از کد ملی یا پاسپورت در صورت عدم مجازبودن شعبه اعمال می‌شود.
- ملیت (nationality) از Redis کش می‌شود؛ در صورت نبود، از DB بازیابی و در Redis ذخیره می‌گردد.
- در خروجی نهایی دو حالت وجود دارد: 
    - **allow=true:** مشاهده‌ی کامل داده برای شعب مجاز.
    - **allow=false:** بخش‌هایی از داده به‌صورت ماسک‌شده بازگردانده می‌شود.

</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: 93%; 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>like</td><td>string</td><td>بله</td><td>عبارت مورد جست‌وجو (نام، کدملی، پاسپورت یا موبایل)</td></tr><tr><td>action</td><td>string</td><td>خیر</td><td>نوع جست‌وجو ('passport' یا سایر)</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td>شناسه‌ی شعبه برای بررسی مجوز مشاهده اطلاعات</td></tr></tbody></table>

</div>```
POST /api/v2/passengers/search
{
  "like": "رضا",
  "action": "passport",
  "branch": 25
}
```

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

<div id="bkmrk-%D8%AF%D8%B1-%D8%AD%D8%A7%D9%84%D8%AA-%D9%88%D8%AC%D9%88%D8%AF-%D8%AF%D8%A7%D8%AF%D9%87%D8%8C-%D8%AE" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- در حالت وجود داده، خروجی یک آرایه از اشیاء Passenger است.

</div>```
[
  {
    "allow": true,
    "id": 5043,
    "sex": 1,
    "first_name": "Reza",
    "first_name_fa": "رضا",
    "last_name": "Moradi",
    "last_name_fa": "مرادی",
    "mobile": "09123456789",
    "national_code": "1234567890",
    "passport_code": "M3423112",
    "birth": {
      "fa": "1382/12/14",
      "en": "2004/03/04"
    },
    "nationality": {
      "id": 118,
      "iso": "IR",
      "en_nationality": "Iranian",
      "fa_nationality": "ایرانی"
    }
  }
]
```

<div id="bkmrk-%2A%2A%D8%AF%D8%B1-%D8%B5%D9%88%D8%B1%D8%AA-%D8%B9%D8%AF%D9%85-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**در صورت عدم دسترسی (allow=false):**</div>```
[
  {
    "allow": false,
    "id": 3331,
    "mobile": "***********",
    "national_code": "123****890",
    "passport_code": "******",
    "birth": {"fa": false, "en": false},
    "nationality": false
  }
]
```

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

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

</div>### وابستگی‌ها

<div id="bkmrk-db%3A%3Atable%28%27customers" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- DB::table('customers')
- Redis Cache (countries)
- Carbon + Jalalian
- Morilog\\Jalali\\CalendarUtils

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

افزودن Limit 20 باعث شده به‌طور میانگین &lt;40 ms پاسخ دهد؛ داده کش‌شده Redis زمان را تا 2 ms کاهش می‌دهد.

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

<div id="bkmrk-%D8%AF%D8%B1-%D8%B5%D9%88%D8%B1%D8%AA-%D8%B4%D8%B1%D9%88%D8%B9-like-%D8%A8%D8%A7" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- در صورت شروع `like` با 999 جستجو انجام نمی‌شود (خروجی خالی).
- در سایر موارد، خطاها توسط سطح سیستم مدیریت می‌شود.

</div>### اثرات جانبی

<div id="bkmrk-%DA%A9%D8%B4%E2%80%8C%D8%B3%D8%A7%D8%B2%DB%8C-%D9%85%D9%84%DB%8C%D8%AA-%DA%A9%D8%B4%D9%88%D8%B1-%D8%AF%D8%B1" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- کش‌سازی ملیت کشور در Redis برای بهبود سرعت.

</div>### ردپای حسابرسی

هیچ داده‌ای ثبت نمی‌شود (عملیات فقط خواندنی است).

<div id="bkmrk--4" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;"></div>### پیشنهاد بهبود

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%AD%D8%B0%D9%81-%D8%AE%D9%88%D8%AF%DA%A9%D8%A7%D8%B1-ca" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- افزودن حذف خودکار cache کشورها با TTL ۲۴ ساعته.
- امکان مرتب‌سازی خروجی بر اساس تاریخ تولد یا نام.
- جلوگیری از درخواست‌های بدون فیلتر طولانی (rate limit).

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

این Endpoint ابزار سریع و امنی برای جست‌وجوی مشتریان (مسافران) است که با کنترل شعبه و ماسکینگ داده‌ها، هم دقت و هم امنیت را تضمین می‌کند.

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