#P1434
GET /api/v2/calendar
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| GET | /api/v2/calendar | UserController@calendar | authWithJwt | دریافت تقویم کاری ماهانه پرسنل با اطلاعات شیفت، تردد، مرخصی، تعطیلات و وظایف. |
منطق عملکرد
- از کلاس کمکی
Attendanceمقداردهی اولیه شیفت انجام میشود با متدgetPersonnelShiftWork(year, month, operator_id, shift_work, branch). - مقادیر
loginوtime_workاز شیفت جاری استخراج و به آرایه روزهای هفته تبدیل میشوند. - ورودیهای ثبتشده در جدول
rollcallsبرای پرسنل در بازه بین روز اول تا سی و یکم همان ماه واکشی میشوند. - درخواستها با وضعیت:
- status=3: ورود تأییدشده.
- status=1: ورود در انتظار تأیید (pending).
- مرخصیها (جدول
rollcall_licenses) با وضعیتهای فعال استخراج میشوند، همراه با تجمیع نوع مرخصی با کوئری aggregate. - تعطیلات رسمی (`holidays`) با فیلتر `year`, `month`, `status=1` دریافت میشوند.
- وظایف کارتابلی توسط
OfficialController::getTasks('all', false, operator_id, from, to, 1)واکشی و در تقویم توزیع میشوند. - در انتها متد
Attendance::calendarداده نهایی را ساختاردهی و بازمیگرداند.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| year | integer | بله | سال جاری برای نمایش تقویم. |
| month | integer | بله | ماه هدف برای محاسبه شیفت و تردد. |
| operator | object | خیر | از JWT خوانده میشود، شامل id, personnel_id, shift_work. |
| branch | integer | بله | شناسه شعبهای که اپراتور در آن مشغول است. |
GET /api/v2/calendar?year=1404&month=8 Authorization: Bearer <JWT>
نمونه خروجی موفق
{
"status": true,
"time": 1732036800,
"shift": [
{"title":"شنبه","login":"08:30","logout":"17:30"},
{"title":"یکشنبه","login":"08:30","logout":"17:30"},
{"title":"دوشنبه","login":"08:30","logout":"17:30"}
],
"data": [
{ "day": 5, "type": "work", "status": "present", "tasks": [ {"title": "جلسه فنی"} ] },
{ "day": 6, "type": "holiday", "title": "تعطیل رسمی" }
]
}
امنیت و کنترل دسترسی
- JWT الزامی است.
- اطلاعات شخصی بر اساس شناسه اپراتور استخراج میشود؛ اپراتور تنها شیفتهای خود را میبیند.
Dependencies
- Attendance (Custom Library)
- OfficialController
- Carbon
- CalendarUtils
- DB, Functions Helper
کارایی
بهدلیل کوئریهای همزمان روی چند جدول، زمان اجرا بین 80 تا 120 ms است. کش دادههای شیفت برای نسخه بعدی توصیه میشود.
مدیریت خطا
اگر هیچ دادهای یافت نشود یا شیفت کاربر تعریف نشده باشد، پاسخ با `status=false` و پیام `اطلاعاتی یافت نشد` بازگردانده میشود.
اثرات جانبی
خواندن اطلاعات بدون تغییر در دیتابیس.
ردپای حسابرسی
ندارد.
پیشنهاد بهبود
- کش شیفتها و تعطیلات در Redis برای کاهش زمان پاسخ.
- ثبت لاگ در زمان لود تقویم برای تحلیل حضور و غیاب.
جمعبندی
روت تقویم کاری محوریترین قسمت ماژول منابع انسانی است. داده شیفت، مرخصی، تعطیلات و وظایف را یکجا تجمیع کرده و در خروجی منسجم ماهانه ارائه میدهد.