#P1469
POST /api/v2/notif/send
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/notif/send |
V2BaseController@notifySend |
authWithJwt |
ارسال اعلان جدید به کاربران یا اپراتورهای هدف در سیستم Base |
منطق عملکرد تابع
تابع
notifySend ورودیهای اعلان را از درخواست دریافت کرده و با استفاده از مدل
notifications در بانک اطلاعاتی ثبت میکند. منطق تابع به صورت خلاصه:
- دریافت و اعتبارسنجی فیلدهای اجباری (نوع، عنوان، متن، گیرنده).
- ساخت رکورد جدید در جدول
notifications با وضعیت فعال.
- در صورت وجود فیلدهای گروه یا branch، تخصیص آنها.
- بازگرداندن پاسخ موفقیت همراه با timestamp و شناسه اعلان ایجادشده.
| نام فیلد |
نوع داده |
الزامی |
توضیح |
| title |
string |
بله |
عنوان اعلان |
| content |
string |
بله |
متن کامل اعلان برای نمایش |
| type |
string |
بله |
نوع اعلان (simple / system / branch) |
| receiver_id |
integer |
خیر |
شناسه کاربر یا اپراتور مقصد |
| branch |
integer |
خیر |
شناسه شعبه یا محدوده ارسال |
| status |
boolean |
خیر |
وضعیت فعال یا غیرفعال بودن اعلان |
نمونه درخواست:
POST /api/v2/notif/send
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json
{
"title": "هشدار موجودی",
"content": "موجودی کیف پول شما کمتر از حد مجاز است.",
"type": "simple",
"branch": 5,
"status": true
}
ساختار خروجی
| فیلد |
نوع داده |
توضیح |
| status |
boolean |
وضعیت موفقیت عملیات |
| meta.timestamp |
integer |
زمان واکنش سرور (Unix) |
| data.id |
integer |
شناسه اعلان ایجادشده در DB |
| data.title |
string |
عنوان اعلان ثبتشده |
نمونه پاسخ:
{
"status": true,
"meta": {"timestamp": 1732289390},
"data": {
"id": 341,
"title": "هشدار موجودی"
}
}
نکات امنیتی و کنترل دسترسی
- نیازمند احراز هویت توسط Middleware
authWithJwt.
- در نسخه فعلی محدودیتی بر اساس نقش (Role) وجود ندارد.
- عدم بررسی sanitize فیلد
content میتواند منجر به آسیب تزریق HTML شود.
- ثبت مستقیم در DB بدون queue یا caching انجام میشود.
- در عملکرد بالا تعداد زیاد اعلانها باعث افزایش زمان پاسخ و تحمیل بار I/O بر DB میگردد.
- توصیه به اضافهکردن سیستم push یا asynchronous job (queue).
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Http\Request;
- use App\Models\Notification;
- use App\Helpers\Functions;
- use Carbon\Carbon;
کدهای خطا و پاسخهای غیرعادی
| کد خطا |
شرح خطا |
منبع |
| 400 |
Missing or invalid input data |
Validation مرحله ورود داده |
| 1006 |
توکن JWT منقضی یا نادرست |
auth middleware |
| 500 |
Database Exception هنگام ثبت اعلان |
DB::insert() |
پیشنهادهای امنیتی
- استفاده از Escaping در محتوای
content.
- اعمال محدودیت سطح دسترسی ارسال اعلان به فقط
adminها یا super-operatorها.
- اعمال rate-limit (۵ اعلان در دقیقه).
پیشنهادهای بهبود
- افزودن ستون
read_at برای ثبت زمان خواندهشدن اعلان.
- افزودن queue جهت ارسال همزمان به چند گیرنده.
- اضافهکردن Audit Log برای ثبت هویت ارسالکننده.
ممیزی و لاگها
- در نسخه فعلی هیچ لاگی برای ثبت ارسال اعلان در جدول
system_logs وجود ندارد.
- پیشنهاد: استفاده از
SystemLog::dispatch('notification_created') هنگام ایجاد رکورد.
جمعبندی
این مسیر کلیدی برای مدیریت و ارسال اعلان در سیستم است اما نیازمند تقویت زیرساخت امنیتی و ممیزی است. در وضعیت فعلی مناسب برای پنل داخلی است ولی برای ارسال real-time یا حجم زیاد اعلان، باید از queue و caching استفاده شود.
