Skip to main content
#P1467

POST /api/v2/titles/list

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/titles/list V2BaseController@baseAutomationData authWithJwt دریافت لیست عنوان‌های ثابت یا داده‌های ساختاری جدول‌های پایه مانند room_type، room_rate و room_view

منطق عملکرد تابع

تابع baseAutomationData بر اساس table و action پارامتر دریافت‌شده از درخواست، داده‌های عنوانی مورد نیاز را واکشی و پردازش می‌کند:
  • اگر table برابر با hotel_title باشد، بر اساس مقدار action یکی از سه حالت room_type، room_rate یا room_view اجرا می‌شود.
  • دریافت محتوا از جدول hotel_titles با انتخاب فیلد data و دیکد آن به JSON.
  • ساخت آرایه نهایی fixedTitles با فیلدهای title_fa، title_en، property، status، و selected.
  • ارسال خروجی استاندارد به صورت JSON به همراه زمان UNIX در فیلد time.

ورودی‌ها (Request Fields)

نام فیلد نوع داده الزامی توضیح
table string بله نام جدول در دیتابیس (فقط hotel_title در حال حاضر)
action string بله زیرعملیات مربوط به جدول (مقادیر: room_type، room_rate، room_view)

نمونه درخواست:

POST /api/v2/titles/list
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "table": "hotel_title",
  "action": "room_type"
}

خروجی (Response)

فیلد نوع داده توضیح
status boolean وضعیت کلی درخواست
time integer زمان واکنش سرور
data.titles[] array لیست عنوان‌های ثابت با فیلدهای زبان، وضعیت و ویژگی‌ها

نمونه پاسخ:

{
  "status": true,
  "time": 1732289234,
  "data": {
    "titles": [
      {"title_fa": "سوئیت دونفره", "title_en": "Double Suite", "property": "2 beds", "status": true, "selected": false},
      {"title_fa": "اتاق رو به دریا", "title_en": "Sea View Room", "status": true, "selected": true}
    ]
  }
}

امنیت و کنترل دسترسی

  • تابع دارای لایهٔ امنیتی AuthWithJWT برای تأیید هویت کاربر است.
  • عدم وجود محدودسازی Role-Based بر اساس نوع داده‌ها؛ صرفاً مجوز عمومی کاربر معتبر بررسی می‌شود.
  • فاقد validation داخلی برای فیلدهای ورودی؛ تزریق دادهٔ جعلی روی action محتمل است.

نکات کارایی و پیاده‌سازی

  • داده مستقیماً از جدول `hotel_titles` واکشی می‌شود؛ بدون cache یا pagination.
  • هر بار دیکد JSON کامل در سمت سرور انجام می‌شود؛ در صورت حجم زیاد منجر به افزایش load CPU خواهد شد.
  • نیاز به ایندکس مجزا برای فیلد `title` در جدول hotel_titles جهت بهینه‌شدن Queryها.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use App\Models\HotelTitle;
  • use Illuminate\Http\Request;
  • use App\Helpers\Functions;

کدهای خطا و خروجی‌های Exception

کد خطا شرح منبع
400 Database Exception → Trace بازگردانده می‌شود. baseAutomationData
1006 JWT token منقضی یا نامعتبر. AuthWithJWT

پیشنهادهای امنیتی

  • اعمال Request Validation برای ورودی‌های table و action.
  • پنهان‌سازی Trace کامل در خروجی خطا.
  • محدودسازی دسترسی فقط برای کاربران نوع operator.

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

  • افزودن مکانیزم caching با TTL جهت پاسخ سریع‌تر در تکرار درخواست.
  • جداسازی منطق دریافت داده به کلاس Service مستقل (مثلاً TitleService).
  • افزودن فیلد زبان به عنوان پارامتر اختیاری جهت انتخاب زبان خروجی.

ممیزی دسترسی و لاگ‌ها

  • هیچ لاگ سروری برای ثبت تعداد فراخوانی‌ها وجود ندارد.
  • پیشنهاد ثبت رویداد با event SystemLog::dispatch() جهت ردیابی درخواست‌های غیرمجاز.

جمع‌بندی

این Endpoint مسیر اصلی دریافت عنوان‌های پارامتری در سیستم اتوماسیون است. ساختار ساده و خروجی یکسان باعث سهولت مصرف در فرانت‌اند می‌شود، اما عدم وجود validation و cache منجر به ضعف امنیت و Performance در حجم بالا خواهد شد. توصیه می‌شود Refactor در لایهٔ Service و اعمال TTL روی داده‌های ثابت انجام گیرد.
Back to top