#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 و صفحه‌بندی برحسب زمان آخرین مشاهده در نسخهٔ بعدی اضافه گردد.

Revision #1
Created 2025-11-22 13:21:27 UTC by Alireza
Updated 2025-11-22 13:23:14 UTC by Alireza