Skip to main content
#P1714

GET /v2/credit-card/index

Credit Card: List & Index

این اندپوینت وظیفه واکشی و نمایش لیست کارت‌های اعتباری صادر شده را بر عهده دارد.
مهم‌ترین ویژگی این بخش، اعمال لایه‌ی امنیتی روی شماره کارت‌ها (Masking) جهت حفاظت از داده‌های حساس و همچنین فیلترینگ هوشمند بر اساس دسترسی شعبه (Branch Access) می‌باشد.

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 (الزامی) شناسه شعبه درخواست‌کننده. اگر کاربر ادمین مرکزی نباشد، لیست فقط محدود به رکوردهای این شعبه می‌شود.
paginate[length] integer (الزامی) تعداد رکورد مورد نظر در هر صفحه (Limit).
paginate[start] integer (الزامی) آفست (Offset) شروع رکوردها. سیستم از این عدد برای محاسبه شماره صفحه فعلی استفاده می‌کند.

Logic Details

منطق پردازش لیست شامل مراحل امنیتی و محاسباتی زیر است:

  1. کنترل سطح دسترسی شعبه (Branch Filtering):
    • سیستم بررسی می‌کند که آیا branch ارسال شده برابر با 1 (دفتر مرکزی) است یا خیر.
    • اگر branch != 1 باشد، شرط whereJsonContains('branch', $branch) به کوئری اضافه می‌شود. این یعنی یک کارت ممکن است به چند شعبه دسترسی داشته باشد (ساختار JSON).
  2. غنی‌سازی داده‌ها (Data Enrichment):
    • جدول credit_cards با جدول customers به صورت Left Join ترکیب می‌شود.
    • هدف: استخراج نام و نام خانوادگی فارسی مسافر (`first_name_fa`, `last_name_fa`) جهت نمایش در لیست.
  3. محاسبه صفحه‌بندی (Pagination Logic):
    • لاراول به صورت پیش‌فرض با page کار می‌کند، اما ورودی دیتاتیبل معمولاً start و length است.
    • فرمول تبدیل: $page = ($start == 0 ? $length : $start + $length) / $length.
  4. لایه امنیت و تغییر فرمت (Security Transformation):
    • ماسک کردن شماره کارت: تابع Functions::creditCardSecurity فراخوانی می‌شود.
      الگوریتم: نمایش ۴ رقم اول + ******** + نمایش ۴ رقم آخر.
      نتیجه: 6219********1234.
    • مدیریت مقادیر خالی: فیلدهای withdrawal_limit و blocked_amount بررسی می‌شوند؛ اگر null باشند، مقدار false برگردانده می‌شود تا در فرانت‌اند خطای تایپ رخ ندهد.

Response Structure

پاسخ موفق

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

مدیریت خطا

در صورت بروز خطای دیتابیس یا منطقی، ساختار زیر برای دیباگ برگردانده می‌شود:

{
  "error": {
    "code": "HY000",
    "message": "SQLSTATE[HY000]: General error: ...",
    "file": "/app/Http/Controllers/V2/CreditCards.php",
    "line": 85
  },
  "meta": { "timestamp": 1715005123 }
}

Flowchart

Start Request
↓
Is Branch == 1?
No (Specific Branch)
Add Filter
whereJsonContains('branch', id)
Yes (HQ)
No Filter Applied
↓
Execute Query
Left Join Customers table
Apply Pagination
↓
Transform Data
1. Mask Card Number (****)
2. Format Response JSON
↓
Return 200 OK
Back to top