# POST /accounting/balance

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/accounting/balance</td><td dir="ltr">V2CreditDebitController@accountingBalance</td><td dir="ltr">authWithJwt</td><td dir="rtl">دریافت موجودی لحظه‌ای حساب‌ها (بانکی، صندوق) و محاسبه تراز مالی شعبه.</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **accountingBalance** موجودی حساب‌های ثبت‌شده در سیستم را بر اساس `branch` یا سایر فیلترهای مشخص شده واکشی می‌کند. داده‌ها شامل جمع موجودی نقدی، جمع موجودی بانکی، مجموع چک‌های در جریان و تراز کلی سیستم است.

برای افزایش کارایی، داده‌ها ممکن است از کش Redis خوانده شوند. در صورت عدم وجود یا انقضای کش، اطلاعات از دیتابیس واکشی و مجدد کش‌گذاری می‌شود.

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### ورودی‌ها

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D9%85%D9%86%D8%A8%D8%B9" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 94%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام پارامتر</td><td>نوع</td><td>منبع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شناسه شعبه برای محاسبه موجودی.</td></tr><tr><td>filters</td><td>object</td><td>Body</td><td>خیر</td><td>فیلترهای مانند نوع حساب یا بازه تاریخ تراکنش‌ها.</td></tr><tr><td>goal</td><td>string</td><td>Body</td><td>خیر</td><td>هدف نمایش داده‌ها (مثلاً گزارش یا داشبورد).</td></tr></tbody></table>

</div>### خروجی (Response)

```
{
  "status": true,
  "time": 1732287600,
  "result": {
    "cash_total": 15200000,
    "bank_total": 94500000,
    "checks_in_flow": 32000000,
    "overall_balance": 141700000
  }
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2-%D8%A8%D9%87-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87%D9%88%DB%8C%D8%AA-j" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نیاز به احراز هویت JWT.
- نقش مجاز: `financial.balance.view`.
- بررسی تعلق شعبه به کاربر احراز شده.

</div>### نکات عملکردی

<div id="bkmrk-%DA%A9%D8%B4-redis-%D8%A8%D8%A7-ttl-%D9%BE%DB%8C%D8%B4%E2%80%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- کش Redis با TTL پیش‌فرض 600 ثانیه.
- محاسبات مجموع موجودی با استفاده از ایندکس روی ستون‌های `account_type` و `branch`.
- استفاده از SELECT SUM برای تجمیع سریع داده‌ها.

</div>### وابستگی‌ها

<div id="bkmrk-use-illuminate%5Csuppo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Helpers\\Functions;
- use Carbon\\Carbon;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-400-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>400</td><td>پارامتر branch نامعتبر.</td><td>Validator</td></tr><tr><td>403</td><td>عدم دسترسی به موجودی شعبه.</td><td>Auth Middleware</td></tr><tr><td>500</td><td>خطا در واکشی داده‌ها یا کش Redis.</td><td>Exception Handler</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-%D9%84%D8%A7%DA%AF-%D8%AF%D8%B1%D8%AE%D9%88%D8%A7%D8%B3%D8%AA-%D9%85%D9%88%D8%AC%D9%88" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت لاگ درخواست موجودی با IP و شناسه کاربر.
- محدودیت نرخ درخواست (Rate Limit) برای جلوگیری از فشار به سرور.

</div>### پیشنهادهای بهبود

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%AC%D8%B2%D8%A6%DB%8C%D8%A7%D8%AA-%D8%B3%D8%B7%D8%AD-%D8%AD%D8%B3" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن جزئیات سطح حساب (جزء‌کل) در خروجی.
- پشتیبانی از فیلتر براساس ارز.
- نمایش تاریخ آخرین بروزرسانی موجودی.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF%3A-accountingb" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ: `AccountingBalanceView`.
- ثبت داده‌ها: branch, filters, timestamp.
- مدت نگهداری: ۳۰ روز.

</div>### جمع‌بندی

تابع **accountingBalance** ابزاری کلیدی برای گزارش‌گیری مالی سریع و دقیق شعبه است و با پشتیبانی کش، عملکرد پایداری در محیط‌های پرتراکنش ارائه می‌دهد.

<div id="bkmrk-accounting-balance" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>