#P1430

POST /api/v2/customers/list

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/customers/list	UserController@passengersList	authWithJwt	دریافت فهرست مشتریان (مسافران) با قابلیت جستجا و صفحه‌بندی

منطق عملکرد

داده ورودی در فیلد json به‌صورت string JSON ارسال می‌شود و Parse می‌گردد.
محاسبه اندیس شروع لیست (start) و ارزش شمارش (length) برای صفحه‌بندی.
فیلتر اصلی بر اساس مقدار Data->search->value تنظیم می‌شود:
- اگر مقدار عددی باشد: جستجو بر اساس id، national_code، mobile، phone.
- اگر رشته باشد: جستجو بر مبنای نام فارسی یا انگلیسی، یا فیلد office.
اعمال شرط whereJsonContains('branch', $request->get('branch')) برای محدودکردن نمایش به شعبه جاری.
دریافت داده‌ها با paginate() براساس طول و اندیس.
برای هر رکورد:
- واکشی داده ملیت از Redis تحت کلید countries:{country_id}.
- در صورت عدم وجود، کوئری DB و سپس کش‌گذاری در Redis.
- تبدیل تاریخ تولد و تاریخ انقضای پاسپورت با تابع Functions::int2DateTime.
بازگرداندن داده در قالب DataTables سازگار با `draw`, `recordsTotal`, `recordsFiltered` و آرایه `data`.

پارامترهای ورودی

نام	نوع	ضروری	توضیح
json	stringified JSON	بله	داده‌های صفحه‌بندی و جستجو شامل `start`, `length`, `search->value`, `draw`.
branch	integer	بله	شناسه شعبه جاری برای فیلتر رکوردها

POST /api/v2/customers/list
{
  "json": "{\"start\":0,\"length\":10,\"search\":{\"value\":\"علیرضا\"},\"draw\":1}",
  "branch": 12
}

نمونه خروجی موفق

{
  "draw": 1,
  "recordsTotal": 1052,
  "recordsFiltered": 1052,
  "data": [
    {
      "passenger_id": 4021,
      "national_code": "1234567890",
      "birthday": "1383/12/10",
      "name_fa": "علیرضا",
      "lastname_fa": "ایرانپور",
      "citizenship": {
        "id": 118,
        "fa_name": "ایران",
        "fa_nationality": "ایرانی"
      },
      "sex": true
    }
  ]
}

امنیت

JWT معتبر برای دسترسی الزامی است.
فیلتر رکوردها محدود به شعبه کاربر.

Dependencies

Customer Model
Redis
DB::table('countries')
Functions::int2DateTime

کارایی

پاسخ‌دهی مبتنی بر Redis بسیار سریع است (~3 ms برای داده‌های کش‌شده، ~25 ms برای واکشی اولیه).

مدیریت خطا

در صورت دریافت ورودی نامعتبر JSON یا branch خالی، منجر به پاسخ ناقص بدون code خاص می‌شود؛ بهتر است اعتبارسنجی اضافه شود.

اثرات جانبی

کش‌گذاری کشورها در Redis برای آیتم‌های جدید.

ردپای حسابرسی

ثبت لاگ مستقیم ندارد.

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

اضافه‌کردن TTL به Redis برای تازه‌سازی خودکار ملیت‌ها.
بهینه‌سازی جستجو با ایندکس‌های ترکیبی روی فیلدهای اسمی.

جمع‌بندی

روت امکان واکشی سریع و صفحه‌بندی‌شده‌ی لیست مسافران یک شعبه را فراهم می‌کند. طراحی آن برای محیط‌های DataTables بسیار مناسب است.