Skip to main content
#P1468

POST /api/v2/notif/simple/list

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/notif/simple/list V2BaseController@notifySimpleList authWithJwt واچش اعلان‌های ساده (Simple Notification) کاربر برای نمایش فوری در داشبورد یا موبایل

منطق عملکرد تابع

تابع notifySimpleList با دریافت شناسهٔ شعبه یا اپراتور کاربر، لیست اعلان‌های فعال را از جدول notifications واکشی می‌کند و آن‌را به ترتیب نزولی تاریخ مرتب می‌نماید. روند اجرایی اصلی:
  • دریافت پارامتر branch از JWT یا درخواست.
  • فیلتر اعلان‌هایی که status = 1 و نوعشان simple است.
  • مرتب‌سازی با orderBy('id','DESC') برای آخرین اعلان‌ها.
  • بازگرداندان خروجی در قالب JSON شامل متادیتا (timestamp).

ورودی‌ها (Request Fields)

نام فیلد نوع داده الزامی توضیح
branch integer بله شناسه شعبهٔ کاربر برای فیلتر اعلان‌ها
limit integer خیر تعداد رکوردهای قابل نمایش در پاسخ (پیش‌فرض ۱۰)
search string خیر عبارت جستجوی جزئی در عنوان یا متن اعلان

خروجی (Response)

فیلد نوع داده توضیح
status boolean وضعیت نهایی پاسخ
meta.timestamp integer زمان واکنش سرور (Unix)
data[] array آرایه‌ای از اعلان‌ها
data[].title string عنوان اعلان
data[].content string متن کامل اعلان
data[].created_at datetime تاریخ ایجاد اعلان

نمونه پاسخ:

{
  "status": true,
  "meta": {"timestamp": 1732289310},
  "data": [
    {"title": "به‌روزرسانی سامانه", "content": "نسخه جدید سیستم مدیریت کاربران فعال شد.", "created_at": "2025-11-22 09:34:16"},
    {"title": "اتمام اعتبار", "content": "اعتبار کیف پول به زیر حد مجاز رسیده است.", "created_at": "2025-11-21 19:48:00"}
  ]
}

امنیت و کنترل دسترسی

  • فقط کاربران معتبر JWT می‌توانند اعلان‌های شعبهٔ خود را ببینند.
  • عدم وجود محدودسازی بر اساس role؛ کافی‌ست توکن معتبر باشد.
  • جستجوی رشته‌ای بدون escaping می‌تواند زمینهٔ تزریق در LIKE را فراهم کند.

نکات کارایی و سرعت

  • عدم استفاده از Redis باعث واکشی مستقیم از DB در هر بار درخواست می‌شود.
  • پیشنهاد افزودن Cache کوتاه مدت (TTL 60s) برای کاهش Queryهای تکراری.
  • در صورت زیاد بودن اعلان‌ها، از pagination یا LIMIT استفاده شود.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Http\Request;
  • use App\Models\Notification;
  • use App\Helpers\Functions;

کدهای خطا و خروجی‌های Exception

کد خطا شرح منبع
400 Database یا Query Exception notifySimpleList
1006 JWT نامعتبر یا منقضی شده authWithJwt
404 عدم یافتن اعلان برای branch Query Result

پیشنهادهای امنیتی

  • افزودن escaping برای پارامتر search.
  • اعمال محدودیت max-limit برای جلوگیری از overload.
  • جداسازی نقش‌ها برای اعلان‌های اختصاصی شعبه و مدیر کل.

پیشنهادهای بهبود

  • افزودن سیستم دسته‌بندی اعلان‌ها بر اساس نوع (سیستمی، مالی، پشتیبانی).
  • امکان مارک خوانده‌شدن توسط کاربر (read/unread flag).
  • فعال‌سازی لاگ برای ثبت آخرین مشاهدهٔ اعلان توسط هر اپراتور.

ممیزی و لاگ‌ها

  • در حال حاضر هیچ لاگی برای دسترسی به اعلان‌ها ثبت نمی‌شود.
  • پیشنهاد ثبت با SystemLog::dispatch("notifListAccess") برای رصد خطاها.

جمع‌بندی

Endpoint POST /notif/simple/list یکی از مسیرهای کلیدی مدیریتی برای رساندن اعلان‌های سریع به کاربران است. ساختار ساده و بدون Cache باعث افزایش بار در تکرار درخواست‌ها شده و نبود Audit باعث فقدان ردپای ثبت‌شدهٔ امنیتی است. توصیه می‌شود Redis و صفحه‌بندی برحسب زمان آخرین مشاهده در نسخهٔ بعدی اضافه گردد.
Back to top