#P1501
POST /accounting/balance
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/accounting/balance | V2CreditDebitController@accountingBalance | authWithJwt | دریافت موجودی لحظهای حسابها (بانکی، صندوق) و محاسبه تراز مالی شعبه. |
منطق عملکرد تابع
تابع accountingBalance موجودی حسابهای ثبتشده در سیستم را بر اساس branch یا سایر فیلترهای مشخص شده واکشی میکند. دادهها شامل جمع موجودی نقدی، جمع موجودی بانکی، مجموع چکهای در جریان و تراز کلی سیستم است.
برای افزایش کارایی، دادهها ممکن است از کش Redis خوانده شوند. در صورت عدم وجود یا انقضای کش، اطلاعات از دیتابیس واکشی و مجدد کشگذاری میشود.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| branch | integer | JWT/Header | بله | شناسه شعبه برای محاسبه موجودی. |
| filters | object | Body | خیر | فیلترهای مانند نوع حساب یا بازه تاریخ تراکنشها. |
| goal | string | Body | خیر | هدف نمایش دادهها (مثلاً گزارش یا داشبورد). |
خروجی (Response)
{
"status": true,
"time": 1732287600,
"result": {
"cash_total": 15200000,
"bank_total": 94500000,
"checks_in_flow": 32000000,
"overall_balance": 141700000
}
}
نکات امنیتی
- نیاز به احراز هویت JWT.
- نقش مجاز:
financial.balance.view. - بررسی تعلق شعبه به کاربر احراز شده.
نکات عملکردی
- کش Redis با TTL پیشفرض 600 ثانیه.
- محاسبات مجموع موجودی با استفاده از ایندکس روی ستونهای
account_typeوbranch. - استفاده از SELECT SUM برای تجمیع سریع دادهها.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Helpers\Functions;
- use Carbon\Carbon;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | پارامتر branch نامعتبر. | Validator |
| 403 | عدم دسترسی به موجودی شعبه. | Auth Middleware |
| 500 | خطا در واکشی دادهها یا کش Redis. | Exception Handler |
پیشنهادهای امنیتی
- ثبت لاگ درخواست موجودی با IP و شناسه کاربر.
- محدودیت نرخ درخواست (Rate Limit) برای جلوگیری از فشار به سرور.
پیشنهادهای بهبود
- افزودن جزئیات سطح حساب (جزءکل) در خروجی.
- پشتیبانی از فیلتر براساس ارز.
- نمایش تاریخ آخرین بروزرسانی موجودی.
ممیزی و لاگها
- نوع لاگ:
AccountingBalanceView. - ثبت دادهها: branch, filters, timestamp.
- مدت نگهداری: ۳۰ روز.
جمعبندی
تابع accountingBalance ابزاری کلیدی برای گزارشگیری مالی سریع و دقیق شعبه است و با پشتیبانی کش، عملکرد پایداری در محیطهای پرتراکنش ارائه میدهد.