#P1489
POST /credit-debit/list
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/credit-debit/list |
V2CreditDebitController@creditDebitList |
authWithJwt |
دریافت فهرست تراکنشهای بدهکار و بستانکار با جزئیات صفحهبندی و فیلتر پیشرفته. |
منطق عملکرد تابع
تابع creditDebitList دادهها را از جدول تراکنشها (Pay یا Ledger) بر اساس شعبه کاربر و پارامترهای ورودی صفحهبندی واکشی میکند. ابتدا داده $request->json دیکد میشود، سپس مقادیر start و length برای صفحهبندی تنظیم میشود. بعد از اجرای کوئری، نتایج در آرایه نهایی با کلیدهای draw، recordsTotal، recordsFiltered و data بازگردانده میشود.
ورودیها
| نام پارامتر |
نوع |
منبع |
الزامی |
توضیح |
| json |
string (JSON) |
Body |
بله |
شامل تنظیمات صفحهبندی و فیلترهای جستجو. |
| branch |
integer |
JWT/Header |
بله |
شناسه شعبه برای فیلتر تراکنشها. |
| draw |
integer |
Body→JSON |
خیر |
شماره درخواست برای DataTables. |
| length |
integer |
Body→JSON |
بله |
تعداد ردیف در هر صفحه. |
| start |
integer |
Body→JSON |
خیر |
شاخص شروع ایتمها (offset). |
خروجی (Response)
{
"draw": 2,
"recordsTotal": 120,
"recordsFiltered": 20,
"data": [
{
"serial_id": 112,
"system_serial": 5143,
"type": "receive",
"description": "دریافت از فروشنده",
"amount": 750000,
"date": "2025/10/20",
"status": "completed"
}
]
}
نکات امنیتی
- احراز JWT الزامی است.
- اطلاعات فقط برای همان شعبه کاربر قابلنمایش است.
- فیلدهای حساس (مثل شماره حساب) از خروجی حذف میشوند.
نکات عملکردی
- استفاده از
paginate() برای بهینهسازی صفحهبندی.
- پیشنهاد: کش Redis برای Queryهای پرتکرار (TTL=600s).
- در حالت فیلتر سنگین، توصیه به افزودن ایندکس بر
branch, date, type.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Exception;
- use Carbon\Carbon;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 400 |
ورودی JSON نامعتبر یا پارامتر ناقص. |
json_decode() |
| 500 |
خطا در واکشی داده از پایگاه داده. |
DB Query |
پیشنهادهای امنیتی
- افزودن کنترل نقش: فقط کاربر دارای دسترسی
can('view_creditdebit').
- اعمال Rate Limiting بر اساس IP.
پیشنهادهای بهبود
- افزودن پارامتر
sort_by برای مرتبسازی پویا.
- افزودن فیلد فیلتر بر اساس وضعیت تراکنش (در انتظار/انجامشده).
- نمایش کلاس CSS وضعیت (error/success) در پاسخ.
ممیزی و لاگها
- نوع لاگ پیشنهادی:
ReadCreditDebitList.
- فیلدها:
operator_id، branch، filters.
- سطح لاگ: Info.
جمعبندی
این مسیر برای واکشی فهرست بدهکار/بستانکار طراحی شده است. با احراز JWT و صفحهبندی ایمن امکان فیلتر تطبیقی دارد. در نسخه بعدی افزودن پارامترهای مرتبسازی و کش توصیه میشود.
