#P1714

GET /v2/credit-card/index

Credit Card: List & Index

این اندپوینت وظیفه نمایش لیست کارت‌های اعتباری صادر شده را بر عهده دارد.
اطلاعات در این لیست شامل وضعیت کارت، مشخصات مسافر و محدودیت‌های مالی است. نکته مهم امنیتی این اندپوینت، ماسک کردن (Masking) شماره کارت‌هاست، به طوری که تنها ۴ رقم ابتدایی و انتهایی قابل مشاهده هستند.

Request Overview

URL: /v2/credit-card/index

Method: GET

Controller: CreditCards@indexCreditCard

Middleware: authWithJwt

Access Control

نیاز به توکن احراز هویت (JWT).
پاسخ‌ها بر اساس پارامتر branch فیلتر می‌شوند (دسترسی شعبه).

Query Parameters

Parameter	Type	Description
branch	integer	(الزامی) شناسه شعبه. اگر مقدار غیر از `1` باشد، نتایج فیلتر می‌شوند تا فقط کارت‌های مرتبط با آن شعبه نمایش داده شوند.
paginate[length]	integer	(الزامی) تعداد آیتم‌ها در هر صفحه (Limit).
paginate[start]	integer	(الزامی) نقطه شروع رکوردها (Offset). از این عدد برای محاسبه شماره صفحه استفاده می‌شود.

Logic Details

منطق دریافت لیست شامل مراحل زیر است:

فیلترینگ شعبه (Access Policy):
- اگر پارامتر branch برابر با 1 نباشد (شعبه غیر مرکزی)، یک کوئری روی ستون JSON branch اجرا می‌شود.
- از دستور whereJsonContains استفاده می‌شود تا اطمینان حاصل شود کارت متعلق به شعبه درخواست‌کننده است.
تجمع داده‌ها (Data Aggregation):
- جدول credit_cards با جدول customers (به صورت Left Join) ترکیب می‌شود.
- هدف از این جوین، استخراج نام و نام خانوادگی فارسی (`first_name_fa`, `last_name_fa`) صاحب کارت است.
صفحه‌بندی دستی (Pagination Calculation):
- شماره صفحه فعلی (Current Page) با فرمول زیر محاسبه می‌شود:
  (start == 0 ? length : start + length) / length
- سپس متد paginate لاراول با شماره صفحه محاسبه شده فراخوانی می‌گردد.
امنیت و تغییر شکل داده‌ها (Transformation & Security):
- ماسک کردن شماره کارت: تابع creditCardSecurity اجرا می‌شود.
  فرمت خروجی: 4 رقم اول + ستاره (*) + 4 رقم آخر.
  مثال: 6037********1234
- مدیریت مقادیر Null: فیلدهای withdrawal_limit و blocked_amount چک می‌شوند؛ اگر نال باشند، مقدار false برگردانده می‌شود.

Response Structure

پاسخ موفق (200 OK)

{
  "items": [
    {
      "id": 105,
      "status": 1,
      "card": {
        "number": "6219********4321", // Masked
        "withdrawal_limit": false,
        "blocked_amount": 500000
      },
      "passenger": {
        "id": 2045,
        "first_name": "علی",
        "last_name": "محمدی"
      }
    }
  ],
  "meta": {
    "timestamp": 1715005000,
    "table": {
      "total": 50,
      "per_page": 10,
      "current_page": 1,
      "last_page": 5,
      "from": 1,
      "to": 10
    }
  }
}

پاسخ خطا (Exception)

{
  "error": {
    "code": "42S22", // SQL Error Code
    "message": "Column not found...",
    "file": "/app/Http/Controllers/V2/CreditCards.php",
    "line": 45
  },
  "meta": { "timestamp": 1715001200 }
}

Flowchart

Start Request

↓

Branch == 1?

Filter Query
whereJsonContains(branch)

Yes (Admin)

No Filter

↓

Query Database
Left Join Customers
Calculate Page Number

↓

Data Transformation
Mask Card Number (****)
Format Passenger Obj

↓

Return JSON List