# GET /api/v2/base/certificates

<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="margin: 15px auto; width: 96%; border-collapse: collapse; text-align: center;"><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 style="direction: ltr; text-align: left;">GET</td><td style="direction: ltr; text-align: left;">/api/v2/base/certificates</td><td style="direction: ltr; text-align: left;">V2BaseController@indexCertificates</td><td style="direction: ltr; text-align: left;">authWithJwt</td><td style="direction: rtl; text-align: right;">نمایش لیست گواهی‌نامه‌های شعبه شامل فایل‌ها و پیش‌نمایش محتوای آن‌ها.</td></tr></tbody></table>

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

<div id="bkmrk-%D8%AA%D8%A7%D8%A8%D8%B9-indexcertificat" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><div style="direction: rtl; text-align: justify;">تابع **indexCertificates** سطرهای جدول `certificates` را که مربوط به شعبه‌ی کاربر فعلی هستند واکشی می‌کند، سپس آن‌ها را بر اساس `id DESC` مرتب می‌نماید. هر آیتم از نظر وجود فایل `document` بررسی شده و در صورت وجود، تصویر پیش‌نمایش تولید می‌شود: - اگر `document` با پسوند `.pdf` باشد، آیکون PDF نمایش داده می‌شود.
- در غیر این صورت، پیش‌نمایش تصویر آپلود شده از Storage (service01) تولید می‌شود.

در انتها فیلدهای اضافی مانند `created_at`، `updated_at` و `branch` حذف می‌گردند و نتیجه با ساختار تفکیک‌شده بازگردانده می‌شود.</div></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-%D8%AF%D8%A7%D8%AF%D9%87" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="margin: 15px auto; width: 90%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام پارامتر</td><td>نوع داده</td><td>منبع</td><td>الزامی</td><td>توضیح</td></tr><tr><td>branch</td><td>integer</td><td>Header / JWT</td><td>بله</td><td>شناسه شعبه‌ای که داده‌ی گواهی‌نامه در آن ذخیره شده.</td></tr></tbody></table>

</div>#### نمونه درخواست:

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

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### خروجی (Response)

<div id="bkmrk-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="margin: 15px auto; width: 94%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>فیلد</td><td>نوع داده</td><td>توضیح</td></tr><tr><td>items\[\].id</td><td>integer</td><td>شناسه گواهی‌نامه.</td></tr><tr><td>items\[\].title</td><td>string</td><td>عنوان ثبت‌شده مدارک.</td></tr><tr><td>items\[\].document</td><td>string</td><td>مسیر فایل سند در Storage.</td></tr><tr><td>items\[\].preview</td><td>string|html</td><td>کد HTML شامل تصویر یا محتوای نوشته برای پیش‌نمایش.</td></tr><tr><td>meta.timestamp</td><td>integer</td><td>زمان یونیکس ثبت پاسخ.</td></tr></tbody></table>

</div>#### نمونه پاسخ موفق:

```
{
  "items": [
    {
      "id": 128,
      "title": "گواهی ISO 9001",
      "document": "media/certificates/iso9001.pdf",
      "preview": "<img src="https://storage.service01.ir/media/temporary/icon-pdf.png"></img>"
    },
    {
      "id": 129,
      "title": "مجوز درجه دو",
      "document": "media/certificates/license.png",
      "preview": "<img src="https://storage.service01.ir/media/certificates/license.png"></img>"
    }
  ],
  "meta": {
    "timestamp": 1750669215
  }
}
```

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

<div id="bkmrk-%D9%86%DB%8C%D8%A7%D8%B2%D9%85%D9%86%D8%AF-%D8%A7%D8%AD%D8%B1%D8%A7%D8%B2-%D9%87%D9%88%DB%8C%D8%AA-j" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نیازمند احراز هویت JWT معتبر از طریق Middleware `authWithJwt`.
- کاربر تنها به گواهی‌نامه‌های شعبه‌ی خودش دسترسی دارد.
- هیچ فیلد فایلی به‌صورت قابل نوشتن بازگردانده نمی‌شود.

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

<div id="bkmrk-%DA%A9%D9%88%D8%A6%D8%B1%DB%8C-%D8%B3%D8%A7%D8%AF%D9%87-%D8%A8%D8%A7-orderb" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- کوئری ساده با `orderBy('id','DESC')` و احتمالاً بدون نیاز به ایندکس اضافی.
- در صورت افزایش حجم داده پیشنهاد صفحه‌بندی یا `limit(50)`.
- امکان cache خروجی در Redis با کلید `certificates:{branch}` با TTL=1800s برای کاهش بار DB.

</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 Exception;
- use Illuminate\\Http\\Request;
- use Illuminate\\Support\\Facades\\Response;

</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="margin: 15px auto; width: 88%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>400</td><td>خطا در اجرای کوئری پایگاه‌داده.</td><td>Catch(Exception)</td></tr><tr><td>404</td><td>هیچ گواهی‌نامه‌ای برای این شعبه یافت نشد.</td><td>indexCertificates()</td></tr></tbody></table>

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

<div id="bkmrk-%D8%A7%D8%B6%D8%A7%D9%81%D9%87%E2%80%8C%DA%A9%D8%B1%D8%AF%D9%86-%DA%A9%D9%86%D8%AA%D8%B1%D9%84-%D8%B3%D8%B7%D8%AD" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- اضافه‌کردن کنترل سطح دسترسی Role (مثلاً `can('view_certificates')`).
- رمزنگاری مسیر فایل برای جلوگیری از دسترسی مستقیم خارج از Storage.
- اعتبارسنجی دقیق SSL Storage (service01.ir).

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

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%B5%D9%81%D8%AD%D9%87%E2%80%8C%D8%A8%D9%86%D8%AF%DB%8C-%D9%88-%D9%81" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن صفحه‌بندی و فیلتر جستجو بر اساس `title`.
- پشتیبانی از پیش‌نمایش PDF با Embedded Viewer.
- اضافه کردن فیلد `uploaded_by` برای لاگ مسئول بارگذاری.
- افزودن شمارنده کل برای جدول `certificates`.

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

<div id="bkmrk-%D9%86%D9%88%D8%B9-%D9%84%D8%A7%DA%AF-%D8%AA%D9%88%D8%B5%DB%8C%D9%87%E2%80%8C%D8%B4%D8%AF%D9%87%3A-r" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- نوع لاگ توصیه‌شده: `ReadCertificates`.
- ذخیره فیلدهای: `operator_id`، `branch`، `count(items)`.
- سطح لاگ پیشنهادی: **Info**.

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

<div id="bkmrk-index-certificates" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><div style="direction: rtl; text-align: justify;">متد **indexCertificates** داده‌های ساده و استاتیک گواهی‌نامه‌های شعبه را واکشی می‌کند و پیش‌نمایش‌های خودکار از فایل یا تصویر ایجاد می‌کند. پیشنهاد می‌شود برای بهبود سرعت در بارگذاری داشبوردها، خروجی در Redis cache ذخیره شود و در نسخه بعدی قابلیت جستجوی پویا اضافه گردد.</div></div>