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@settingsIndex authWithJwt دریافت تنظیمات شاخه، شامل کشور، استان و شهر مربوط به شعبه، براساس نوع تنظیم {type}.

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

تابع settingsIndex پارامتر {type} را از URL دریافت کرده و بر اساس آن، تنظیمات اصلی شعبه را از جدول offices واکشی می‌کند. اگر مقدار type برابر با “branch” باشد، سه سطح داده جغرافیایی کشور، استان و شهر از جداول پایگاه‌داده خوانده می‌شود:
  • ابتدا رکورد شعبه از offices واکشی می‌شود.
  • در صورت داشتن مقدار country، تلاش می‌کند داده را از Redis با کلید countries:{id} بخواند؛ در صورت نبود، از DB بازیابی و cache می‌کند.
  • در ادامه state و city نیز از جداول ایالتی و شهری دریافت می‌شوند.
  • در پایان داده‌ها در قالب JSON دارای شناسه، نام فارسی و انگلیسی هر سطح برگردانده می‌شوند.

پارامترهای ورودی

نام پارامتر نوع داده منبع الزامی توضیح
type string URL Path بله نوع تنظیم مورد نیاز (مثلاً branch).
branch integer JWT Payload بله شناسه شعبه جهت واکشی اطلاعات مرتبط از جدول offices.

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

GET /api/v2/settings/index/branch
Authorization: Bearer {JWT_TOKEN}

خروجی (Response)

فیلد نوع داده توضیح
country.title.fa string نام فارسی کشور
country.title.en string نام انگلیسی کشور
state.title.fa string نام فارسی استان
city.title.fa string نام فارسی شهر
status boolean وضعیت موفقیت عملیات
meta.timestamp integer زمان تولید پاسخ (یونیکس)

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

{
  "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": 1750668858 }
}

نکات امنیتی

  • تأیید هویت با middleware authWithJwt انجام می‌شود.
  • نباید اجازه داد کاربران سایر شعب به تنظیمات شعبه‌ای دسترسی داشته باشند.
  • در نسخه فعلی، کنترل سطح دسترسی بین شعبه‌ای (`branch cross-access`) پیاده‌سازی نشده است.

نکات عملکردی

  • در هر درخواست سه کوئری به جداول countries، states و cities اجرا می‌شود.
  • پیشنهاد: کش Redis برای هر سه سطح با TTL حداقل 6 ساعت.
  • درخواست GET به Redis قبل از DB برای کاهش latency.

وابستگی‌ها

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use Illuminate\Http\Request;
  • use Carbon\Carbon;

کدهای خطا

کد شرح خطا منبع
1006 توکن JWT نامعتبر یا منقضی شده authWithJwt
1002 نوع تنظیم {type} نامعتبر یا پشتیبانی‌نشده است settingsIndex()
500 خطا در اتصال به Redis یا پایگاه‌داده DB/Redis

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

  • اضافه‌کردن Role-based Validation برای اپراتورهای هر شعبه.
  • ثبت لاگ دسترسی به تنظیمات در SystemLog با نوع ReadSettings.
  • افزودن Rate-limit برای درخواست‌های GET متوالی از یک JWT.

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

  • افزودن پشتیبانی از نوع‌های تنظیم دیگر (hub، application، office).
  • افزودن ساختار Metadata شامل زمان آخرین بروزرسانی.
  • نمایش پرچم یا نماد کشور در پاسخ برای UX بهتر در فرانت‌اند.

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

  • ثبت لاگ هر درخواست در جدول system_log با فیلدهای operator_id، branch_id و type.
  • سطح لاگ توصیه‌شده: Info برای درخواست‌های موفق و Warning برای شکست‌های Redis.

جمع‌بندی

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