#P1545
POST /personnel/document
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /personnel/document | OfficialController@personnelDocument | authWithJwt | مدیریت مستندات و فایلهای مرتبط با پرسنل (رزومه، قرارداد، مدارک هویتی, سوابق) |
منطق عملکرد تابع
تابع personnelDocument بهمنظور ثبت، بهروزرسانی یا واکشی مستندات پرسنلی طراحی شده است. بسته به نوع ورودی (action)، عملیات متفاوتی انجام میدهد:
- پارامتر
actionرا بررسی میکند (create, update, delete, list). - در صورت
list، با join به جدولpersonnel_documents، دادههای مربوط بهperson_idرا واکشی میکند. - در صورت
create، فایل جدید را در مسیر تعریفشده ذخیره و رکورد دیتابیس ثبت میشود. - در حالت
update، متادیتای فایل (نوع، عنوان، تاریخ انقضا) بهروزرسانی میشود. - در حالت
delete، فایل فیزیکی و رکوردش از دیتابیس حذف میگردد. - در همه حالات، پاسخ JSON استاندارد با وضعیت و جزئیات بازگردانده میشود.
پارامترهای ورودی
| نام | محل | نوع | الزامی | توضیح |
| id | Body | integer | بله | شناسه پرسنل |
| action | Body | string | بله | نوع عملیات (create, update, delete, list) |
| file | Body(form-data) | file | در create/update | فایل مستند بارگذاریشده (PDF، JPG، …) |
| title | Body | string | خیر | عنوان مستند برای UI |
| expire_date | Body | string | خیر | تاریخ انقضا (اختیاری برای مدارک زماندار) |
ساختار خروجی
{
"status": true,
"time": 1732365700,
"data": [
{
"id": 44,
"title": "کارت ملی",
"file_url": "https://api.domain.ir/storage/personnel/44_national_card.pdf",
"expire_date": "1405/12/20",
"created_at": "1404/02/18"
}
]
}
در صورت خطا:
{
"status": false,
"time": 1732365700,
"code": 1003,
"message": "خطا در ذخیره فایل یا عدم دسترسی."
}
نکات امنیتی
- تمام درخواستها باید توسط کاربران احرازشده (JWT معتبر) ارسال شود.
- احراز شعبه و مالکیت فایل قبل از حذف یا تغییر.
- تشخیص MIME-type واقعی فایلها برای جلوگیری از بارگذاری اسکریپت مخرب.
عملکرد
- بارگذاری فایل با استفاده از Disk Driver (Local/AWS S3) طبق تنظیمات config/filesystems.php.
- مدیریت حجم فایل با حد ۲۵ مگابایت و زمان پاسخ < 150 ms برای لیست.
Dependencies
- Illuminate\Support\Facades\Storage
- Illuminate\Support\Facades\DB
- Carbon\Carbon
کدهای خطا
| کد | شرح | منبع |
| 400 | ورودی نامعتبر یا فایل یافت نشد | Validation |
| 403 | عدم مجوز برای عملیات در فایل | Access Control |
| 500 | خطای سرور یا فایلسیستم | Storage service |
پیشنهادهای امنیتی
- رمزگذاری نام فایلهای ذخیرهشده.
- افزودن ماژول اسکن ویروس برای فایلهای جدید.
پیشنهادهای توسعهای
- اجازه دسترسی نسخه Preview در مرورگر برای PDF و تصویر.
- قابلیت جستجو بین عناوین مستندات.
ممیزی و ثبت وقایع
- ثبت هر عملیات create/update/delete با شناسه کاربر و IP.
- ذخیره مسیر فایل و زمان دقیق در جدول
audit_document_logs.
جمعبندی
personnelDocument بهصورت یک ماژول مستقل برای بارگذاری و مدیریت مستندات پرسنلی عمل میکند و پایهگذار سیستم مدیریت فایل یکپارچه در بخش HR است.