# POST /api/v2/titles/list

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/v2/titles/list</td><td style="direction: ltr; text-align: left;">V2BaseController@baseAutomationData</td><td style="direction: ltr; text-align: left;">authWithJwt</td><td style="direction: rtl; text-align: right;">دریافت لیست عنوان‌های ثابت یا داده‌های ساختاری جدول‌های پایه مانند room\_type، room\_rate و room\_view</td></tr></tbody></table>

</div>### منطق عملکرد تابع

<div id="bkmrk-function-logic-content" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify;">تابع **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`.

</div>### ورودی‌ها (Request Fields)

<div id="bkmrk-input-table" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام فیلد</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>table</td><td>string</td><td>بله</td><td>نام جدول در دیتابیس (فقط `hotel_title` در حال حاضر)</td></tr><tr><td>action</td><td>string</td><td>بله</td><td>زیرعملیات مربوط به جدول (مقادیر: `room_type`، `room_rate`، `room_view`)</td></tr></tbody></table>

</div>#### نمونه درخواست:

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

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

### خروجی (Response)

<table border="1" cellpadding="6" cellspacing="0" id="bkmrk-%D9%81%DB%8C%D9%84%D8%AF-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%AA%D9%88%D8%B6%DB%8C%D8%AD-" style="margin: 15px auto; width: 97%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>فیلد</td><td>نوع داده</td><td>توضیح</td></tr><tr><td>status</td><td>boolean</td><td>وضعیت کلی درخواست</td></tr><tr><td>time</td><td>integer</td><td>زمان واکنش سرور</td></tr><tr><td>data.titles\[\]</td><td>array</td><td>لیست عنوان‌های ثابت با فیلدهای زبان، وضعیت و ویژگی‌ها</td></tr></tbody></table>

#### نمونه پاسخ:

```
{
  "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

<table border="1" cellpadding="6" cellspacing="0" id="bkmrk-%DA%A9%D8%AF-%D8%AE%D8%B7%D8%A7-%D8%B4%D8%B1%D8%AD-%D9%85%D9%86%D8%A8%D8%B9-400-" style="margin: 15px auto; width: 90%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد خطا</td><td>شرح</td><td>منبع</td></tr><tr><td>400</td><td>Database Exception → Trace بازگردانده می‌شود.</td><td>baseAutomationData</td></tr><tr><td>1006</td><td>JWT token منقضی یا نامعتبر.</td><td>AuthWithJWT</td></tr></tbody></table>

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

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

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

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

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

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

### جمع‌بندی

<div id="bkmrk-%D8%A7%DB%8C%D9%86-endpoint-%D9%85%D8%B3%DB%8C%D8%B1-%D8%A7%D8%B5" style="direction: rtl; text-align: justify;">این Endpoint مسیر اصلی دریافت عنوان‌های پارامتری در سیستم اتوماسیون است. ساختار ساده و خروجی یکسان باعث سهولت مصرف در فرانت‌اند می‌شود، اما عدم وجود validation و cache منجر به ضعف امنیت و Performance در حجم بالا خواهد شد. توصیه می‌شود Refactor در لایهٔ Service و اعمال TTL روی داده‌های ثابت انجام گیرد.</div>