# POST /announcement/store

<div id="bkmrk-" 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; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><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 dir="ltr">POST</td><td dir="ltr">/api/v2/announcement/store</td><td dir="ltr">V2CreditDebitController@storeAnnouncement</td><td dir="ltr">authWithJwt</td><td dir="rtl">ثبت یا به‌روزرسانی درجا (Inline) اعلان مالی در فرم‌های پرداخت/دریافت.</td></tr></tbody></table>

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

تابع **storeAnnouncement** در این حالت برای ثبت سریع اعلان (مثلاً هم‌زمان با ثبت سند پرداخت) استفاده می‌شود. در صورتی که شناسه‌ای از اعلان موجود ارسال شود، دادهٔ موجود ویرایش می‌شود وگرنه رکوردی جدید در جدول `announcements` ایجاد می‌گردد.

پس از درج یا به‌روزرسانی، حافظهٔ کش مالی Redis برای شاخهٔ مربوطه پاک‌سازی (invalidate) شده و شناسهٔ نهایی در خروجی بازگردانده می‌شود.

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### ورودی‌ها

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D9%85%D9%86%D8%A8%D8%B9" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 94%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام پارامتر</td><td>نوع</td><td>منبع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>id</td><td>integer</td><td>Body</td><td>خیر</td><td>شناسهٔ اعلان (در صورت ویرایش رکورد موجود).</td></tr><tr><td>type</td><td>string</td><td>Body</td><td>بله</td><td>نوع اعلان (مثلاً `pay`، `receive`).</td></tr><tr><td>object\_id</td><td>integer</td><td>Body</td><td>بله</td><td>شناسهٔ رکورد منبع (سند/چک/تراکنش).</td></tr><tr><td>branch</td><td>integer</td><td>JWT/Header</td><td>بله</td><td>شعبهٔ مرتبط برای تعیین محدودهٔ داده.</td></tr><tr><td>operator</td><td>integer</td><td>JWT</td><td>بله</td><td>شناسهٔ کاربر ثبت‌کننده.</td></tr><tr><td>description</td><td>string</td><td>Body</td><td>خیر</td><td>توضیحات اختیاری جهت ثبت در اعلان مالی.</td></tr></tbody></table>

</div>### خروجی (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"
  }
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-jwt-%D8%A7%D8%AC%D8%A8%D8%A7%D8%B1%DB%8C.-%D9%86%D9%82" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- احراز JWT اجباری.
- نقش مجاز: `financial.announcement.edit`.
- کنترل حفظ مالکیت داده با چک‌کردن `branch` در JWT و جدول اعلان‌ها.

</div>### نکات عملکردی

<div id="bkmrk-%D8%A8%D8%B9%D8%AF-%D8%A7%D8%B2-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA-insert" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- بعد از عملیات `insert/update`، Redis کش مربوط به اعلان‌های آن شعبه را پاک می‌کند.
- TTL پیش‌فرض کش‌های وابسته: ۶۰۰ ثانیه.
- پردازش میانگین کمتر از ۴۵ms برای حالت local data write.

</div>### وابستگی‌ها

<div id="bkmrk-use-illuminate%5Csuppo" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Helpers\\Functions;
- use Carbon\\Carbon;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-400-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>400</td><td>پارامتر type یا object\_id ارسال نشده است.</td><td>Validator</td></tr><tr><td>403</td><td>دسترسی نقش به ویرایش اعلان‌ها محدود است.</td><td>RBAC</td></tr><tr><td>404</td><td>رکورد ارسالی برای ویرایش یافت نشد.</td><td>DB Query</td></tr><tr><td>500</td><td>خطای داخلی در عملیات درج یا بروزرسانی.</td><td>Exception Handler</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-verify-level-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن verify-level دوم برای اعلان‌هایی که به مبالغ بالا مربوط می‌شوند.
- ثبت لاگ IP و timestamp در جدول ممیزی.

</div>### پیشنهادهای بهبود

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-silen" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن پارامتر `silent` برای جلوگیری از invalidate موقت کش در عملیات batch.
- بهینه‌سازی واکشی object\_id با `join` جهت کاهش round-trip.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%85%D9%85%DB%8C%D8%B2%DB%8C%3A-storeanno" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع ممیزی: `StoreAnnouncementInline`.
- ثبت شامل: id، branch، operator، object\_id و نوع عملیات (insert/update).
- سطح حساسیت: **Audit**.

</div>### جمع‌بندی

تابع **storeAnnouncement** در حالت inline بخشی از فرایندهای ترکیبی است که به‌صورت بلادرنگ اعلان را همراه با پرداخت یا دریافت درج یا اصلاح می‌کند و تمام کش‌های شعبه را به‌روزرسانی می‌نماید. این تابع جزو مسیرهای با درجهٔ امنیتی بالا در ماژول مالی محسوب می‌شود.

<div id="bkmrk-announcement-store-inline" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>