#P1505
POST /announcement/store
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/store | V2CreditDebitController@storeAnnouncement | authWithJwt | ثبت یا بهروزرسانی درجا (Inline) اعلان مالی در فرمهای پرداخت/دریافت. |
منطق عملکرد تابع
تابع storeAnnouncement در این حالت برای ثبت سریع اعلان (مثلاً همزمان با ثبت سند پرداخت) استفاده میشود. در صورتی که شناسهای از اعلان موجود ارسال شود، دادهٔ موجود ویرایش میشود وگرنه رکوردی جدید در جدول announcements ایجاد میگردد.
پس از درج یا بهروزرسانی، حافظهٔ کش مالی Redis برای شاخهٔ مربوطه پاکسازی (invalidate) شده و شناسهٔ نهایی در خروجی بازگردانده میشود.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| id | integer | Body | خیر | شناسهٔ اعلان (در صورت ویرایش رکورد موجود). |
| type | string | Body | بله | نوع اعلان (مثلاً pay، receive). |
| object_id | integer | Body | بله | شناسهٔ رکورد منبع (سند/چک/تراکنش). |
| branch | integer | JWT/Header | بله | شعبهٔ مرتبط برای تعیین محدودهٔ داده. |
| operator | integer | JWT | بله | شناسهٔ کاربر ثبتکننده. |
| description | string | Body | خیر | توضیحات اختیاری جهت ثبت در اعلان مالی. |
خروجی (Response)
{
"status": true,
"message": "Announcement stored successfully",
"data": {
"id": 114,
"branch": 3,
"type": "pay",
"object_id": 554,
"description": "ثبت خودکار همزمان با پرداخت",
"timestamp": "2025-11-23 16:19:00"
}
}
نکات امنیتی
- احراز JWT اجباری.
- نقش مجاز:
financial.announcement.edit. - کنترل حفظ مالکیت داده با چککردن
branchدر JWT و جدول اعلانها.
نکات عملکردی
- بعد از عملیات
insert/update، Redis کش مربوط به اعلانهای آن شعبه را پاک میکند. - TTL پیشفرض کشهای وابسته: ۶۰۰ ثانیه.
- پردازش میانگین کمتر از ۴۵ms برای حالت local data write.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Helpers\Functions;
- use Carbon\Carbon;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | پارامتر type یا object_id ارسال نشده است. | Validator |
| 403 | دسترسی نقش به ویرایش اعلانها محدود است. | RBAC |
| 404 | رکورد ارسالی برای ویرایش یافت نشد. | DB Query |
| 500 | خطای داخلی در عملیات درج یا بروزرسانی. | Exception Handler |
پیشنهادهای امنیتی
- افزودن verify-level دوم برای اعلانهایی که به مبالغ بالا مربوط میشوند.
- ثبت لاگ IP و timestamp در جدول ممیزی.
پیشنهادهای بهبود
- افزودن پارامتر
silentبرای جلوگیری از invalidate موقت کش در عملیات batch. - بهینهسازی واکشی object_id با
joinجهت کاهش round-trip.
ممیزی و لاگها
- نوع ممیزی:
StoreAnnouncementInline. - ثبت شامل: id، branch، operator، object_id و نوع عملیات (insert/update).
- سطح حساسیت: Audit.
جمعبندی
تابع storeAnnouncement در حالت inline بخشی از فرایندهای ترکیبی است که بهصورت بلادرنگ اعلان را همراه با پرداخت یا دریافت درج یا اصلاح میکند و تمام کشهای شعبه را بهروزرسانی مینماید. این تابع جزو مسیرهای با درجهٔ امنیتی بالا در ماژول مالی محسوب میشود.