# POST /announcement/statement

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

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

تابع **statementAnnouncement** با هدف تهیهٔ بیانیهٔ تجمیعی از اعلان‌های مالی (پرداخت، دریافت، چک، و اعلان مرتبط) طراحی شده است. این تابع معمولاً بعد از اجرای عملیات `listAnnouncement` یا `updateAnnouncement` برای استخراج گزارش دقیق جریان‌های مالی استفاده می‌شود.

مقدارهای ورودی شامل تاریخ شروع، تاریخ پایان، نوع اعلان، و شناسه شعبه هستند. تابع با استفاده از `DB::table('announcements')` داده‌ها را واکشی کرده و نسبت به `object_type` (مانند pay, check, cost) عملیات Grouping انجام می‌دهد. سپس مجموع‌ها (balance, debit, credit) محاسبه و ساختار JSON خروجی بازگردانده می‌شود.

<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>type</td><td>string</td><td>Body</td><td>خیر</td><td>در صورت ارسال، فقط بیانیه نوع خاص (pay, check, cost) بازگردانده می‌شود.</td></tr><tr><td>currency</td><td>string</td><td>Body</td><td>خیر</td><td>واحد ارزی (تومان، دلار، یورو، ...).</td></tr></tbody></table>

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

```
{
  "status": true,
  "statement": {
    "branch": 3,
    "from": "1404-09-01",
    "to": "1404-09-23",
    "currency": "IRR",
    "summary": {
      "total_credit": 71250000,
      "total_debit": 53320000,
      "balance": 17930000
    },
    "details": [
      {
        "id": 114,
        "type": "pay",
        "object_type": "check",
        "description": "پرداخت چک بابت اجاره دفتر",
        "amount": 5200000,
        "created_at": "1404-09-12",
        "status": "paid"
      },
      {
        "id": 115,
        "type": "receive",
        "object_type": "cash",
        "description": "دریافت پیش پرداخت از مشتری A",
        "amount": 10500000,
        "created_at": "1404-09-15",
        "status": "done"
      }
    ]
  }
}
```

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

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

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

<div id="bkmrk-%D8%A7%D8%B3%D8%AA%D9%81%D8%A7%D8%AF%D9%87-%D8%A7%D8%B2-%DA%A9%D9%88%D8%A6%D8%B1%DB%8C%E2%80%8C%D9%87%D8%A7%DB%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- استفاده از کوئری‌های تجمیعی (aggregate) برای بهبود سرعت گزارش.
- در صورت وجود کش، نتایج تا ۳۰۰ ثانیه در Redis نگهداری می‌شوند.
- میانگین زمان اجرا: ~120ms (بدون کش).

</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-%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>ورودی‌های زمانی یا نوع اعلان نادرست است.</td><td>Validator</td></tr><tr><td>403</td><td>کاربر مجاز به مشاهده‌ی بیانیه شعبه نیست.</td><td>Auth Middleware</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%AA%D8%BA%DB%8C%DB%8C%D8%B1-%D8%B3%D8%A7%D8%AE%D8%AA%D8%A7%D8%B1-%D8%AE%D8%B1%D9%88%D8%AC%DB%8C-%D8%AF" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- تغییر ساختار خروجی در نقش‌های سطح پایین برای کاهش نشت داده مالی.
- ثبت ممیزی `view_statement` با تاریخ و IP کاربر.

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-group" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن پارامتر `group_by` با گزینه‌های (day, week, month).
- افزودن خروجی PDF و Excel برای دانلود سریع بیانیه.

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

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

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

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

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