#P1507
POST /announcement/view
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/announcement/view | V2CreditDebitController@viewAnnouncement | authWithJwt | نمایش جزئیات کامل یک اعلان مالی برای بازبینی یا مشاهدهی بدون ویرایش. |
منطق عملکرد تابع
تابع viewAnnouncement با دریافت شناسهٔ اعلان، رکورد مربوطه را از جدول announcements خوانده و در صورت نیاز ارتباطات آن را (مانند پرداختها، چکها، و اعلانهای وابسته) نیز شامل میکند.
هیچ تغییری در داده انجام نمیشود. این endpoint فقط برای مشاهده، چاپ یا آمادهسازی نمای modal یا PDF استفاده میشود. چنانچه اعلان مورد نظر قفل مالی یا در وضعیت بسته باشد، فقط در حالت read-only قابل دریافت است.
ورودیها
| نام پارامتر | نوع | منبع | الزامی | توضیح |
| id | integer | Body | بله | شناسهٔ اعلان مورد نظر برای مشاهده. |
| branch | integer | JWT/Header | بله | شعبهٔ کاربر جهت بررسی محدودهٔ مجاز. |
| operator | integer | JWT | بله | شناسهٔ کاربر درخواستدهنده جهت ثبت در لاگ مشاهده. |
| include_related | boolean | Body | خیر | در صورت true، دادههای وابسته (پرداختها، چکها، و اعلانهای فرزند) نیز اضافه میشود. |
خروجی (Response)
{
"status": true,
"data": {
"id": 114,
"type": "pay",
"object_id": 554,
"branch": 3,
"status": "done",
"description": "هزینه بلیط پرواز تهران–مشهد",
"created_at": "2025-11-20 18:35:00",
"updated_at": "2025-11-21 09:12:11",
"financial_lock": false,
"related": [
{
"id": 882,
"type": "check",
"status": "cleared",
"deadline": "1404/09/10"
}
]
}
}
نکات امنیتی
- احراز هویت JWT الزامی است.
- نقش مورد نیاز:
financial.announcement.view. - اطلاعات نمایششده فقط برای شعبهٔ کاربر قابل دسترس است.
نکات عملکردی
- درخواست سبک (read-only) با
selectمحدود به ستونهای مرتبط. - در صورت فعال بودن
include_related، کوئری به صورت lazy load اجرا میشود (Load factor ~1.3x). - TTL کش Redis برای نتایج تکراری ۹۰ ثانیه.
وابستگیها
- 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 | خطای داخلی در بازیابی اطلاعات یا join دادههای وابسته. | Exception |
پیشنهادهای امنیتی
- افزودن لاگ رسمی
financial_view_logبرای ثبت تاریخچهٔ مشاهده. - محدودسازی فیلدهای حساس در پاسخ JSON برای کاربران با نقش پایینتر.
پیشنهادهای بهبود
- افزودن قابلیت فیلتر view با ورودی
object_typeبرای نمایش اعلانهای خاص یک ماژول. - امکان ارسال
format=pdfجهت تولید فایل قابل چاپ.
ممیزی و لاگها
- نوع ممیزی:
ViewAnnouncement. - دادههای ثبتشونده: id، branch، operator، زمان درخواست.
- سطح حساسیت: Notice.
جمعبندی
تابع viewAnnouncement مسیر read-only برای مشاهدهٔ ایمن جزئیات اعلان مالی است و به کاربران دارای نقش مشاهده اجازه میدهد محتوای دقیق رکورد را بدون دخالت در فرآیندهای مالی بخوانند. دادهها با دسترسی کنترلشده و کش زماندار ارائه میشوند.