#P1714
GET /v2/credit-card/index
Credit Card: List & Index
این اندپوینت وظیفه واکشی و نمایش لیست کارتهای اعتباری صادر شده را بر عهده دارد. اطلاعاتمهمترین درویژگی این لیستبخش، شاملاعمال وضعیت کارت، مشخصات مسافر و محدودیتهای مالی است. نکته مهملایهی امنیتی این اندپوینت، ماسک کردن (Masking)روی شماره کارتهاست،ها به(Masking) طوریجهت کهحفاظت تنهااز ۴دادههای رقم ابتداییحساس و انتهاییهمچنین قابلفیلترینگ مشاهدههوشمند هستند.بر اساس دسترسی شعبه (Branch Access) میباشد.
Request Overview
URL:
/v2/credit-card/indexMethod: GET
Controller: CreditCards@indexCreditCard
Middleware: authWithJwt
Access Control
- نیاز به توکن احراز هویت (JWT).
پاسخدادهها بر اساس پارامترbranchفیلتر میشوند (دسترسیایزولهسازیشعبه)دادههای شعب).
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| branch | integer | (الزامی) شناسه نباشد، |
| paginate[length] | integer | (الزامی) تعداد |
| paginate[start] | integer | (الزامی) |
Logic Details
منطق دریافتپردازش لیست شامل مراحل امنیتی و محاسباتی زیر است:
فیلترینگکنترل سطح دسترسی شعبه (AccessBranchPolicy)Filtering):اگرسیستمپارامتربررسی میکند که آیاbranchارسال شده برابر با 1نباشد(شعبه غیردفتر مرکزی)،است یا خیر.- اگر
branch != 1باشد، شرطwhereJsonContains('branch', $branch)به کوئری اضافه میشود. این یعنی یککوئری روی ستون JSONbranchاجرا میشود. از دستورwhereJsonContainsاستفاده میشود تا اطمینان حاصل شودکارتمتعلقممکن است به چند شعبهدرخواستکنندهدسترسیاست.داشته باشد (ساختار JSON).
تجمعغنیسازی دادهها (DataAggregation)Enrichment):- جدول
credit_cardsبا جدولcustomers(به صورت LeftJoin)Join ترکیب میشود. هدف از این جوین،هدف: استخراج نام و نام خانوادگی فارسی مسافر (`first_name_fa`, `last_name_fa`)صاحبجهتکارتنمایشاست.در لیست.
- جدول
- محاسبه صفحهبندی
دستی(PaginationCalculation)Logic):شمارهلاراولصفحهبهفعلیصورت(Current Page)پیشفرض باpageکار میکند، اما ورودی دیتاتیبل معمولاًstartوlengthاست.- فرمول
زیرتبدیل:محاسبه$pageمیشود:=($start == 0 ? $length : $start + $length) / $length سپس متدpaginateلاراول با شماره صفحه محاسبه شده فراخوانی میگردد..
- لایه امنیت و تغییر
شکل دادههافرمت (TransformationSecurity& Security)Transformation):- ماسک کردن شماره کارت: تابع
Functions::creditCardSecurityاجرافراخوانی میشود.فرمتالگوریتم:خروجی:نمایش4۴ رقم اول +ستاره (*+)*******4نمایش ۴ رقم آخر.مثال:نتیجه:.6037*6219********1234 - مدیریت مقادیر
Null:خالی: فیلدهایwithdrawal_limitوblocked_amountچکبررسی میشوند؛ اگرنالnullباشند، مقدارfalseبرگردانده میشود.شود تا در فرانتاند خطای تایپ رخ ندهد.
- ماسک کردن شماره کارت: تابع
Response Structure
پاسخ موفق (200 OK)
{
"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": "42S22"HY000", // SQL Error Code
"message": "ColumnSQLSTATE[HY000]: notGeneral found.error: ...",
"file": "/app/Http/Controllers/V2/CreditCards.php",
"line": 4585
},
"meta": { "timestamp": 17150012001715005123 }
}
Flowchart
Start Request
↓
Is Branch == 1?
No (Specific Branch)
Add Filter Query
whereJsonContains(branch)'branch', id)
whereJsonContains(
Yes (Admin)HQ)
No Filter Applied
↓
Execute Query Database
Left Join Customers table
CalculateApply Page NumberPagination
Left Join Customers table
↓
Transform Data Transformation
1. Mask Card Number (****)
2. FormatPassengerResponse ObjJSON
1. Mask Card Number (****)
2. Format
↓
Return JSON200 ListOK