# POST /api/v2/operator/update-password

<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/operator/update-password</td><td style="direction: ltr;">UserController@updatePassword</td><td style="direction: ltr;">authWithJwt</td><td style="direction: rtl; text-align: right;">تغییر رمز عبور اپراتور (کاربر) با احراز رمز فعلی</td></tr></tbody></table>

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

<div id="bkmrk-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87%D9%88%DB%8C%D8%AA-%D8%A8%D8%A7-%D9%85%D8%AA%D8%AF-au" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- احراز هویت با متد `Auth::once` بر مبنای `personnel_id` و رمز فعلی (`last_password`) انجام می‌شود.
- درصورت اشتباه بودن رمز فعلی، پاسخ JSON با `status=false` و پیام خطای مناسب بازگردانده می‌شود.
- درصورت صحت رمز فعلی، رکورد کاربر جاری از مدل `User` واکشی شده و رمز جدید با `Hash::make` هش و ذخیره می‌شود.
- پس از موفقیت، یک لاگ ناهمگام `SystemLog(type=UpdatePassword)` در صف `snailJob` ایجاد می‌شود.

</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: 92%; 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>personnelId</td><td>integer</td><td>بله</td><td>کد پرسنلی اپراتور (User personnel\_id)</td></tr><tr><td>last\_password</td><td>string</td><td>بله</td><td>رمز عبور فعلی برای تأیید</td></tr><tr><td>new\_password</td><td>string</td><td>بله</td><td>رمز عبور جدید مورد نظر</td></tr></tbody></table>

</div>```
POST /api/v2/operator/update-password
{
  "personnelId": 102,
  "last_password": "oldPass@123",
  "new_password": "Secure#2025"
}
```

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

<div id="bkmrk-%2A%2A%D9%85%D9%88%D9%81%D9%82%3A%2A%2A" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**موفق:**</div>```
{
  "status": true,
  "time": 1732031104
}
```

<div id="bkmrk-%2A%2A%D8%B1%D9%85%D8%B2-%D8%A7%D8%B4%D8%AA%D8%A8%D8%A7%D9%87%3A%2A%2A" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**رمز اشتباه:**</div>```
{
  "status": false,
  "time": 1732031104,
  "message": "کلمه عبور فعلی اشتباه می باشد"
}
```

<div id="bkmrk-%2A%2A%D8%AE%D8%B7%D8%A7%DB%8C-%D9%81%D8%B1%D8%A2%DB%8C%D9%86%D8%AF-%D8%A8%D9%87%E2%80%8C%D8%B1%D9%88%D8%B2" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">**خطای فرآیند به‌روزرسانی:**</div>```
{
  "status": false,
  "time": 1732031104,
  "message": "عملیات تغییر کلمه عبور با مشکل مواجه شد"
}
```

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

<div id="bkmrk-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%D8%A7%D8%B2-jwt%E2%80%AFtoken" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- استفاده از **JWT Token** الزامی.
- رمز عبور در سرور با `bcrypt` هش می‌شود و نسخه خام هرگز ذخیره نمی‌شود.
- احراز موقت با `Auth::once()` برای جلوگیری از زمان طولانی توکن اعتبار.

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

<div id="bkmrk-auth-facade-%28one-tim" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- Auth Facade (one-time login)
- Hash::make()
- Carbon::now()
- SystemLog Job Queue (snailJob)

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

میانگین زمان پاسخ سرور &lt;10 ms، صف لاگ asynchronous است.

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

<div id="bkmrk-%D8%AE%D8%B7%D8%A7%D9%87%D8%A7%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-%D8%A8%D8%A7-%D9%81%DB%8C%D9%84%D8%AF" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- خطاهای معتبر با فیلد `message` کاربرپسند بازگردانده می‌شود.
- به‌جای استثناء، خروجی JSON کنترل‌شده ارائه می‌شود.

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

<div id="bkmrk-%D8%AA%D8%BA%DB%8C%DB%8C%D8%B1-%D9%81%D9%88%D8%B1%DB%8C-%D8%B1%D9%85%D8%B2-%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- تغییر فوری رمز کاربر در DB.
- ورود مجدد برای توکن فعلی توصیه می‌شود (Token Invalidation Plan در آینده).

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

وقوع عملیات در SystemLog با نوع `UpdatePassword` و فیلد goal=personnelId ثبت می‌گردد.

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

<div id="bkmrk-%D8%A7%D8%B9%D9%85%D8%A7%D9%84-%D9%85%D9%86%D8%B7%D9%82-complexit" style="direction: rtl; font-family: Vazir,Tahoma; text-align: justify; line-height: 1.85;">- اعمال منطق Complexity Policy برای رمز جدید (طول &gt; 8 کاراکتر، حروف + نشانه).
- لاگ‌آوت خودکار پس از تغییر رمز.

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

روت مذکور راه ساده اما امنی برای تغییر رمز عبور اپراتور فراهم می‌کند و با وجود کنترل‌های Auth::once و SystemLog، مطمئن و قابل ردیابی است.

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