#P1544
POST /personnel/bill
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/personnel/bill |
OfficialController@personnelBill |
authWithJwt |
بازیابی و نمایش صورتحساب مالی پرسنل با جزییات اسناد و مانده |
منطق عملکرد تابع
این متد بر اساس شناسه پرسنل دادهشده، تمام تراکنشهای مالی مرتبط (دریافت، پرداخت، اسناد دستی، افتتاحیه/اختتامیه) را واکشی میکند، آنها را بر اساس تاریخ مرتب مینماید و در قالب ساختار صورتحساب یکپارچه بازمیگرداند.
- دریافت پارامترهای جستجو از
$Data->advanced و اعمال فیلتر بازه تاریخ یا شماره سند.
- واخوانی فاکتورهای پرداخت (pay) از جدول
pays با شرایط مربوط به پرسنل (functor/object).
- تشخیص نوع سند: سند عملیات رفرنس، سند کارمزدی، سند دستی، یا عملیات دریافت/پرداخت.
- ساخت آبجکت جزئیات شامل عنوان، نوع سند، مبلغ بدهکار/بستانکار و تشخیص وضعیت (diagnosis).
- مرتبسازی آیتمها بر اساس زمان.
- افزودن سند افتتاحیه از جدول
financial_pasts اگر موجود بود و شرایط اجازه میداد.
- بازگرداندن پاسخ شامل دادهها، جزئیات شخص، و اطلاعات فیلتر.
پارامترهای ورودی
| نام |
محل |
نوع |
الزامی |
توضیح |
| id |
Body |
integer |
بله |
شناسه پرسنل |
| Data.advanced.from |
Body |
string |
خیر |
تاریخ شروع (YYYY-MM-DD) |
| Data.advanced.to |
Body |
string |
خیر |
تاریخ پایان (YYYY-MM-DD) |
| Data.advanced.r |
Body |
mixed |
خیر |
شماره/سریال سند |
| Data.draw |
Body |
integer |
خیر |
شناسه درخواست برای DataTables |
ساختار خروجی
{
"draw": 1,
"recordsTotal": 100,
"recordsFiltered": 10,
"filtered": {
"from": "2025-05-01",
"to": "2025-06-01"
},
"details": {
"id": 23,
"first_name": "مریم",
"last_name": "اکبری",
"branch": "اصفهان"
},
"data": [
{
"serial_id": "5100",
"system_serial": 23,
"datetime": "1404/02/15 00:00:00",
"details": {
"title": {
"html": "سند افتتاحیه",
"text": "سند افتتاحیه"
},
"type": {
"subject": "financial_past",
"title": "افتتاحیه"
}
},
"credit": 2000000,
"debit": 0,
"diagnosis": "creditor"
}
]
}
نکات امنیتی
- دسترسی فقط برای کاربران احراز شده با JWT.
- اطمینان از اینکه
id درخواستشده متعلق به پرسنل مجاز است.
عملکرد
- چندین کوئری به جداول pays، manual_documents، financial_pasts با ایندکس مناسب.
- مرتبسازی آرایهها در PHP — بهینهسازی با usort.
Dependencies
- Illuminate\Support\Facades\DB
- Carbon\Carbon
- Morilog\Jalali\Jalalian
کدهای خطا
| کد |
شرح |
منبع |
| 404 |
پرسنل یافت نشد |
DB query |
| 500 |
خطای داخلی دیتابیس/پردازش |
Exception Handler |
پیشنهادهای امنیتی
- اعتبارسنجی پارامتر
id در سطح سرویس و کنترلر.
- عدم بازگرداندن اطلاعات حساس تراکنشها به کاربران غیرمرتبط.
پیشنهادهای توسعهای
- افزودن قابلیت صفحهبندی نتایج برای درخواستهای بزرگ.
- گزارش PDF خروجی صورتحساب.
ممیزی و ثبت وقایع
- ثبت همه درخواستهای صورتحساب در جدول audit با شناسه کاربر و زمان درخواست.
جمعبندی
personnelBill امکان مشاهده جامع تاریخچه مالی پرسنل را فراهم میکند و دادهها را در قالب ساختار سندی استاندارد بازمیگرداند.
