# POST /api/v2/passenger/add-branch

<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/passenger/add-branch</td><td style="direction: ltr;">UserController@addUserToBranch</td><td style="direction: ltr;">authWithJwt</td><td style="direction: rtl; text-align: right;">افزودن مسافر به شعبه در صورت تطابق کد ملی یا پاسپورت</td></tr></tbody></table>

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

<div id="bkmrk-%D9%88%D8%A7%DA%A9%D8%B4%DB%8C-%D8%B1%DA%A9%D9%88%D8%B1%D8%AF-%D9%85%D8%B3%D8%A7%D9%81%D8%B1-%D8%A7%D8%B2" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- واکشی رکورد مسافر از جدول `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 و برگرداندن پیام خطا با تعداد فرصت‌های باقی‌مانده.
    - اگر شمارنده به سقف رسید: پیام محدودیت زمانی.
- اگر مسافر وجود نداشت: پیام خطای "مسافر یافت نشد".

</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>passenger\_id</td><td>integer</td><td>بله</td><td>شناسه مسافر در جدول customers</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td>شناسه شعبه جاری</td></tr><tr><td>action</td><td>string</td><td>بله</td><td>'national' یا 'passport' برای تعیین نوع تطابق</td></tr><tr><td>national\_code</td><td>string</td><td>خیر</td><td>کد ملی (برای action = national)</td></tr><tr><td>passport\_code</td><td>string</td><td>خیر</td><td>شماره پاسپورت (برای action = passport)</td></tr></tbody></table>

</div>```
POST /api/v2/passenger/add-branch
{
  "passenger_id": 502,
  "branch": 12,
  "action": "national",
  "national_code": "1234567890"
}
```

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

```
{
  "status": true,
  "time": 1732034501,
  "data": {
    "allow": true,
    "id": 502,
    "first_name_fa": "علیرضا",
    ...
  },
  "message": "مسافر با موفقیت  به دفتر شما افزوده شد"
}
```

<div id="bkmrk-%2A%2A%D9%86%D9%85%D9%88%D9%86%D9%87-%D8%AE%D8%B7%D8%A7%DB%8C-%D8%AA%D8%B7%D8%A7%D8%A8%D9%82%3A%2A" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**نمونه خطای تطابق:**</div>```
{
  "status": false,
  "time": 1732034501,
  "message": "اطلاعات وارد شده مختص  این مسافر نمی باشد | درخواست باقی مانده: 3"
}
```

<div id="bkmrk-%2A%2A%D9%86%D9%85%D9%88%D9%86%D9%87-%D8%AE%D8%B7%D8%A7%DB%8C-%D9%85%D8%AD%D8%AF%D9%88%D8%AF%DB%8C%D8%AA" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**نمونه خطای محدودیت:**</div>```
{
  "status": false,
  "time": 1732034501,
  "message": "متاسفانه در افزودن این مسافر به محدودیت خورده اید. لطفا 15 دقیقه دیگر تلاش فرمائید."
}
```

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

<div id="bkmrk-%D9%81%D9%82%D8%B7-%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1%D8%A7%D9%86-%D8%A8%D8%A7-jwt-%D9%85" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- فقط کاربران با JWT معتبر اجازه دارند.
- کنترل تعداد تلاش (Rate-limit) با Redis برای جلوگیری از brute force روی کد ملی/پاسپورت.

</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
- Carbon
- Morilog\\Jalali\\Jalalian
- Country Model

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

عملیات فقط شامل یک SELECT و یک UPDATE است، حدود 5~20 ms.

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

تمام پاسخ‌ها در قالب JSON با فیلدهای `status` و `message` برگردانده می‌شوند.

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

تغییر فیلد branch در رکورد مسافر.

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

هیچ لاگ مستقیم ثبت نمی‌شود.

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

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-%D9%84%D8%A7%DA%AF-%D8%B1%D9%88%DB%8C%D8%AF%D8%A7%D8%AF-%D9%85%D9%88%D9%81%D9%82-" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- ثبت لاگ رویداد موفق به SystemLog برای پیگیری.
- ارسال نوتیفیکیشن به کاربر شعبه در صورت اضافه شدن.

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

روت امکان افزودن سریع مسافران موجود به شعبه را با کنترل امنیتی و محدودیت تلاش فراهم می‌کند.

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