# POST /personnel/operation

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="border-collapse: collapse; margin: 15px auto; width: 96%; 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 dir="ltr">POST</td><td dir="ltr">/personnel/operation</td><td dir="ltr">OfficialController@operationPersonnel</td><td dir="ltr">authWithJwt</td><td dir="rtl">اجرای عملیات مدیریتی روی پرونده پرسنل (بروزرسانی، تغییر وضعیت، مسدودسازی موقت)</td></tr></tbody></table>

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

این متد عملیاتی را که از طریق کلید `action` مشخص می‌شود، روی پرسنل اجرا می‌کند:

<div id="bkmrk-update%3A-%D8%A2%D9%85%D8%A7%D8%AF%D9%87%E2%80%8C%D8%B3%D8%A7%D8%B2%DB%8C-%D8%A8" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- **update**: آماده‌سازی برای بروزرسانی اطلاعات پرسنل (در نسخه فعلی فاقد منطق داخلی).
- **status**: تغییر فیلد `status` اپراتور مشخص‌شده.
- **blocking**: ثبت زمان مسدودسازی تا لحظه‌ای معین روی فیلد `blocked_up` اپراتور.

</div>در پایان، نتیجه اجرای عملیات به‌صورت JSON بازگردانده می‌شود.

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%85%D8%AD%D9%84-%D9%86%D9%88%D8%B9-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="border-collapse: collapse; width: 95%; margin: 15px auto; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>محل</td><td>نوع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>action</td><td>Body</td><td>string</td><td>بله</td><td>نوع عملیات (update, status, blocking)</td></tr><tr><td>id</td><td>Body</td><td>integer</td><td>بله</td><td>شناسه اپراتور هدف</td></tr><tr><td>status</td><td>Body</td><td>integer</td><td>خیر</td><td>مقدار وضعیت جدید (برای action=status)</td></tr><tr><td>duration</td><td>Body</td><td>integer</td><td>خیر</td><td>مدت زمان مسدودسازی به دقیقه (پیش‌فرض: 15 دقیقه، برای action=blocking)</td></tr></tbody></table>

</div>### ساختار خروجی

```
// موفق
{
  "status": true,
  "time": 1732365890
}

// خطا
{
  "status": false,
  "time": 1732365890,
  "message": "500 : SQLSTATE[...]", 
  "trace": [ ... ]
}
```

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

<div id="bkmrk-%D8%A7%D8%AC%D8%B1%D8%A7%DB%8C-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA-%D9%81%D9%82%D8%B7-%D8%AA%D9%88%D8%B3" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اجرای عملیات فقط توسط ادمین‌ها یا کاربران دارای مجوز مدیریت پرسنل مجاز است.
- ورودی‌ها باید اعتبارسنجی شوند تا از تغییر ناخواسته اطلاعات جلوگیری شود.

</div>### عملکرد

<div id="bkmrk-%D8%AA%D9%85%D8%A7%D9%85%DB%8C-%D8%AA%D8%BA%DB%8C%DB%8C%D8%B1%D8%A7%D8%AA-%D8%A8%D8%A7-%DB%8C%DA%A9-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- تمامی تغییرات با یک کوئری ساده `UPDATE` روی جدول `operators` انجام می‌شود.
- پاسخ معمولاً کمتر از 50ms تولید می‌شود.

</div>### Dependencies

<div id="bkmrk-illuminate%5Csupport%5Cf" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- Illuminate\\Support\\Facades\\DB
- Carbon\\Carbon
- Exception handling (PHP native)

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-500-%D8%AE%D8%B7%D8%A7%DB%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="border-collapse: collapse; width: 90%; margin: 15px auto; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح</td><td>منبع</td></tr><tr><td>500</td><td>خطای عمومی پایگاه داده یا منطق</td><td>Exception</td></tr><tr><td>400</td><td>ورودی نامعتبر</td><td>Validation layer</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-%D9%84%D8%A7%DA%AF-%DA%A9%D8%A7%D9%85%D9%84-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت لاگ کامل عملیات انجام‌شده همراه با کاربر اجراکننده.
- محدود کردن مدت مسدودسازی به حداکثر معقول (مثلاً 24 ساعت).

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%AA%DA%A9%D9%85%DB%8C%D9%84-%D9%85%D9%86%D8%B7%D9%82-action%3Dup" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- تکمیل منطق action=update برای بروزرسانی خودکار اطلاعات.
- افزودن پاسخ استاندارد همراه با نتیجه دقیق هر عملیات.

</div>### ممیزی و ثبت وقایع

<div id="bkmrk-%D9%87%D8%B1-%D8%AA%D8%BA%DB%8C%DB%8C%D8%B1-%D8%AF%D8%B1-%D9%88%D8%B6%D8%B9%DB%8C%D8%AA-%DB%8C%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- هر تغییر در وضعیت یا مسدودسازی باید در جدول logهای امنیتی ذخیره شود.

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

**operationPersonnel** ابزار مدیریتی پرسنل است که امکان تغییر سریع وضعیت یا اعمال محدودیت را فراهم می‌کند و باید با سیاست‌های امنیتی سختگیرانه اجرا شود.

<div id="bkmrk-post-personnel-operation" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>