#P1540
GET /personnel/attendance
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| GET |
/personnel/attendance |
OfficialController@attendancePersonnel |
authWithJwt |
دریافت لیست حضور و غیاب پرسنل با امکان فیلتر پیشرفته و جزئیات مالی |
منطق عملکرد تابع
متد attendancePersonnel پس از تأیید احراز هویت، اطلاعات حضور و غیاب پرسنل را با پارامترهای فیلتر متنوع برگردانده و در خروجی جزئیات مالی مرتبط را بهمراه اسناد ثبت شده نمایش میدهد.
- دریافت داده ورودی از
Request شامل فیلترها، تاریخها و شناسه پرسنل.
- جستجوی رکورد پرسنل در جدول مرتبط.
- بر اساس شرایط زمانبندی یا کلید جستجوی پیشرفته (
advanced)، استخراج حضورها از دیتابیس.
- ساخت آرایه
Items شامل اطلاعات هر رویداد:
- شماره سریال و شناسه سیستم
- تاریخ و ساعت ثبت حضور
- جزئیات عنوان، نوع سند، مبلغ بستانکاری/بدهکاری، تشخیص وضعیت
- مرتبسازی اقلام بر اساس زمان به صورت صعودی.
- در صورت نیاز، افزودن سند افتتاحیه از جدول
financial_pasts به ابتدای لیست.
- بازگرداندن خروجی همراه با جزئیات پرسنل، محدوده فیلتر شده، و دادهها.
پارامترهای ورودی
| نام |
محل |
نوع |
الزامی |
توضیح |
| id |
Query |
integer |
بله |
شناسه پرسنل |
| advanced |
Body(JSON) |
object |
خیر |
شیء فیلتر پیشرفته شامل تاریخ شروع/پایان، شناسه سند، وضعیت، و ... |
| draw |
Body(JSON) |
integer |
خیر |
شماره درخواست برای DataTables |
ساختار خروجی
{
"draw": 1,
"recordsTotal": 100,
"recordsFiltered": 10,
"filtered": {
"from": "2025/11/01",
"to": "2025/11/23"
},
"details": { ...personnelObject },
"data": [
{
"serial_id": 12345,
"system_serial": 6789,
"datetime": "1404/08/01 08:15:00",
"details": {
"title": { "html": "نام پرسنل | توضیحات سند", "text": "..." },
"type": { "subject": "pay", "title": "سند مالی" }
},
"credit": 0,
"debit": 500000,
"diagnosis": "debtor"
}
]
}
نکات امنیتی
- الزام استفاده از توکن JWT معتبر برای دسترسی به مسیر.
- کنترل مجوز روی شناسه پرسنل ارسال شده جهت جلوگیری از مشاهده اطلاعات سایر کاربران.
- ولیدیشن صحیح دادههای ورودی (بخصوص تاریخها و کلید فیلتر).
عملکرد
- مرتبسازی با تابع
usort بر اساس تاریخ انجام میشود که برای لیست بزرگ باید بهینهسازی شود.
- افزودن سند افتتاحیه از دیتابیس قبل از پاسخ نهایی یک Query اضافی ایجاد میکند.
Dependencies
- use Illuminate\Support\Facades\DB;
- use Morilog\Jalali\Jalalian;
- use Carbon\Carbon;
کدهای خطا
| کد |
شرح |
منبع |
| 404 |
پرسنل یافت نشد |
Query DB |
| 401 |
توکن نامعتبر |
AuthWithJwt |
| 400 |
پارامترهای ورودی نامعتبر |
Validation |
پیشنهادهای امنیتی
- اعمال محدودیت مشاهده حضور و غیاب به سرپرستان یا بخش HR.
- ثبت تمامی درخواستهای مشاهده در جدول لاگ.
پیشنهادهای توسعهای
- افزودن قابلیت صفحهبندی و سرچ سمت سرور برای دیتاهای بزرگ.
- امکان فیلتر بر اساس نوع رویداد حضور (ورود، خروج، مرخصی و ...).
ممیزی و ثبت وقایع
- ثبت زمان و شناسه کاربر مشاهده کننده، همراه IP.
- ثبت مجموع رکوردهای دیده شده در هر درخواست.
جمعبندی
attendancePersonnel مسیر پایه برای مشاهده وضعیت حضور پرسنل با جزئیات مالی است. اگر کنترل سطح دسترسی و ثبت رویدادها بهدرستی اجرا شود، مسیر قابلیت استفاده در محیطهای حساس را دارد.
