# POST /announcement/update

<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/update</td><td dir="ltr">V2CreditDebitController@updateAnnouncement</td><td dir="ltr">authWithJwt</td><td dir="rtl">بروزرسانی اطلاعات اعلان مالی موجود پس از تایید سطح دسترسی.</td></tr></tbody></table>

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

تابع **updateAnnouncement** برای ویرایش ایمن رکورد موجود در جدول `announcements` به کار می‌رود. ابتدا بررسی می‌کند که اعلان با شناسهٔ مشخص در شعبهٔ کاربر و وضعیت باز وجود داشته باشد.

در صورت تأیید، به‌روزرسانی مقادیر کلیدی مانند نوع، توضیح، مبلغ یا شیء مرجع انجام می‌شود. پس از ثبت تغییرات در DB، کش مالی مرتبط با شاخهٔ ذکرشده پاک‌سازی شده (**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>نوع عملیات مالی؛ در صورت ارسال جایگزین مقدار پیشین می‌شود.</td></tr><tr><td>description</td><td>string</td><td>Body</td><td>خیر</td><td>توضیح جدید اعلان مالی.</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></tbody></table>

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

```
{
  "status": true,
  "message": "Announcement updated successfully.",
  "data": {
    "id": 114,
    "branch": 3,
    "type": "pay",
    "description": "اصلاح توضیحات اعلان جهت سند پرداخت",
    "updated_at": "2025-11-23 16:55:04",
    "operator": 17
  }
}
```

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

<div id="bkmrk-jwt-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%A7%D8%B3%D8%AA.-%D9%86%D9%82%D8%B4-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- JWT الزامی است.
- نقش لازم: `financial.announcement.edit` یا سطح بالاتر.
- عدم اجازه بروزرسانی اعلان‌های بسته یا پایان‌یافته (status ≥ locked).
- بررسی انطباق `branch` بین کاربر و رکورد.

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

<div id="bkmrk-%D8%AF%D8%B1-%D8%B9%D9%85%D9%84%DB%8C%D8%A7%D8%AA-update-%D8%A7%D8%B2-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- در عملیات update از `DB::transaction` استفاده شده تا atomic بودن تضمین شود.
- جلوی تکرار کش redis با TTL جدید گرفته می‌شود (invalidate فوری شعبه).
- میانگین اجرای عملیات: ۶۵–۸۰ ms.

</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 Carbon\\Carbon;
- use App\\Helpers\\Functions;

</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>شناسه یا پارامترهای ورودی ناقص است.</td><td>Validator</td></tr><tr><td>403</td><td>کاربر مجوز ویرایش این اعلان را ندارد.</td><td>RBAC</td></tr><tr><td>404</td><td>اعلان یافت نشد یا از شعبه دیگر است.</td><td>Query</td></tr><tr><td>423</td><td>اعلان بسته است و قابل ویرایش نیست.</td><td>Business Rule</td></tr><tr><td>500</td><td>خطای داخلی سرور در هنگام ذخیره.</td><td>Exception</td></tr></tbody></table>

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

<div id="bkmrk-%D8%AB%D8%A8%D8%AA-timestamp-%D8%AA%D8%BA%DB%8C%DB%8C%D8%B1-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- ثبت timestamp تغییر با IP کاربر در Log.
- افزودن قفل optimistic برای جلوگیری از وضعیت race-condition هنگام ویرایش همزمان.

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-endpoint-%D9%85%D8%AC%D8%B2%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن endpoint مجزای `/announcement/notes` جهت نگهداری شرح تغییرات.
- پشتیبانی از بروزرسانی بخشی (partial update) با PATCH.

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

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%85%D9%85%DB%8C%D8%B2%DB%8C%3A-updateann" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع ممیزی: `UpdateAnnouncement`.
- موارد ثبت‌شونده: id، operator، branch، تغییرات انجام‌شده.
- سطح حساسیت: **Audit**.

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

تابع **updateAnnouncement** با رویکرد atomic و قفل منطقی روی داده‌ها، به‌عنوان لایه انتقال برای عملیات اصلاح اعلان‌های مالی عمل می‌کند و بخشی از چرخه ممیزی شعبه در ماژول مالی محسوب می‌شود.

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