#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 فعال و کنترل سطح دسترسی دقیق اعمال گردد تا فرایند پاسخ‌دهی هم سریع‌تر و هم ایمن‌تر شود.

Revision #2
Created 2025-11-22 13:40:57 UTC by Alireza
Updated 2025-11-22 13:45:01 UTC by Alireza