#P1508
POST /announcement/statement
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/statement | V2CreditDebitController@statementAnnouncement | authWithJwt | تولید و ارائهٔ گزارش بیانیه (Statement) مالی برای اعلانهای فعال در بازهٔ مورد درخواست کاربر. |
منطق عملکرد تابع
تابع statementAnnouncement با هدف تهیهٔ بیانیهٔ تجمیعی از اعلانهای مالی (پرداخت، دریافت، چک، و اعلان مرتبط) طراحی شده است. این تابع معمولاً بعد از اجرای عملیات listAnnouncement یا updateAnnouncement برای استخراج گزارش دقیق جریانهای مالی استفاده میشود.
مقدارهای ورودی شامل تاریخ شروع، تاریخ پایان، نوع اعلان، و شناسه شعبه هستند. تابع با استفاده از DB::table('announcements') دادهها را واکشی کرده و نسبت به object_type (مانند pay, check, cost) عملیات Grouping انجام میدهد. سپس مجموعها (balance, debit, credit) محاسبه و ساختار JSON خروجی بازگردانده میشود.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| from | string (Y-m-d) | Body | خیر | تاریخ شروع بازه گزارش. |
| to | string (Y-m-d) | Body | خیر | تاریخ پایان بازه گزارش. |
| branch | integer | JWT/Header | بله | شناسه شعبه کاربر برای فیلتر گزارش. |
| type | string | Body | خیر | در صورت ارسال، فقط بیانیه نوع خاص (pay, check, cost) بازگردانده میشود. |
| currency | string | Body | خیر | واحد ارزی (تومان، دلار، یورو، ...). |
خروجی (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"
}
]
}
}
نکات امنیتی
- JWT الزامی است.
- نقش الزامی:
financial.announcement.viewیا بالاتر. - اطلاعات فقط برای
branchکاربر جاری باز میگردد.
نکات عملکردی
- استفاده از کوئریهای تجمیعی (aggregate) برای بهبود سرعت گزارش.
- در صورت وجود کش، نتایج تا ۳۰۰ ثانیه در Redis نگهداری میشوند.
- میانگین زمان اجرا: ~120ms (بدون کش).
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Morilog\Jalali\Jalalian;
- use App\Helpers\Functions;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | ورودیهای زمانی یا نوع اعلان نادرست است. | Validator |
| 403 | کاربر مجاز به مشاهدهی بیانیه شعبه نیست. | Auth Middleware |
| 404 | دادهای در بازهٔ زمانی موردنظر یافت نشد. | Query |
| 500 | خطای داخلی سرور در پردازش تجمیعی. | Exception |
پیشنهادهای امنیتی
- تغییر ساختار خروجی در نقشهای سطح پایین برای کاهش نشت داده مالی.
- ثبت ممیزی
view_statementبا تاریخ و IP کاربر.
پیشنهادهای بهبود
- افزودن پارامتر
group_byبا گزینههای (day, week, month). - افزودن خروجی PDF و Excel برای دانلود سریع بیانیه.
ممیزی و لاگها
- نوع ممیزی:
StatementAnnouncement. - موارد ثبتشونده: بازهٔ زمانی، operator، branch.
- سطح حساسیت: Audit.
جمعبندی
تابع statementAnnouncement ستون اصلی گزارشگیری تجمیعی اعلانهاست که خروجی استاندارد و قالببندیشدهای برای واحد مالی فراهم میکند. با سطح دسترسی Audit، نقش مدیریتی میتواند کل جریانهای مالی شعبه را در یک بازهٔ زمانی مرور کند.