Skip to main content
#P1483

GET /api/v2/base/certificates

Route Info

Method Endpoint Controller Middleware Purpose
GET /api/v2/base/certificates V2BaseController@indexCertificates authWithJwt نمایش لیست گواهی‌نامه‌های شعبه شامل فایل‌ها و پیش‌نمایش محتوای آن‌ها.

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

تابع indexCertificates سطرهای جدول certificates را که مربوط به شعبه‌ی کاربر فعلی هستند واکشی می‌کند، سپس آن‌ها را بر اساس id DESC مرتب می‌نماید. هر آیتم از نظر وجود فایل document بررسی شده و در صورت وجود، تصویر پیش‌نمایش تولید می‌شود:
  • اگر document با پسوند .pdf باشد، آیکون PDF نمایش داده می‌شود.
  • در غیر این صورت، پیش‌نمایش تصویر آپلود شده از Storage (service01) تولید می‌شود.
در انتها فیلدهای اضافی مانند created_at، updated_at و branch حذف می‌گردند و نتیجه با ساختار تفکیک‌شده بازگردانده می‌شود.

ورودی‌ها

نام پارامتر نوع داده منبع الزامی توضیح
branch integer Header / JWT بله شناسه شعبه‌ای که داده‌ی گواهی‌نامه در آن ذخیره شده.

نمونه درخواست:

GET /api/v2/base/certificates
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

فیلد نوع داده توضیح
items[].id integer شناسه گواهی‌نامه.
items[].title string عنوان ثبت‌شده مدارک.
items[].document string مسیر فایل سند در Storage.
items[].preview string|html کد HTML شامل تصویر یا محتوای نوشته برای پیش‌نمایش.
meta.timestamp integer زمان یونیکس ثبت پاسخ.

نمونه پاسخ موفق:

{
  "items": [
    {
      "id": 128,
      "title": "گواهی ISO 9001",
      "document": "media/certificates/iso9001.pdf",
      "preview": ""
    },
    {
      "id": 129,
      "title": "مجوز درجه دو",
      "document": "media/certificates/license.png",
      "preview": ""
    }
  ],
  "meta": {
    "timestamp": 1750669215
  }
}

نکات امنیتی

  • نیازمند احراز هویت JWT معتبر از طریق Middleware authWithJwt.
  • کاربر تنها به گواهی‌نامه‌های شعبه‌ی خودش دسترسی دارد.
  • هیچ فیلد فایلی به‌صورت قابل نوشتن بازگردانده نمی‌شود.

نکات عملکردی

  • کوئری ساده با orderBy('id','DESC') و احتمالاً بدون نیاز به ایندکس اضافی.
  • در صورت افزایش حجم داده پیشنهاد صفحه‌بندی یا limit(50).
  • امکان cache خروجی در Redis با کلید certificates:{branch} با TTL=1800s برای کاهش بار DB.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Exception;
  • use Illuminate\Http\Request;
  • use Illuminate\Support\Facades\Response;

کدهای خطا

کد شرح خطا منبع
400 خطا در اجرای کوئری پایگاه‌داده. Catch(Exception)
404 هیچ گواهی‌نامه‌ای برای این شعبه یافت نشد. indexCertificates()

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

  • اضافه‌کردن کنترل سطح دسترسی Role (مثلاً can('view_certificates')).
  • رمزنگاری مسیر فایل برای جلوگیری از دسترسی مستقیم خارج از Storage.
  • اعتبارسنجی دقیق SSL Storage (service01.ir).

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

  • افزودن صفحه‌بندی و فیلتر جستجو بر اساس title.
  • پشتیبانی از پیش‌نمایش PDF با Embedded Viewer.
  • اضافه کردن فیلد uploaded_by برای لاگ مسئول بارگذاری.
  • افزودن شمارنده کل برای جدول certificates.

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

  • نوع لاگ توصیه‌شده: ReadCertificates.
  • ذخیره فیلدهای: operator_id، branch، count(items).
  • سطح لاگ پیشنهادی: Info.

جمع‌بندی

متد indexCertificates داده‌های ساده و استاتیک گواهی‌نامه‌های شعبه را واکشی می‌کند و پیش‌نمایش‌های خودکار از فایل یا تصویر ایجاد می‌کند. پیشنهاد می‌شود برای بهبود سرعت در بارگذاری داشبوردها، خروجی در Redis cache ذخیره شود و در نسخه بعدی قابلیت جستجوی پویا اضافه گردد.
Back to top