Skip to main content
#P1478

GET /api/v2/settings/index/{type}

Route Info

Method Endpoint Controller Middleware Purpose
GET /api/v2/settings/index/{type} V2BaseController@indexSettingsV2BaseController@settingsIndex authWithJwt دریافت تنظیمات شاخه، شامل کشور، استان و پیکربندی‌هایشهر دفترکارمربوط به شعبه، براساس نوع درخواستتنظیم (application، office، accounting، hub){type}.

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

تابع indexSettingssettingsIndex بر اساس پارامتر {type} نوع پیکربندی را تشخیصاز می‌دهدURL دریافت کرده و داده‌هایبر مربوطاساس بهآن، هرتنظیمات بخشاصلی شعبه را از پایگاهجدول دادهoffices می‌خواند. این تابع از یک switch-case یا نگاشت (Map) داخلی برای هدایت درخواست به منبع داده مناسب استفادهواکشی می‌کند. پارامتراگر مقدار branchtype کهبرابر با “branch” باشد، سه سطح داده جغرافیایی کشور، استان و شهر از درخواستجداول (معمولاًپایگاه‌داده از توکن JWT استخراجخوانده می‌شود یا در پارامترهای کوئری موجود است) دریافت می‌گردد، به عنوان کلید اصلی برای فیلتر کردن تنظیمات مربوط به آن شعبه خاص عمل می‌کند.شود:
  • درابتدا حالت application، جزئیات رابط‌های برنامه و مشخصات گرافیکی سیستم (مانند لوگوها، رنگ‌بندی‌های پیش‌فرض، تنظیمات UI/UX عمومی) برمی‌گردد. این داده‌ها معمولاً کمتر تغییر می‌کنند و می‌توانند کش شوند.
  • در حالت office، داده‌های مربوط به نمایندگی فعلی (آدرس، وضعیت فعال/غیرفعال بودن، تنظیمات سرویس‌های فعال، شماره‌های تماس پشتیبانی) واکشی می‌شود. این تنظیمات مختص به نهادرکورد شعبه جاری است.
  • در حالتاز accounting، اطلاعات مالی شاخه شامل base_onlineoffices (حداقل اعتبار لازم برای رزروهای مستقیم آنلاین)، credit_limit (حداکثر اعتبار مجاز دفتر)، و عناوین حسابداری (مانند کدهای استاندارد خدمات، سرفصل‌های مالی مورد استفاده در گزارش‌گیری) بازگرداندهواکشی می‌شود.
  • در حالتصورت داشتن مقدار hubcountry، داده‌هایتلاش مربوطمی‌کند بهداده تنظیماترا از Redis با کلید markupcountries:{id} برایبخواند؛ انواعدر سرویس‌هاصورت (system،نبود، charter،از airplus،DB accommodationبازیابی و other) نمایش دادهcache می‌شود. این تنظیمات اغلب شامل ضرایب افزایش قیمت یا تخفیف‌های ثابت سیستمی هستند. محاسبه markup معمولاً بر اساس فرمول زیر است: [ \text{Price}{\text{Final}} = \text{Price}{\text{Base}} \times (1 + \text{MarkupPercentage}) + \text{FixedFee} ]کند.
  • خروجیدر به‌صورتادامه state و city نیز از جداول ایالتی و شهری دریافت می‌شوند.
  • در پایان داده‌ها در قالب JSON شاملدارای بخش‌هایشناسه، تفکیک‌شدهنام (مانند application_config، office_data، financial، markup_rates)فارسی و زمانانگلیسی تولیدهر پاسخسطح دربرگردانده متادیتا (meta.timestamp) است.می‌شوند.

ورودی‌هاپارامترهای (Request Fields)ورودی

نام فیلدپارامتر نوع دادهمنبع الزامی توضیح
typestringURL Pathبلهنوع تنظیم مورد نیاز (مثلاً branch).
branch integerJWT Payload بله شناسه شعبه درخواست‌دهنده جهت واکشی دادهاطلاعات تنظیمات. این شناسه معمولاًمرتبط از JWTجدول استخراج شده و در صورت عدم وجود، خطا برمی‌گرداند.
typestring (enum)بلهنوع تنظیمات مورد درخواست (application, office, accounting, hub)offices. این پارامتر مسیر اصلی پردازش در کنترلر است.

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

GET /api/v2/settings/index/accounting?branch=101

Host: api.example.combranch
Authorization: Bearer {JWT_TOKEN}

توجه: در این مثال، branch به عنوان کوئری پارامتر ارسال شده است، اما ممکن است از مسیر (Path Parameter) یا توکن JWT نیز استخراج شود.

خروجی (Response)

