#P1432
GET /api/v2/cartable/requests/list
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| GET | /api/v2/cartable/requests/list | UserController@listCartableRequests | authWithJwt | دریافت لیست درخواستهای کارتابل بر اساس نوع دستهبندی (در حال بررسی / رد شده / تایید شده) |
منطق عملکرد
- بر اساس مقدار
categoryسه حالت دارد:- category = 1: درخواستهای در حال بررسی برای مدیران، جانشینها یا مدیرعامل.
- category = 2: درخواستهای ردشده برای کاربر جاری.
- category = 3: درخواستهای تایید شده (تکمیلشده).
- در هر حالت، دو نوع داده بازیابی میشود:
rollcall_licenses→ مرخصیها و مأموریتها.rollcalls→ درخواستهای تردد ثبتنشده.
- منطق دسترسی بر اساس نقش:
- CEO: دسترسی به همه درخواستها در شعبه، شامل فیلتر پالایش تایید و جانشین.
- مدیران: درخواستهای زماندار و جانشینی مرتبط به گروه مدیریتی.
- کارمندان: فقط درخواستهای شخصی خود.
- برای هر مورد، رشته
titleبا استفاده از نوع مرخصی (استحقاقی، استعلاجی، تشویقی، بدون حقوق، مأموریت) و نوع زمانی (روزانه / ساعتی) ساخته میشود. - تاریخها با
Jalalian::fromFormat('Ymd', ...)->format('%A, %d %B %Y')به فارسی تبدیل شدهاند. - جزئیات هر درخواست شامل اطلاعات تأیید، جانشین، و تأیید نهایی در ساختار سهگانه `details` درج میگردد.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| category | integer | بله | نوع دستهبندی درخواستها (۱=درحال بررسی، ۲=رد شده، ۳=تایید شده). |
| branch | integer | بله | شناسه شعبه جاری. |
| operator | object (JWT extracted) | بله | اپراتور فعلی برای تشخیص نقش دسترسی و فیلتر رکورد. |
GET /api/v2/cartable/requests/list?category=1 Header: Authorization: Bearer <JWT>
نمونه خروجی موفق
{
"status": true,
"time": 1732025400,
"data": [
{
"id": 551,
"status": 1,
"operator": {"id": 42, "name": "علیرضا ایرانپور"},
"operation_type": "confirm",
"type": "rollcall_licenses",
"title": "آیا موافقت میکنید با درخواست مرخصی استحقاقی روزانه از تاریخ شنبه، 10 خرداد 1404 تا تاریخ دوشنبه، 12 خرداد 1404 | سفر شخصی",
"tags": ["مرخصی استحقاقی","روزانه"],
"details": {
"confirm": {"by": {"id": 42,"name": "علیرضا"}, "at": "2025-11-19 09:10:04"},
"final_approval": {"by": false, "at": false, "note": false}
}
}
]
}
امنیت و کنترل دسترسی
- تمامی مسیرها زیر میدلور `authWithJwt` اجرا میشوند.
- بررسی نقش اپراتور از فیلد
operator->idو مدیر شعبه ازoffices.leader. - فیلتر رکوردها بر اساس JSON ساختاریافته در
office_departments.managers.
Dependencies
- DB Facade
- Carbon
- Morilog\Jalali\Jalalian
- Functions Helper
- StaticController::getOperators()
کارایی
بهدلیل استفاده از کوئریهای چندهگانه `distinct + leftJoin` زمان پاسخ حدود 50 تا 90 ms برای هر ۳ دسته است. مناسب برای پنلهای داشبورد.
مدیریت خطا
خطاهای دیتابیس یا ساختاری با catch(Exception) بازگردانده میشوند با بدنه شامل message و trace.
اثرات جانبی
درخواست فقط خواندن دارد، جدولها تغییری نمیکنند.
ردپای حسابرسی
ثبت لاگ ندارد؛ پیشنهاد افزودن لاگ در عملیات تایید و رد آینده.
پیشنهاد بهبود
- جداسازی فیلترهای سطح دسترسی به Trait مشترک برای کنترل خوانایی.
- کاهش حجم کوئری با projection محدود و lazy load اپراتورها.
جمعبندی
روت اصلی کارتابل برای دریافت کلیه درخواستهای مرخصی و تردد بسته به نقش اپراتور است. طراحی منطقی، اما حجم کوئری زیاد دارد که در نسخههای بعدی باید بهینهسازی شود.