#P1506
POST /announcement/update
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/update | V2CreditDebitController@updateAnnouncement | authWithJwt | بروزرسانی اطلاعات اعلان مالی موجود پس از تایید سطح دسترسی. |
منطق عملکرد تابع
تابع updateAnnouncement برای ویرایش ایمن رکورد موجود در جدول announcements به کار میرود. ابتدا بررسی میکند که اعلان با شناسهٔ مشخص در شعبهٔ کاربر و وضعیت باز وجود داشته باشد.
در صورت تأیید، بهروزرسانی مقادیر کلیدی مانند نوع، توضیح، مبلغ یا شیء مرجع انجام میشود. پس از ثبت تغییرات در DB، کش مالی مرتبط با شاخهٔ ذکرشده پاکسازی شده (Redis invalidate) و دادهٔ نهایی ذخیره شده باز میگردد.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| id | integer | Body | بله | شناسه رکورد اعلان جهت بروزرسانی. |
| type | string | Body | خیر | نوع عملیات مالی؛ در صورت ارسال جایگزین مقدار پیشین میشود. |
| description | string | Body | خیر | توضیح جدید اعلان مالی. |
| object_id | integer | Body | خیر | شناسه رکورد منبع (اختیاری برای تغییر پیوند). |
| branch | integer | JWT/Header | بله | شناسه شعبه جهت کنترل دسترسی. |
| operator | integer | JWT | بله | شناسهٔ کاربر درخواستدهنده برای ثبت در ممیزی. |
خروجی (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
}
}
نکات امنیتی
- JWT الزامی است.
- نقش لازم:
financial.announcement.editیا سطح بالاتر. - عدم اجازه بروزرسانی اعلانهای بسته یا پایانیافته (status ≥ locked).
- بررسی انطباق
branchبین کاربر و رکورد.
نکات عملکردی
- در عملیات update از
DB::transactionاستفاده شده تا atomic بودن تضمین شود. - جلوی تکرار کش redis با TTL جدید گرفته میشود (invalidate فوری شعبه).
- میانگین اجرای عملیات: ۶۵–۸۰ ms.
وابستگیها
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Carbon\Carbon;
- use App\Helpers\Functions;
کدهای خطا
| کد | شرح خطا | منبع |
| 400 | شناسه یا پارامترهای ورودی ناقص است. | Validator |
| 403 | کاربر مجوز ویرایش این اعلان را ندارد. | RBAC |
| 404 | اعلان یافت نشد یا از شعبه دیگر است. | Query |
| 423 | اعلان بسته است و قابل ویرایش نیست. | Business Rule |
| 500 | خطای داخلی سرور در هنگام ذخیره. | Exception |
پیشنهادهای امنیتی
- ثبت timestamp تغییر با IP کاربر در Log.
- افزودن قفل optimistic برای جلوگیری از وضعیت race-condition هنگام ویرایش همزمان.
پیشنهادهای بهبود
- افزودن endpoint مجزای
/announcement/notesجهت نگهداری شرح تغییرات. - پشتیبانی از بروزرسانی بخشی (partial update) با PATCH.
ممیزی و لاگها
- نوع ممیزی:
UpdateAnnouncement. - موارد ثبتشونده: id، operator، branch، تغییرات انجامشده.
- سطح حساسیت: Audit.
جمعبندی
تابع updateAnnouncement با رویکرد atomic و قفل منطقی روی دادهها، بهعنوان لایه انتقال برای عملیات اصلاح اعلانهای مالی عمل میکند و بخشی از چرخه ممیزی شعبه در ماژول مالی محسوب میشود.