#P1502
POST /announcement/list
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/announcement/list |
V2CreditDebitController@listAnnouncement |
authWithJwt |
دریافت لیست اعلانهای مالی مرتبط با پرداختها، دریافتها و سایر رویدادهای حسابداری سیستم. |
منطق عملکرد تابع
تابع listAnnouncement دادههای مربوط به اعلانهای مالی را از جدول announcements بازیابی میکند. این اعلانها معمولاً شامل ارتباط بین اسناد پرداخت، دریافت، چک یا حوالههای حسابی هستند. دادهها بر اساس فیلترهای DataTables (draw, start, length) و فیلترهای پیشرفته مانند نوع اعلان، وضعیت و تاریخ، استخراج میشوند. سپس خروجی نهایی شامل متای صفحهبندی، زمان سرور و لیست اعلانهای ساختاریافته بازگردانده میشود.
ورودیها
| نام پارامتر |
نوع |
منبع |
الزامی |
توضیح |
| draw |
integer |
Body |
بله |
شناسه شماره درخواست DataTables برای همزمانسازی. |
| start |
integer |
Body |
بله |
ایندکس شروع دادهها. |
| length |
integer |
Body |
بله |
تعداد رکورد در هر صفحه. |
| advanced |
object |
Body |
خیر |
فیلترهای پیشرفته مثل نوع اعلان، وضعیت، تاریخ از و تا. |
| branch |
integer |
JWT/Header |
بله |
شناسه شعبه مرتبط با اعلانها. |
خروجی (Response)
{
"status": true,
"meta": {
"draw": 5,
"recordsTotal": 258,
"recordsFiltered": 258,
"timestamp": 1732287600
},
"data": [
{
"id": 315,
"type": "pay",
"reference_id": 1621,
"branch": 4,
"title": "ثبت پرداخت نقدی",
"status": "done",
"created_at": "2025-10-11 13:45:00"
}
]
}
نکات امنیتی
- نیاز به احراز هویت JWT.
- کاربر فقط اجازه مشاهده اعلانهای مربوط به شعبه خود را دارد.
- نقش لازم:
financial.announcement.view.
نکات عملکردی
- کش Redis بر اساس کلید
announcement:list:{branch} با TTL=600 s برای دادههای بدون فیلتر.
- ایندکس ترکیبی روی ستونهای
(branch,type,status) برای افزایش سرعت واکشی.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Morilog\Jalali\Jalalian;
- use App\Helpers\Functions;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 400 |
ورودی ناقص یا نامعتبر DataTables. |
Validator |
| 403 |
عدم دسترسی به اعلانهای شعبه دیگر. |
Auth Middleware |
| 500 |
خطای داخلی دیتابیس یا کش Redis. |
Exception Handler |
پیشنهادهای امنیتی
- اعمال RBAC دقیق برای کنترل مشاهده و حذف اعلانها.
- رمزنگاری آیدی مرجع پیش از ارسال به کلاینت.
پیشنهادهای بهبود
- افزودن قابلیت جستجوی ترکیبی چند ستونی.
- امکان گروهبندی بر اساس نوع اعلان (
payment، receive، system).
- پشتیبانی از مرتبسازی پویا توسط فرانتاند.
ممیزی و لاگها
- ثبت هر درخواست مشاهده لیست در
audit_logs با نوع ListAnnouncement.
- شامل: شناسه کاربر، شعبه، زمان، فیلترهای اعمال شده.
جمعبندی
مسیر listAnnouncement امکان مدیریت و مرور اعلانهای مالی را بهصورت امن، صفحهبندیشده و کششده فراهم میکند و پایه گزارشگیری داخلی سیستمهای مالی است.
