#P1426
POST /api/v2/passenger/add-branch
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/passenger/add-branch | UserController@addUserToBranch | authWithJwt | افزودن مسافر به شعبه در صورت تطابق کد ملی یا پاسپورت |
منطق عملکرد
- واکشی رکورد مسافر از جدول
customersبر اساسpassenger_id. - اگر مسافر وجود داشت:
- کنترل محدودیت درخواست با استفاده از
Redis key(check-add-passenger:{passenger_id}:{operator_id})، حداکثر ۵ تلاش در مدت ۱۵ دقیقه. - تطبیق اطلاعات بر اساس
action:national→ تطابقnational_code.passport→ تطابقpassport_code.
- اگر تطابق برقرار بود:
- بروزرسانی فیلد
branchبا اضافه کردن شعبهٔ جدید (به صورت JSON ذخیره میشود) و حذف مقادیر تکراری باarray_unique(). - تولید پاسخ شامل داده کامل مسافر، ملیت (از مدل
Country) و تاریخ تولد به فرمت فارسی و میلادی.
- بروزرسانی فیلد
- اگر تطابق برقرار نبود: افزایش شمارنده در Redis و برگرداندن پیام خطا با تعداد فرصتهای باقیمانده.
- اگر شمارنده به سقف رسید: پیام محدودیت زمانی.
- کنترل محدودیت درخواست با استفاده از
- اگر مسافر وجود نداشت: پیام خطای "مسافر یافت نشد".
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| passenger_id | integer | بله | شناسه مسافر در جدول customers |
| branch | integer | بله | شناسه شعبه جاری |
| action | string | بله | 'national' یا 'passport' برای تعیین نوع تطابق |
| national_code | string | خیر | کد ملی (برای action = national) |
| passport_code | string | خیر | شماره پاسپورت (برای action = passport) |
POST /api/v2/passenger/add-branch
{
"passenger_id": 502,
"branch": 12,
"action": "national",
"national_code": "1234567890"
}
نمونه خروجی موفق
{
"status": true,
"time": 1732034501,
"data": {
"allow": true,
"id": 502,
"first_name_fa": "علیرضا",
...
},
"message": "مسافر با موفقیت به دفتر شما افزوده شد"
}
**نمونه خطای تطابق:**
{
"status": false,
"time": 1732034501,
"message": "اطلاعات وارد شده مختص این مسافر نمی باشد | درخواست باقی مانده: 3"
}
**نمونه خطای محدودیت:**
{
"status": false,
"time": 1732034501,
"message": "متاسفانه در افزودن این مسافر به محدودیت خورده اید. لطفا 15 دقیقه دیگر تلاش فرمائید."
}
امنیت
- فقط کاربران با JWT معتبر اجازه دارند.
- کنترل تعداد تلاش (Rate-limit) با Redis برای جلوگیری از brute force روی کد ملی/پاسپورت.
وابستگیها
- DB::table('customers')
- Redis
- Carbon
- Morilog\Jalali\Jalalian
- Country Model
کارایی
عملیات فقط شامل یک SELECT و یک UPDATE است، حدود 5~20 ms.
مدیریت خطا
تمام پاسخها در قالب JSON با فیلدهای status و message برگردانده میشوند.
اثرات جانبی
تغییر فیلد branch در رکورد مسافر.
ردپای حسابرسی
هیچ لاگ مستقیم ثبت نمیشود.
پیشنهاد بهبود
- ثبت لاگ رویداد موفق به SystemLog برای پیگیری.
- ارسال نوتیفیکیشن به کاربر شعبه در صورت اضافه شدن.
جمعبندی
روت امکان افزودن سریع مسافران موجود به شعبه را با کنترل امنیتی و محدودیت تلاش فراهم میکند.