فیلد نوع داده توضیح
country.title.fastringنام فارسی کشور
country.title.enstringنام انگلیسی کشور
state.title.fastringنام فارسی استان
city.title.fastringنام فارسی شهر
status boolean وضعیت موفقیت عملیات (true در صورت موفقیت).
meta.timestamp integer زمان یونیکستولید پاسخ (Timestamp) جهت بررسی تازگی داده.
detailsobjectداده‌های پیکربندی بسته به نوع درخواست (محتوای این شیء متغیر است).
financial.base_onlinefloatاعتبار پایه دفتر برای رزرو آنلاین (حداقل شارژ).
financial.credit_limitfloatسقف اعتبار کلی دفتر یا کاربری.
application.ui_themestringتم رابط کاربری انتخاب شده.یونیکس)

نمونه پاسخ (نوع accounting):موفق:

{
  "status": true,
  "settings": {
    "country": {
      "title": { "fa": "ایران", "en": "Iran" },
      "id": 118, "iso": "IR"
    },
    "state": {
      "id": 31,
      "title": { "fa": "یزد", "en": "Yazd" }
    },
    "city": {
      "id": 548,
      "title": { "fa": "احمدآباد", "en": "Ahmadabad" }
    }
  },
  "meta": { "timestamp": 1750669801, "path": "/api/v2/settings/index/accounting" },
"footer_announcements": "Accounting Tips: All payments must be settled within 48 hours.",
"financial": {
    "base_online": 2000000.00,
    "credit_limit": 10000000.00,
    "currency": "IRR",
    "bank": { 
        "name": "Mellat", 
        "iban": "IR12345678901234567890",
        "account_number": "1234567"1750668858 }
},
"system_defaults": {
    "default_tax_rate": 0.09
}
}

نکات امنیتی

  • دسترسیتأیید فقط از طریق JWT معتبر وهویت با احراز هویت کامل کاربر (میدل‌ورmiddleware authWithJwt الزامیانجام است).می‌شود.
  • پارامترنباید branchاجازه (چهداد درکاربران مسیرسایر و چه در کوئری) باید با شناسه مجاز کاربر احراز هویت شده تطابق داشته باشد (Authorization Check). دسترسیشعب به تنظیمات شعبه‌ای دیگر بدون داشتن دسترسی مدیریتیداشته ممنوع است.باشند.
  • در صورتنسخه استفادهفعلی، از نوع hub، داده‌های حساس مالی (Markupها) باید فقط برای نقش‌های دارایکنترل سطح دسترسی adminبین یا finance_manager بازگردانده شوند. برای نقش‌های operator باید دسترسی به این بخش محدود شود.
  • اعتبارسنجی ورودی‌هاشعبه‌ای (Input`branch Validation)cross-access`) برایپیاده‌سازی اطمیناننشده از اینکه {type} یکی از مقادیر مجاز است، حیاتی است تا از تزریق کدهای دیتابیسی جلوگیری شود (اگرچه استفاده از ORM این خطر را کاهش می‌دهد).است.

نکات عملکردی

  • Caching: در حالتهر درخواست سه کوئری به جداول hubcountries، حجم داده به‌دلیل ارسال لیست‌های markup برای چندین سرویس (که اغلب ثابت هستند) می‌تواند زیاد باشد. استفاده از Caching با Redis (با کلید مبتنی بر نوعstates و شناسهcities شعبه) با TTL (Time To Live) بین 1 تا 4 ساعت اکیداً پیشنهاداجرا می‌شود.
  • درپیشنهاد: حالتکش accounting،Redis اگربرای اطلاعاتهر حسابداریسه شاملسطح سرفصل‌هایبا زیادTTL باشد،حداقل اجرای6 هم‌زمانساعت.
    • کوئری‌های
  • درخواست متعددGET به جدولRedis accounting_titles باید با یک کوئری بهینه با استفادهقبل از JOINDB یا Eloquent eager loading تجمیع شود تا سربار دیتابیسبرای کاهش یابد.
  • TTL کش تنظیمات پایه: برای تنظیمات application و office که به ندرت تغییر می‌کنند، TTL کش باید بین 600 ثانیه (10 دقیقه) تا 1800 ثانیه (30 دقیقه) تنظیم شود.
  • استفاده از DB::table()->where(‘branch_id’, $branchId)->first() به جای کوئری‌های پیچیده در این Endpoint اولویت دارد.latency.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;: برای اجرای مستقیم کوئری‌های بهینه (در صورت نیاز).
  • use Illuminate\Support\Facades\Redis;
  • use Illuminate\Http\Request;: برای دسترسی به پارامترهای ورودی و بدنه درخواست.
  • use Carbon\Carbon;: برای مدیریت زمان و تولید Timestamp (در بخش متا).
  • use App\Services\CacheService;: برای مدیریت لایه کشینگ (Redis).
  • use Illuminate\Support\Facades\Auth;: برای استخراج اطلاعات کاربر احراز هویت شده از JWT.

کدهای خطا

