# POST /announcement/ledger

<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/announcement/ledger</td><td dir="ltr">V2CreditDebitController@ledgerAnnouncement</td><td dir="ltr">authWithJwt</td><td dir="rtl">ارائه دفترکل اعلان‌ها (Ledger) بر اساس فیلتر حساب، شعبه و بازهٔ زمانی.</td></tr></tbody></table>

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

تابع **ledgerAnnouncement** برای استخراج دفترکل اعلان‌های مالی به کار می‌رود. داده‌ها بر اساس شناسهٔ شعبه، بازهٔ زمانی، نوع اعلان و موجودی حساب طبقه‌بندی می‌شوند.

این تابع از همان ساختار underlying جدول‌های `announcements`، `pays` و `checks` استفاده می‌کند و پس از پردازش، خروجی را به‌صورت مرتب‌شده بر اساس تاریخ و حساب ارائه می‌دهد. همچنین امکان گروه‌بندی بر پایهٔ **حساب معین** (`moeen_id`) یا **نوع عملیات** فراهم است.

<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>from</td><td>string (Y-m-d)</td><td>Body</td><td>خیر</td><td>تاریخ شروع دفترکل.</td></tr><tr><td>to</td><td>string (Y-m-d)</td><td>Body</td><td>خیر</td><td>تاریخ پایان دفترکل.</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شعبهٔ درخواست دهنده.</td></tr><tr><td>moeen\_id</td><td>integer</td><td>Body</td><td>خیر</td><td>در صورت ارسال، فقط عملیات مربوط به حساب معین خاص.</td></tr><tr><td>group\_by</td><td>string</td><td>Body</td><td>خیر</td><td>نحوه گروه‌بندی (day، type، account).</td></tr><tr><td>currency</td><td>string</td><td>Body</td><td>خیر</td><td>واحد ارزی فیلتر گزارش.</td></tr></tbody></table>

</div>### خروجی (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
  }
}
```

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

<div id="bkmrk-%D8%AA%D9%88%DA%A9%D9%86-jwt-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%A7%D8%B3%D8%AA." style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- توکن JWT الزامی است.
- نقش مورد نیاز: `financial.ledger.view`.
- اجازهٔ دسترسی فقط به اعلان‌های همان شعبه.

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

<div id="bkmrk-%DA%AF%D8%B2%D8%A7%D8%B1%D8%B4-%D8%AA%D8%AC%D9%85%DB%8C%D8%B9%DB%8C-%D8%A8%D8%A7-%D8%A7%D8%B3%D8%AA%D9%81" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- گزارش تجمیعی با استفاده از `GROUP BY` در SQL.
- امکان Cache Redis تا 300 ثانیه برای کاهش فشار گزارش‌های تکراری.
- میانگین زمان اجرا: ۹۰ تا ۱۴۰ میلی‌ثانیه.

</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 Morilog\\Jalali\\Jalalian;
- use App\\Helpers\\Functions;

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

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-%D8%AA%D8%A7%D8%B1%DB%8C" 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>تاریخ یا پارامتر گزارش ارسال نشده است.</td><td>Validator</td></tr><tr><td>403</td><td>کاربر اجازه مشاهده دفترکل این شعبه را ندارد.</td><td>RBAC</td></tr><tr><td>404</td><td>هیچ تراکنشی در بازهٔ مورد نظر پیدا نشد.</td><td>Query</td></tr><tr><td>500</td><td>خطای داخلی سرور.</td><td>Exception</td></tr></tbody></table>

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

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-%D8%AA%D8%A7%D8%B1%DB%8C%D8%AE-%D9%88-ip-%DA%A9%D8%A7%D8%B1%D8%A8%D8%B1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت تاریخ و IP کاربر مشاهده‌کننده گزارش در ممیزی.
- محافظت خروجی با masking در اطلاعات حساس (مثلاً شماره حساب).

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%AD%D8%A7%D9%84%D8%AA-real-tim" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن حالت real-time refresh برای Dynamic Ledger UI.
- پشتیبانی از خروجی CSV یا Excel.
- امکان فیلتر چندحسابی (multi-account ledger) در نسخه ۲.۱.

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

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%85%D9%85%DB%8C%D8%B2%DB%8C%3A-ledgerann" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع ممیزی: `LedgerAnnouncement`.
- ثبت: branch، operator، بازه، نوع گروه‌بندی.
- سطح حساسیت: **Audit**.

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

تابع **ledgerAnnouncement** ستون اصلی گزارش‌گیری تحلیلی دفترکل در ماژول مالی است. این تابع بر پایه داده‌های اعلان، جریان‌های وام، پرداخت و دریافتی را تجمیع کرده و با سیستم کَش تلفیق‌شده، سرعت بالا و داده دقیق برای حسابداران فراهم می‌کند.

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