#P1425
POST /api/v2/passengers/search
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/passengers/search | UserController@searchPassengers | authWithJwt | جستوجوی سریع مسافران (مشتریان) با تطبیق نام، کد ملی یا پاسپورت |
منطق عملکرد
- اگر مقدار
likeبا «۹۹۹» شروع نشود، جستوجو آغاز میشود. - از جدول
customersدادهها بر اساسfirst_name،last_name،national_code،passport_code،mobileو … واکشی میشوند. - در صورتی که
action == 'passport'باشد فقط مسافرانی نمایش داده میشوند که پاسپورت ثبتشده دارند. - در هر نتیجه، تابع کمکی
replaceWithStars()برای سانسور بخشهایی از کد ملی یا پاسپورت در صورت عدم مجازبودن شعبه اعمال میشود. - ملیت (nationality) از Redis کش میشود؛ در صورت نبود، از DB بازیابی و در Redis ذخیره میگردد.
- در خروجی نهایی دو حالت وجود دارد:
- allow=true: مشاهدهی کامل داده برای شعب مجاز.
- allow=false: بخشهایی از داده بهصورت ماسکشده بازگردانده میشود.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| like | string | بله | عبارت مورد جستوجو (نام، کدملی، پاسپورت یا موبایل) |
| action | string | خیر | نوع جستوجو ('passport' یا سایر) |
| branch | integer | بله | شناسهی شعبه برای بررسی مجوز مشاهده اطلاعات |
POST /api/v2/passengers/search
{
"like": "رضا",
"action": "passport",
"branch": 25
}
ساختار خروجی
- در حالت وجود داده، خروجی یک آرایه از اشیاء Passenger است.
[
{
"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": "ایرانی"
}
}
]
**در صورت عدم دسترسی (allow=false):**
[
{
"allow": false,
"id": 3331,
"mobile": "***********",
"national_code": "123****890",
"passport_code": "******",
"birth": {"fa": false, "en": false},
"nationality": false
}
]
امنیت
- JWT الزامی است.
- بررسی مالکیت شعبه قبل از نمایش داده کامل.
- سانسور خودکار دادهها برای شعب غیرمجاز.
وابستگیها
- DB::table('customers')
- Redis Cache (countries)
- Carbon + Jalalian
- Morilog\Jalali\CalendarUtils
کارایی
افزودن Limit 20 باعث شده بهطور میانگین <40 ms پاسخ دهد؛ داده کششده Redis زمان را تا 2 ms کاهش میدهد.
مدیریت خطا
- در صورت شروع
likeبا 999 جستجو انجام نمیشود (خروجی خالی). - در سایر موارد، خطاها توسط سطح سیستم مدیریت میشود.
اثرات جانبی
- کشسازی ملیت کشور در Redis برای بهبود سرعت.
ردپای حسابرسی
هیچ دادهای ثبت نمیشود (عملیات فقط خواندنی است).
پیشنهاد بهبود
- افزودن حذف خودکار cache کشورها با TTL ۲۴ ساعته.
- امکان مرتبسازی خروجی بر اساس تاریخ تولد یا نام.
- جلوگیری از درخواستهای بدون فیلتر طولانی (rate limit).
جمعبندی
این Endpoint ابزار سریع و امنی برای جستوجوی مشتریان (مسافران) است که با کنترل شعبه و ماسکینگ دادهها، هم دقت و هم امنیت را تضمین میکند.