#P1490
POST /credit-debit/summary
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/credit-debit/summary |
V2CreditDebitController@summary |
authWithJwt |
بازیابی خلاصه مالی تراکنشهای بدهکار و بستانکار (Credit/Debit) مربوط به همکار یا مرجع مشخص. |
منطق عملکرد تابع
تابع summary برای ارائه یک گزارش کلی از وضعیت مالی کاربر، همکار یا مرجع طراحی شده است. فرآیند به این صورت است که ابتدا نوع موجودیت (typeDb) و شناسه شناسایی (company یا reference) تعیین میشود. سپس با استفاده از متدهای StaticController::getFinancialPasts()، دادههای سال مالی جاری و دورههای باز و بسته جمعآوری شده، بدهی و بستانکاری کل محاسبه و بازگردانده میشوند.
ورودیها
| نام پارامتر |
نوع |
منبع |
الزامی |
توضیح |
| json |
string (JSON) |
Body |
بله |
حاوی تنظیمات فیلتر و دوره زمانی مالی. |
| branch |
integer |
Header/JWT |
بله |
شناسه شعبه مبدا برای محدودسازی دادهها. |
| advanced.from |
string (YYYY/MM/DD) |
Body→JSON |
خیر |
تاریخ شروع دوره مورد بررسی. |
| advanced.fpopen |
boolean |
Body→JSON |
خیر |
اگر false باشد فقط دوره بسته را بررسی میکند. |
| type |
string |
Body→JSON |
خیر |
نوع حساب (colleague, reference, aggregation). |
| company |
integer |
Body→JSON |
بله |
شناسه مرجع همکار. |
خروجی (Response)
{
"status": true,
"meta": {
"timestamp": 1732287600
},
"summary": {
"total_credit": 12500000,
"total_debit": 8400000,
"opening_balance": 3100000,
"closing_balance": 4100000
}
}
نکات امنیتی
- تمامی درخواستها باید با احراز JWT معتبر ارسال شوند.
- دسترسی فقط برای کاربران دارای نقش مدیریتی یا مالی مجاز است.
- مقادیر مالی واقعی (credit/debit) نباید در لاگ عمومی ثبت شوند.
نکات عملکردی
- فراخوانی توابع مالی پرهزینه (
getFinancialPasts) بهتر است با کش Redis ذخیره شوند.
- محاسبه سال مالی به صورت
StaticController::getYearFinancial() صورت میگیرد و باید فقط یکبار در هر درخواست اجرا شود.
- در صورت حجم زیاد تراکنشها، پیشنهاد میشود فیلدهای aggregate در جدول جداگانه نگهداری شوند.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Morilog\Jalali\Jalalian;
- use Carbon\Carbon;
- use App\Http\Controllers\StaticController;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 400 |
ورودی JSON ناقص یا فرمت اشتباه در دوره مالی. |
json_decode() |
| 404 |
داده مالی یا شناسه همکار یافت نشد. |
DB Query |
| 500 |
خطا در محاسبه مجموع بدهی/بستانکاری. |
getFinancialPasts() |
پیشنهادهای امنیتی
- اعمال اعتبارسنجی نقش قبل از فراخوانی تابع اصلی.
- بررسی شناسه شعبه با دادههای JWT برای جلوگیری از تزریق Cross-Branch.
- حذف دادههای تراکنش خام قبل از پاسخ خروجی.
پیشنهادهای بهبود
- افزودن پارامتر انتخاب بازه دلخواه تاریخ بهجای سال مالی ثابت.
- نمایش فیلد
net_balance (credit-debit) در پاسخ برای استفاده سریع.
- افزودن پشتیبانی برای واحد پولی غیر IRR (مثلاً USD).
ممیزی و لاگها
- نوع لاگ:
ReadFinancialSummary
- فیلدهای گزارششده:
user_id، branch، company، year
- سطح لاگ: Info
- زمانبندی پیشنهادی برای ذخیره لاگ: هر بار تغییر در فیلدهای مالی.
جمعبندی
این مسیر خلاصهای از وضعیت مالی بدهکار و بستانکار را بر اساس دادههای سال مالی و تراکنشهای ثبتشده برمیگرداند. با ترکیب کش Redis، اعتبارسنجی JWT و تفکیک نقش کاربران، عملکرد سریع و امن تضمین میشود.
