#P1503
POST /announcement/list/company
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/announcement/list/company |
V2CreditDebitController@listAnnouncementCompany |
authWithJwt |
لیست اعلانهای مالی تجمیعی در سطح شرکت (تمام شعب)، با فیلتر DataTables و فیلتر پیشرفته برای گزارشات مدیریتی. |
منطق عملکرد تابع
تابع listAnnouncementCompany مشابه تابع listAnnouncement عمل میکند اما دامنهٔ دادهها را به تمام شعب وابسته به شرکت (یا کل سازمان) گسترش میدهد. هدف، گزارشگیری یکپارچه از کلیه اعلانهای مالی است. دادهها از جدول announcements بازیابی میشوند و با فیلترهای DataTables و جستجوی پیشرفته محدود میگردند. خروجی، شامل متادیتای DataTables (draw، تعداد کل، زمان درخواست) و آرایهای از اعلانهاست.
ورودیها
| نام پارامتر |
نوع |
منبع |
الزامی |
توضیح |
| draw |
integer |
Body |
بله |
برای همزمانسازی DataTables. |
| start |
integer |
Body |
بله |
نقطه شروع رکوردها. |
| length |
integer |
Body |
بله |
تعداد رکوردها در هر صفحه. |
| advanced |
object |
Body |
خیر |
فیلترهای ترکیبی مدیریت، از جمله نوع، تاریخ، وضعیت و شعبهٔ خاص. |
| company |
integer |
JWT/Header |
بله |
شناسه شرکت مادر برای واکشی اعلانهای کل. |
خروجی (Response)
{
"status": true,
"meta": {
"draw": 1,
"recordsTotal": 842,
"recordsFiltered": 842,
"timestamp": 1732287600
},
"data": [
{
"id": 1220,
"type": "receive",
"reference": "branch_3/pay/554",
"branch": 3,
"company": 1,
"status": "done",
"title": "دریافت وجه نقد از شعبه مرکزی",
"created_at": "2025-10-09 09:44:31"
}
]
}
نکات امنیتی
- احراز JWT الزامی است.
- کاربر باید به نقش سطح شرکت
financial.company.announcement.view مجهز باشد.
- فیلتر خودکار دادهها بر اساس
company از توکن JWT انجام میشود تا از نشت اطلاعات بین شرکتها جلوگیری گردد.
نکات عملکردی
- بهینهسازی Query با ایندکس روی فیلدهای
(company, type, created_at).
- استفاده از کش Redis با TTL=300 s برای پاسخهای صفحه اول (draw=1).
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Helpers\Functions;
- use Carbon\Carbon;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 400 |
ورودی ناقص یا نامعتبر DataTables. |
Validator |
| 403 |
کاربر فاقد سطح دسترسی سازمانی. |
Auth Middleware |
| 500 |
مشکل در واکشی دادهها یا کش Redis. |
Exception Handler |
پیشنهادهای امنیتی
- رمزنگاری کلید مرجع (reference) در پاسخ API.
- ثبت IP و شناسه کاربری در جدول audit_logs برای هر درخواست لیست.
پیشنهادهای بهبود
- افزودن پارامتر
export برای خروجی CSV/Excel.
- پیادهسازی Lazy Loading برای فیلدهای حجیم (description).
- قابلیت گروهبندی بر اساس شعبه یا وضعیت.
ممیزی و لاگها
- نوع ممیزی:
ListAnnouncementCompany.
- ثبت شامل company، filters، timestamp و user_id.
- سطح حساسیت: Info.
جمعبندی
تابع listAnnouncementCompany ابزار اصلی مدیران مالی برای مشاهده اعلانهای کلان بینشعبهای است و با ساختار صفحهبندیشده و کش Redis، کارایی بالایی در محیطهای چندشعبهای دارد.
