#P1509
POST /announcement/ledger
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/ledger | V2CreditDebitController@ledgerAnnouncement | authWithJwt | ارائه دفترکل اعلانها (Ledger) بر اساس فیلتر حساب، شعبه و بازهٔ زمانی. |
منطق عملکرد تابع
تابع ledgerAnnouncement برای استخراج دفترکل اعلانهای مالی به کار میرود. دادهها بر اساس شناسهٔ شعبه، بازهٔ زمانی، نوع اعلان و موجودی حساب طبقهبندی میشوند.
این تابع از همان ساختار underlying جدولهای announcements، pays و checks استفاده میکند و پس از پردازش، خروجی را بهصورت مرتبشده بر اساس تاریخ و حساب ارائه میدهد. همچنین امکان گروهبندی بر پایهٔ حساب معین (moeen_id) یا نوع عملیات فراهم است.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| from | string (Y-m-d) | Body | خیر | تاریخ شروع دفترکل. |
| to | string (Y-m-d) | Body | خیر | تاریخ پایان دفترکل. |
| branch | integer | JWT/Header | بله | شعبهٔ درخواست دهنده. |
| moeen_id | integer | Body | خیر | در صورت ارسال، فقط عملیات مربوط به حساب معین خاص. |
| group_by | string | Body | خیر | نحوه گروهبندی (day، type، account). |
| currency | string | Body | خیر | واحد ارزی فیلتر گزارش. |
خروجی (Response)
{
"status": true,
"branch": 3,
"group_by": "day",
"from": "1404-09-01",
"to": "1404-09-23",
"ledger": [
{
"date": "1404-09-01",
"debit": 2000000,
"credit": 0,
"balance": -2000000,
"description": "پرداخت به تامینکننده کالا",
"account": "110102 حساب پرداختها"
},
{
"date": "1404-09-05",
"debit": 0,
"credit": 4500000,
"balance": 2500000,
"description": "دریافت نقدی از مشتری",
"account": "110101 صندوق نقدی"
}
],
"summary": {
"total_debit": 2000000,
"total_credit": 4500000,
"final_balance": 2500000
}
}
نکات امنیتی
- توکن JWT الزامی است.
- نقش مورد نیاز:
financial.ledger.view. - اجازهٔ دسترسی فقط به اعلانهای همان شعبه.
نکات عملکردی
- گزارش تجمیعی با استفاده از
GROUP BYدر SQL. - امکان Cache Redis تا 300 ثانیه برای کاهش فشار گزارشهای تکراری.
- میانگین زمان اجرا: ۹۰ تا ۱۴۰ میلیثانیه.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Morilog\Jalali\Jalalian;
- use App\Helpers\Functions;
کدهای خطا
| کد | شرح | منبع |
| 400 | تاریخ یا پارامتر گزارش ارسال نشده است. | Validator |
| 403 | کاربر اجازه مشاهده دفترکل این شعبه را ندارد. | RBAC |
| 404 | هیچ تراکنشی در بازهٔ مورد نظر پیدا نشد. | Query |
| 500 | خطای داخلی سرور. | Exception |
پیشنهادهای امنیتی
- ثبت تاریخ و IP کاربر مشاهدهکننده گزارش در ممیزی.
- محافظت خروجی با masking در اطلاعات حساس (مثلاً شماره حساب).
پیشنهادهای بهبود
- افزودن حالت real-time refresh برای Dynamic Ledger UI.
- پشتیبانی از خروجی CSV یا Excel.
- امکان فیلتر چندحسابی (multi-account ledger) در نسخه ۲.۱.
ممیزی و لاگها
- نوع ممیزی:
LedgerAnnouncement. - ثبت: branch، operator، بازه، نوع گروهبندی.
- سطح حساسیت: Audit.
جمعبندی
تابع ledgerAnnouncement ستون اصلی گزارشگیری تحلیلی دفترکل در ماژول مالی است. این تابع بر پایه دادههای اعلان، جریانهای وام، پرداخت و دریافتی را تجمیع کرده و با سیستم کَش تلفیقشده، سرعت بالا و داده دقیق برای حسابداران فراهم میکند.