کد HTTP شرح خطا منبع پردازشی
4011006 توکن JWT نامعتبر یا منقضی شده است authWithJwt Middleware
403دسترسی به تنظیمات شعبه مجاز نیستAuthorization Check (درون Controller)
4041002 نوع تنظیمات یافت نشد یا نامعتبر است (مثلاًتنظیم {type} =نامعتبر ‘billing’یا که تعریف پشتیبانی‌نشده است)است indexSettings(settingsIndex() Logic Switch
400پارامتر Branch یا Type در درخواست موجود نیستRequest Validation
500 خطا در واکشیاتصال به Redis یا پایگاه‌داده از پایگاه داده (مثلاً قطعی اتصال) DB facade / ORM ExecutionDB/Redis

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

  • جداسازیاضافه‌کردن RoleRole-based Validation برای اپراتورهای هر شعبه.
  • ثبت لاگ دسترسی به تنظیمات در Hub:SystemLog پیاده‌سازیبا چک دقیق Role-Based Access Control (RBAC) برای محتواینوع hubReadSettings. اگر کاربر نقش operator دارد، نباید ضرایب Markup سرور (System Markup) را مشاهده کند.
  • Auditافزودن Logging: ثبت هر درخواست موفق و ناموفق در جدول api_logs با جزئیات operator_id، branch_id، endpoint و response_time. نوع لاگRate-limit برای درخواست‌های موفقGET باید Info باشد.
  • Rate Limiting: افزودن محدودیت نرخ (Rate Limiting) به این مسیر (مثلاً 100 درخواست در هر 5 دقیقه) برای جلوگیریمتوالی از حملاتیک DDoS یا تلاش‌های مکرر برای خواندن داده‌های کش نشده.
  • Data Sanitization: اگرچه تنظیمات معمولاً از ورودی کاربر نمی‌آیند، اما اطمینان از عدم بازگرداندن اسکریپت‌های خطرناک در فیلدهای متنی (مانند footer_announcements) ضروری است.JWT.

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

  • تجمیعافزودن داده‌پشتیبانی از نوع‌های Hubتنظیم Markup: به جای واکشی جداگانه برای هر نوع سرویس در زمان درخواست، یک جدول واحد برای Markupها تعریف شود که شامل یک ستون نوعدیگر (Type) باشد. این امر سرعت واکشی را با یک کوئری بهبود می‌بخشد و مدیریت آن را آسان‌تر می‌کند.
  • Versioning Settings: افزودن مکانیزمی برای نسخه‌بندی تنظیمات (مثلاًhub، settings_versionapplication، office). هنگام تغییر، یک نسخه جدید ثبت شود و در صورت نیاز بتوان به نسخه‌های قبلی بازگشت (Rollback).
  • Endpointافزودن به‌روزرسانیساختار مجزا:Metadata اینشامل مسیرزمان صرفاًآخرین خواندنی است. پیشنهاد می‌شود برای مدیریت بهتر، endpoint‌های اختصاصی و امن برای بروزرسانی هر بخش (مثلاً PUT /api/v2/settings/update/accounting) ایجاد شود که فقط توسط مدیران سیستم قابل دسترسی باشند.بروزرسانی.
  • استفادهنمایش ازپرچم DTOها:یا تبدیلنماد داده‌های استخراج شده از DB به Data Transfer Objects (DTOs) قبل از ارسالکشور در پاسخ JSON برای تضمینUX ساختاربهتر یکپارچهدر خروجی.فرانت‌اند.

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

  • ثبت لاگ هر دسترسی موفق بایددرخواست در جدول system_auditssystem_log با فیلدهای user_idoperator_id، branch_id، action (‘READ_SETTING’)، و resource (‘settings/{type}’) ثبت گردد.
  • در صورتی که داده از کش (Cache Hit) بازگردانده شود، باید یک فیلد cache_status: HIT در متا اضافه شود. اگر از دیتابیس خوانده شود، cache_status: MISStype.
  • نوعسطح لاگ پیش‌فرض برای این Endpoint در Log Service بایدتوصیه‌شده: Info باشد،برای مگردرخواست‌های اینکهموفق خطا از سطح احراز هویت (401/403) باشد که بایدو Warning یابرای Errorشکست‌های در نظر گرفته شود.Redis.

جمع‌بندی

مسیر /settings/index/{type} نقطهٔ مرکزی برای واکشیدریافت داده‌های تنظیمات سیستمجغرافیایی شعبه استفاده می‌شود و یکی از پایه‌های ساخت فرم پیکربندی در سطوحداشبورد مختلفمدیریتی دفترکاراست. استضعف و نقش حیاتیاصلی در پایداریحال وحاضر سازگارینبود عملیاتتفکیک روزانهRole دارد.بین اینشعب مسیر ستون فقرات مدیریت پیکربندی‌هااست. در نسخه Enterprise محسوبنیاز می‌شود.است برایRedis پایداری بهترcaching و کاهشAudit سربار،log پیاده‌سازی مکانیزم Caching با Redis برای انواع hubفعال و application ضروری است. همچنین، کنترل دقیق نقش و سطح دسترسی (Roleدقیق Check)اعمال برایگردد جلوگیریتا ازفرایند افشایپاسخ‌دهی تنظیماتهم حساس مالی (بخش accountingسریع‌تر و hub)هم بهایمن‌تر کاربران غیرمجاز، بالاترین اولویت امنیتی در نگهداری این endpoint را دارد.شود.
Back to top