#P1543
POST /personnel/list
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/personnel/list |
OfficialController@personnelList |
authWithJwt |
دریافت لیست کامل پرسنل با امکان فیلتر بر اساس وضعیت، شعبه، نقش و بازه زمانی |
منطق عملکرد تابع
تابع personnelList مجموعهای از رکوردهای پرسنل را از پایگاه داده استخراج میکند و فیلترهایی که در درخواست آمده را اعمال مینماید.
- پارسه کردن ورودیها (branch, status, category, search, from, to).
- افزودن شرطهای
where براساس پارامترها (مثلاً فیلتر شعبه فقط اگر ارسال شده باشد).
- پیوستن جداول مرتبط برای افزودن نقش، دسته و سقف مالی.
- مرتبسازی نتایج بر اساس اولویت و نام.
- بازگرداندن داده با ساختار JSON شامل متادیتا.
پارامترهای ورودی
| نام |
محل |
نوع |
الزامی |
توضیح |
| branch |
Body |
integer |
خیر |
شناسه شعبه مورد نظر |
| status |
Body |
integer |
خیر |
وضعیت کاربر (۰ یا ۱) |
| category |
Body |
integer |
خیر |
شناسه دستهبندی پرسنل |
| search |
Body |
string |
خیر |
عبارت جستجو در نام یا کد |
| from |
Body |
string |
خیر |
تاریخ شروع بازه (YYYY-MM-DD) |
| to |
Body |
string |
خیر |
تاریخ پایان بازه (YYYY-MM-DD) |
ساختار خروجی
{
"draw": 1,
"recordsTotal": 25,
"recordsFiltered": 25,
"data": [
{
"id": 101,
"first_name": "نگین",
"last_name": "محمدی",
"branch": "تهران",
"status": "active",
"category": "پشتیبانی",
"financial_ceiling": 40000000
}
]
}
نکات امنیتی
- دسترسی فقط برای کاربران احراز شده با JWT و دارای نقش HR یا مدیر.
- کنترل صحت سطح دسترسیها در Middleware انجام میشود.
عملکرد
- Optimized query با Index روی ستونهای branch و status.
- Limit/Pagination برای جلوگیری از بارگذاری بیش از حد.
Dependencies
- Illuminate\Support\Facades\DB
کدهای خطا
| کد |
شرح |
منبع |
| 401 |
توکن معتبر نیست یا منقضی شده |
AuthWithJwt |
| 403 |
عدم دسترسی |
Role Check |
| 500 |
اشکال داخلی |
Exception Handler |
پیشنهادهای امنیتی
- ثبت کامل لاگ جستجوها برای ممیزی.
پیشنهادهای توسعهای
- امکان خروجی گرفتن به Excel و PDF.
- افزودن فیلتر پیشرفته براساس نقش.
ممیزی و ثبت وقایع
- ثبت پارامترهای جستجو و تعداد نتایج در جدول audit.
جمعبندی
personnelList ابزاری قدرتمند برای مدیران و HR جهت مدیریت و پایش پرسنل با فیلترهای متنوع است.
