Skip to main content
#P1479

PUT /settings/index/{type}

Route Info

Method Endpoint Controller Middleware Purpose
PUT /api/v2/settings/index/{type} V2BaseController@settingsUpdate authWithJwt به‌روزرسانی تنظیمات شاخه موردنظر (نوع مشخص‌شده در پارامتر {type}) و ذخیره در دیتابیس مربوطه.

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

تابع settingsUpdate با دریافت {type} از URL مسیر، داده جدید تنظیمات شاخه (Branch) را بر اساس نوع تنظیم ذخیره می‌کند. منطق داخلی تابع بر پایه نوع تنظیم به سه شاخه تقسیم می‌شود:
  • type = "application" → بروزرسانی تنظیمات UI/Theme شعبه در جدول offices.
  • type = "accounting" → ثبت داده‌های مالی و محدودیت‌های اعتبار در جدول accounting_titles.
  • type = "hub" → به‌روزرسانی مارکاپ‌های سطحی در جدول hub_markups با استفاده از متد updateOrInsert().
در آخر، داده‌ها پس از تغییر در DB با کلید شعبه (branch) برمی‌گردند تا فرانت‌اند از صحت اعمال تغییرات اطمینان حاصل کند.

ورودی‌ها

نام پارامتر نوع داده منبع الزامی توضیح
type string URL Path بله نوع تنظیم موردنظر (application, accounting, hub).
branch integer JWT Payload بله شناسه شعبه فعال برای اعمال تنظیمات.
markups array Request Body اختیاری (در hub) آرایه دسته‌بندی مارکاپ‌ها در سطوح و نوع‌های مختلف پرواز و اقامت.
theme / style / base_color string Request Body اختیاری (در application) ویژگی‌های ظاهری واسط کاربری تنظیمات شعبه.

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

PUT /api/v2/settings/index/hub
Authorization: Bearer {JWT_TOKEN}
Content-Type: application/json

{
  "markups": {
    "flight": [
      {
        "level": 1,
        "markups": {
          "airplus": { "type": "percent", "value": 4, "discount": { "type": "percent", "value": 1 } },
          "accommodation": { "type": "currency", "value": 50000, "discount": { "type": "currency", "value": 0 } }
        }
      }
    ]
  }
}

خروجی (Response)

فیلد نوع داده توضیح
status boolean نتیجه موفقیت عملیات.
meta.timestamp integer زمان یونیکس پاسخ API.
updated object مقادیر تنظیمات بروزرسانی‌شده برای شعبه.

نمونه پاسخ موفق:

{
  "status": true,
  "updated": {
    "branch": 5,
    "type": "hub",
    "count": 4,
    "meta": {
      "timestamp": 1750668952
    }
  }
}

نکات امنیتی

  • فقط کاربران شعبه می‌توانند تنظیمات همان شعبه را تغییر دهند.
  • پارامتر branch باید از JWT خوانده شود نه از بدنه درخواست.
  • در مسیر PUT نباید مقادیر markups خالی ارسال شود — در غیر این صورت سطوح قبلی پاک می‌شوند.

نکات عملکردی

  • متد updateOrInsert() برای درج یا بروزرسانی رکوردهای hub_markups استفاده می‌شود — تعداد کوئری‌ها به ازای هر سطح برابر با تعداد آیتم‌های markups است.
  • پیشنهاد: فعال‌سازی کش Redis برای داده‌های UI شاخه (type=application).
  • بهتر است TTL کش برای داده‌های hub حداقل ۱۲ ساعت باشد، چون تنظیم مارکاپ‌ها کم‌تغییرند.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Carbon\Carbon;
  • use App\Http\Controllers\CronController;

کدهای خطا

کد شرح خطا منبع
404 نوع تنظیم {type} نامعتبر یا داده‌های ارسالی ناقص است. settingsUpdate()
500 خطا در اتصال به Redis یا در عملیات DB. DB Facade
400 درخواست فاقد احراز هویت JWT معتبر. authWithJwt Middleware

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

  • افزودن فیلتر سطح دسترسی بر اساس Role برای اپراتورها (مثلاً فقط مدیران شعبه بتوانند PUT انجام دهند).
  • ثبت عملیات تغییر تنظیمات در لاگ با سطح AdminWrite.
  • رمزنگاری مقادیر حساس در تنظیمات حسابداری.

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

  • تفکیک endpoint برای هر نوع تنظیم به صورت مستقل (مثلاً `/settings/hub`, `/settings/application`).
  • اضافه کردن Validation سمت سرور با Laravel Validation Rules برای هر بخش تنظیم.
  • افزودن خروجی diff-resolved جهت بررسی تغییرات هنگام بروزرسانی.

ممیزی و لاگ‌ها

  • ثبت لاگ با نوع UpdateSettings، شامل فیلدهای operator_id، branch_id، type و مقدار diff.
  • پیشنهاد سطح لاگ: Admin برای تغییرات نوع hub، Info برای application.

جمع‌بندی

مسیر PUT /settings/index/{type} مسئول بروزرسانی تنظیمات شاخه‌هاست و سه نوع تنظیمات سیستم Interface، مالی، و مرکز پرواز (hub) را شامل می‌شود. برای محیط‌های Production باید مکانیزم cache و audit دقیقی فعال شود تا عملکرد سریع و قابل‌ردگیری تضمین گردد.
Back to top