# POST /api/v2/notif/simple/list

<div id="bkmrk-notif-simple-list" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/v2/notif/simple/list</td><td style="direction: ltr; text-align: left;">V2BaseController@notifySimpleList</td><td style="direction: ltr; text-align: left;">authWithJwt</td><td style="direction: rtl; text-align: right;">واچش اعلان‌های ساده (Simple Notification) کاربر برای نمایش فوری در داشبورد یا موبایل</td></tr></tbody></table>

</div>### منطق عملکرد تابع

<div id="bkmrk-%D8%AA%D8%A7%D8%A8%D8%B9-notifysimplelis" style="direction: rtl; text-align: justify;">تابع **notifySimpleList** با دریافت شناسهٔ شعبه یا اپراتور کاربر، لیست اعلان‌های فعال را از جدول `notifications` واکشی می‌کند و آن‌را به ترتیب نزولی تاریخ مرتب می‌نماید. روند اجرایی اصلی: - دریافت پارامتر `branch` از JWT یا درخواست.
- فیلتر اعلان‌هایی که `status = 1` و نوعشان `simple` است.
- مرتب‌سازی با `orderBy('id','DESC')` برای آخرین اعلان‌ها.
- بازگرداندان خروجی در قالب JSON شامل متادیتا (timestamp).

</div>### ورودی‌ها (Request Fields)

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%A7%D9%84" style="direction: rtl; text-align: justify;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام فیلد</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>branch</td><td>integer</td><td>بله</td><td>شناسه شعبهٔ کاربر برای فیلتر اعلان‌ها</td></tr><tr><td>limit</td><td>integer</td><td>خیر</td><td>تعداد رکوردهای قابل نمایش در پاسخ (پیش‌فرض ۱۰)</td></tr><tr><td>search</td><td>string</td><td>خیر</td><td>عبارت جستجوی جزئی در عنوان یا متن اعلان</td></tr></tbody></table>

</div>### خروجی (Response)

<table border="1" cellpadding="6" id="bkmrk-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD-" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>فیلد</td><td>نوع داده</td><td>توضیح</td></tr><tr><td>status</td><td>boolean</td><td>وضعیت نهایی پاسخ</td></tr><tr><td>meta.timestamp</td><td>integer</td><td>زمان واکنش سرور (Unix)</td></tr><tr><td>data\[\]</td><td>array</td><td>آرایه‌ای از اعلان‌ها</td></tr><tr><td>data\[\].title</td><td>string</td><td>عنوان اعلان</td></tr><tr><td>data\[\].content</td><td>string</td><td>متن کامل اعلان</td></tr><tr><td>data\[\].created\_at</td><td>datetime</td><td>تاریخ ایجاد اعلان</td></tr></tbody></table>

#### نمونه پاسخ:

```
{
  "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

<table border="1" cellpadding="6" id="bkmrk-%DA%A9%D8%AF-%D8%AE%D8%B7%D8%A7-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-" style="margin: 15px auto; width: 90%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد خطا</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>Database یا Query Exception</td><td>notifySimpleList</td></tr><tr><td>1006</td><td>JWT نامعتبر یا منقضی شده</td><td>authWithJwt</td></tr><tr><td>404</td><td>عدم یافتن اعلان برای branch</td><td>Query Result</td></tr></tbody></table>

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

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

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

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

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

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

### جمع‌بندی

<div id="bkmrk-endpoint-post-%2Fnotif" style="direction: rtl; text-align: justify;">Endpoint **POST /notif/simple/list** یکی از مسیرهای کلیدی مدیریتی برای رساندن اعلان‌های سریع به کاربران است. ساختار ساده و بدون Cache باعث افزایش بار در تکرار درخواست‌ها شده و نبود Audit باعث فقدان ردپای ثبت‌شدهٔ امنیتی است. توصیه می‌شود Redis و صفحه‌بندی برحسب زمان آخرین مشاهده در نسخهٔ بعدی اضافه گردد.</div>