#P1466

GET /api/v2/base/data

Route Info

Method	Endpoint	Controller	Middleware	Purpose
GET	/api/v2/base/data	V2BaseController@automationBaseData	authWithJwt	واکشی داده‌های پایهٔ سیستم اتوماسیون مثل نوع اقامتگاه، کشورها، ایستگاه‌ها، یا تیپ اتاق‌ها

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

تابع automationBaseData وظیفه دارد بر اساس پارامترهای subject یا table و action، داده‌های ثابت مورد نیاز بخش‌هایی مثل رزرو اقامتگاه، نوع قطار، یا نرخ اتاق را واکشی کند. روند اجرای کلی:

بررسی نوع جدول درخواست‌شده (مثلاً hotel_title، countries، train_types، train_stations).
واچش داده‌ها از دیتابیس یا Redis در صورت وجود Cache کلیدشده.
در صورت نبود داده در Redis، فراخوانی مستقیم از جدول یا مدل مربوطه انجام می‌شود (مثلاً HotelTitle).
تبدیل نتیجه به آرایهٔ استاندارد شامل شناسه، عنوان فارسی و انگلیسی، وضعیت و ویژگی.
برگرداندن خروجی در قالب JSON همراه با زمان UNIX و وضعیت.

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

نام فیلد	نوع داده	الزامی	توضیح
subject	string	بله	دسته داده مورد نیاز (مثلاً `train_types` یا `room_rate`)
table	string	خیر	نام جدول اصلی در دیتابیس (مثلاً `hotel_title`)
action	string	خیر	زیرعملیات مربوط به table در صورت وجود (مثلاً `room_type`)
search	string	خیر	فیلتر جستجو برای محدودسازی نتایج
state	int	خیر	شناسهٔ استان مورد استفاده برای فیلتر ایستگاه‌ها

خروجی (Response)

فیلد	نوع داده	توضیح
status	boolean	وضعیت کلی درخواست (true/false)
time	int (Unix Timestamp)	زمان واکنش سرور
data	array	لیست آیتم‌های جدول مورد نظر با title‌ها و شناسه‌ها

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

GET /api/v2/base/data?subject=train_types
Authorization: Bearer {JWT_TOKEN}

نمونه پاسخ:

{
  "status": true,
  "time": 1732289102,
  "data": {
    "titles": [
      {"title_fa": "چهارنفره لوکس", "title_en": "Luxury 4", "status": true},
      {"title_fa": "دو نفره عادی", "title_en": "Standard Couple", "status": true}
    ]
  }
}

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

احراز هویت با AuthWithJWT و بررسی جدول کاربر بر اساس نوع (operators, customers, colleague_auth).
توکن منقضی یا غیرمعتبر → بازگشت کدهای خطا 1006 یا 1001.
هیچ سطح دسترسی Role-Based روی نوع داده‌ها وجود ندارد؛ صرفاً مجوز کلی برای شعبه فعلی.
عدم اعتبارسنجی ورودی‌های search و action امکان تزریق param دارد (پیشنهاد به Validation).

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

هر بار درخواست مستقیماً از DB انجام می‌شود اگر Redis Cache قبلاً موجود نباشد.
محدودسازی نتایج با limit(30) جهت کنترل بار سرور.
در حالت جستجو، چندین شرط LIKE بدون ایندکس باعث کاهش سرعت Query می‌شود.
پیشنهاد به ایندکس ترکیبی روی فیلدهای country و state در جداول ایستگاه‌ها.

وابستگی‌ها

use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Redis;
use App\Models\HotelTitle;
use App\Helpers\Functions;

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

کد خطا	شرح	منبع
400	Exception عمومی هنگام Query یا Decode	automationBaseData
1006	JWT منقضی یا نامعتبر	AuthWithJWT
500	Database connection/Redis read failed	V2BaseController

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

اعتبارسنجی فیلدهای ورودی به وسیلهٔ Request Validator داخلی.
اضافه‌کردن TTL به Cache‌های Redis برای جلوگیری از حافظهٔ بی‌انتها.
محدودسازی دسترسی به جدول‌های پایه فقط برای کاربران نوع base/operator.

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

استخراج Service Layer مجزا برای هر نوع دادهٔ پایه (BaseServiceSplit).
افزودن pagination واقعی با پارامتر page و size.
اعمال Cache invalidation زمانی با تغییر در جداول.
بهینه‌سازی کوئری LIKE با FullTextIndex برای جستجوی طبیعی‌تر.

ممیزی دسترسی و عدم قطعیت

هیچ log برای مشاهدهٔ این Route وجود ندارد.
پیشنهاد: افزودن audit طبقه‌بندی شده برای هر subject/table فراخوانی‌شده.
افزودن ردپا (traceId) در پاسخ JSON جهت تطبیق درخواست‌های داخلی.

جمع‌بندی

این endpoint یکی از بخش‌های زیرساختی برای بارگذاری داده‌های ثابت در پانل‌های اتوماسیون است. با حذف cache و اعتبارسنجی ناکافی ورودی، مستعد کندی و SQL Injection خفیف است. نرمال‌سازی منطق به سرویس مستقل و محدودسازی سطح دسترسی، پیش‌نیاز تبدیل آن به نسخهٔ enterprise-grade محسوب می‌شود.

Revision #1
Created 2025-11-22 10:05:03 UTC by Alireza
Updated 2025-11-22 13:20:11 UTC by Alireza