#P1541
POST /personnel/attendance
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/personnel/attendance |
OfficialController@attendancePersonnelStore |
authWithJwt |
ثبت حضور و غیاب روزانهی پرسنل یا اصلاح رکوردهای ثبتشده |
منطق عملکرد تابع
تابع attendancePersonnelStore برای ثبت یا بهروزرسانی سوابق حضور و غیاب پرسنل استفاده میشود. ورودی شامل شناسهی پرسنل، بازهی تاریخ، وضعیت کاری، و نوع حضور است. در حالت کلی:
- دریافت پارامترهای ارسالی از درخواست و بررسی وجود کاربر هدف در جدول
personnel.
- در صورت ثبت اولیه، رکورد جدیدی در جدول
personnel_attendance با تاریخ روز و ساعت فعلی درج میشود.
- در حالت ویرایش، دادهی موجود با اطلاعات جدید (مانند ساعت ورود/خروج) بهروزرسانی میشود.
- در صورت ارسال وضعیت مرخصی یا تعطیلی، رکورد در جدول مجزای
personnel_permissions ثبت میگردد.
- در انتها خروجی شامل وضعیت عملیات و شناسهی رکورد مربوطه بازگردانده میشود.
پارامترهای ورودی
| نام |
محل |
نوع |
الزامی |
توضیح |
| personnel_id |
Body |
integer |
بله |
شناسهی پرسنل |
| date |
Body |
string (YYYY-MM-DD) |
بله |
تاریخ حضور (بهصورت شمسی یا میلادی مطابق تنظیم سیستم) |
| status |
Body |
string |
بله |
نوع وضعیت: present، absent، leave، یا holiday |
| clock_in |
Body |
string (HH:MM) |
خیر |
ساعت ورود |
| clock_out |
Body |
string (HH:MM) |
خیر |
ساعت خروج |
| description |
Body |
string |
خیر |
توضیحات تکمیلی |
ساختار خروجی
{
"status": true,
"time": 1732365532,
"data": {
"id": 1125,
"personnel_id": 19,
"date": "1404/08/23",
"status": "present",
"clock_in": "08:04",
"clock_out": null,
"description": "ثبت اتوماتیک حضور"
}
}
نکات امنیتی
- رمزگذاری توکن JWT جهت تأیید دسترسی به اطلاعات پرسنل.
- کاربران تنها به رکوردهای پرسنل سازمان خود دسترسی دارند (بر اساس فیلد
branch_id).
- ثبت یا تغییر داده نیازمند نقش HR یا Manager است.
عملکرد
- هر عملیات ثبت یا ویرایش تنها یک Query اصلی دارد (INSERT یا UPDATE).
- در صورت فعال بودن Audit Log، یک Query اضافی در جدول
attendance_logs ثبت میشود.
Dependencies
- use Illuminate\Support\Facades\DB;
- use Carbon\Carbon;
- use App\Models\PersonnelAttendance;
کدهای خطا
| کد |
شرح |
منبع |
| 404 |
پرسنل یافت نشد |
Validation |
| 422 |
تاریخ یا وضعیت نامعتبر است |
Validation |
| 401 |
توکن احراز هویت منقضی شده |
AuthWithJwt |
| 500 |
اشکال در ثبت رکورد در دیتابیس |
DB Transaction |
پیشنهادهای امنیتی
- افزودن Rate Limit برای درخواستهای ثبت اتوماتیک (مثلاً کارت یا RFID).
- ولیدیت فیلد تاریخ در سمت سرور بر اساس Time Zone دستگاه.
- ثبت IP و کلید دستگاه ثبتکننده (در بازههای KPI).
پیشنهادهای توسعهای
- افزودن Endpoint مجزا برای ثبت گروهی (برای واحد منابع انسانی).
- محاسبه اتومات تاخیرات و اضافهکاری در همین متد در نسخههای بعدی.
- افزودن سیستم Cross‑Validation بین شیفت کاری و رکورد حضور.
ممیزی و ثبت وقایع
- هر تغییر در رکورد حضور در جدول
attendance_logs ذخیره میشود با فیلدهای:
personnel_idaction (ثبت، ویرایش، حذف)user_id اپراتورtimestamp
جمعبندی
attendancePersonnelStore وظیفهی ثبت و بهروزرسانی سوابق روزانه حضور کارکنان را با سطح دسترسی کنترلشده بر عهده دارد. این مسیر پایهی زیرساخت KPI و محاسبات حقوق و دستمزد پرسنل محسوب میشود.
