Skip to main content
#P1504

POST /announcement/edit

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/announcement/edit V2CreditDebitController@editAnnouncement authWithJwt بازیابی داده‌های اولیه برای ویرایش اعلان مالی مشخص‌شده (جهت استفاده در فرم یا modal).

منطق عملکرد تابع

تابع editAnnouncement شناسه اعلان مالی را از ورودی دریافت کرده، اطلاعات کامل آن (از جدول announcements) را همراه با جزئیات اکوسیستم مرتبط (مانند نوع اعلان، وضعیت، شعبه، object مرجع و تاریخ) بازمی‌گرداند. این مسیر هیچ تغییر داده‌ای انجام نمی‌دهد و صرفاً حالت read-only دارد.

اگر اعلان یافت نشود یا کاربر به شاخهٔ مربوطه دسترسی نداشته باشد، خروجی با وضعیت خطا برمی‌گردد.

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
id integer Body بله شناسه اعلان مالی برای واکشی.
branch integer JWT/Header بله شناسه شعبهٔ درخواست‌دهنده برای اعتبارسنجی مالکیت داده.
operator integer JWT بله شناسه کاربر درخواست‌دهنده (برای ممیزی).

خروجی (Response)

{
  "status": true,
  "data": {
    "id": 72,
    "type": "pay",
    "object_id": 544,
    "status": "done",
    "branch": 3,
    "description": "اعلان پرداخت مربوط به فاکتور 554",
    "created_at": "2025-11-02 10:13:44",
    "updated_at": "2025-11-04 13:26:10",
    "operator": {
      "id": 17,
      "name": "Reza Moradi"
    }
  }
}

نکات امنیتی

  • احراز JWT الزامی.
  • نقش مجاز: financial.announcement.view یا بالاتر.
  • کنترل شعبه با تطبیق branch از JWT و رکورد DB.

نکات عملکردی

  • دسترسی دیتابیس بر اساس id ایندکس‌شده انجام می‌شود.
  • در صورت استفاده مجدد، TTL کش Redis برابر ۶۰ ثانیه است (read cache).
  • پاسخ JSON تا حد ممکن minimal طراحی شده تا در modal یا form کاربردی باشد.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use App\Helpers\Functions;
  • use Carbon\Carbon;

کدهای خطا

کد شرح خطا منبع
400 پارامتر id ارسال نشده یا نامعتبر است. Validator
403 کاربر به شعبهٔ اعلان دسترسی ندارد. Auth Middleware
404 اعلان یافت نشد. DB Query
500 خطای داخلی در بازیابی داده از دیتابیس. Exception Handler

پیشنهادهای امنیتی

  • رمزنگاری فیلدهای حساس (object_id و operator) در سطح پاسخ.
  • ثبت زمان و IP درخواست در جدول audit_logs.

پیشنهادهای بهبود

  • افزودن پارامتر include_related برای بازیابی ارتباطات مثل چک‌ها و سندها.
  • پشتیبانی از کش client-side برای کاهش بار سرور.

ممیزی و لاگ‌ها

  • نوع ممیزی: EditAnnouncement.
  • ثبت شامل: id، branch، operator، و زمان درخواست.
  • سطح حساسیت: Notice.

جمع‌بندی

تابع editAnnouncement نقطه آغاز فرآیند ویرایش است که با واکشی دادهٔ دقیق اعلان، محیط کاربر را برای تغییر ایمن آماده می‌کند. این نقطه هیچ داده‌ای را تغییر نمی‌دهد و صرفاً Fetch اولیهٔ امن محسوب می‌شود.

Back to top