الإعدادات

يوفر FORGE نظام إعدادات تطبيق مدعوم بقاعدة البيانات مع دعم القيم المُنمّطة والتجميع والتشفير للبيانات الحساسة ونموذج ظهور عام/خاص. تُدار الإعدادات من خلال لوحة الإدارة وتُستهلك من الخلفية والواجهة الأمامية.

نظرة عامة

بدلاً من الاعتماد فقط على متغيرات البيئة أو ملفات الإعدادات، يخزن FORGE إعدادات التطبيق في قاعدة البيانات. هذا يُمكّن المسؤولين من تعديل سلوك التطبيق أثناء التشغيل من خلال واجهة الإدارة بدون إعادة النشر.

مخطط قاعدة البيانات

يخزن جدول settings جميع قيم الإعدادات:

العمود	النوع	الوصف
`id`	`UUID`	المفتاح الأساسي
`group_name`	`VARCHAR(100)`	فئة الإعداد (مثل `general`، `auth`، `email`)
`key`	`VARCHAR(100)`	معرّف الإعداد (فريد ضمن المجموعة)
`value`	`TEXT`	القيمة المُخزّنة (قد تكون مُشفّرة)
`type`	`VARCHAR(20)`	نوع القيمة: `string`، `boolean`، `number`، `json`، `encrypted`
`is_public`	`BOOLEAN`	ما إذا كان الإعداد يُكشف للـ API العام
`is_sensitive`	`BOOLEAN`	ما إذا كانت القيمة يجب إخفاؤها في واجهة الإدارة
`created_at`	`TIMESTAMP`	طابع زمني لإنشاء السجل
`updated_at`	`TIMESTAMP`	طابع زمني لآخر تحديث

مجموعات الإعدادات

الإعدادات مُنظّمة في مجموعات منطقية:

عام

المفتاح	النوع	الافتراضي	عام	الوصف
`app_name`	`string`	`"FORGE App"`	نعم	اسم عرض التطبيق
`app_url`	`string`	--	نعم	الرابط الأساسي للتطبيق
`timezone`	`string`	`"UTC"`	نعم	المنطقة الزمنية الافتراضية
`date_format`	`string`	`"YYYY-MM-DD"`	نعم	تنسيق عرض التاريخ

المصادقة

المفتاح	النوع	الافتراضي	عام	الوصف
`allow_registration`	`boolean`	`true`	نعم	ما إذا كان يمكن للمستخدمين الجدد التسجيل
`session_lifetime`	`number`	`1440`	لا	مدة الجلسة بالدقائق
`password_min_length`	`number`	`8`	نعم	الحد الأدنى لطول كلمة المرور
`require_email_verify`	`boolean`	`true`	لا	طلب التحقق من البريد الإلكتروني

البريد الإلكتروني

المفتاح	النوع	الافتراضي	عام	حساس	الوصف
`email_driver`	`string`	`"smtp"`	لا	لا	مزود البريد الإلكتروني
`email_host`	`string`	--	لا	لا	عنوان خادم SMTP
`email_port`	`number`	`587`	لا	لا	منفذ SMTP
`email_username`	`string`	--	لا	لا	اسم مستخدم SMTP
`email_password`	`encrypted`	--	لا	نعم	كلمة مرور SMTP
`email_encryption`	`string`	`"tls"`	لا	لا	طريقة التشفير
`email_from_name`	`string`	--	لا	لا	اسم عرض المُرسل
`email_from_address`	`string`	--	لا	لا	عنوان بريد المُرسل

التخزين

المفتاح	النوع	الافتراضي	عام	الوصف
`storage_driver`	`string`	`"local"`	لا	واجهة التخزين
`max_upload_size`	`number`	`10`	نعم	حد حجم الرفع بالميجابايت
`allowed_types`	`json`	--	نعم	أنواع MIME المسموحة للرفع

التشفير

الإعدادات ذات type = "encrypted" تُشفّر في التخزين باستخدام AES-256-GCM. يُوفّر مفتاح التشفير عبر متغير البيئة FORGE_ENCRYPTION_KEY.

┌─────────────────────────────────────────────────────┐
│                 مسار التشفير                         │
├─────────────────────────────────────────────────────┤
│                                                      │
│  قيمة نصية ──► تشفير AES-256-GCM ──► مُخزّنة        │
│                       │                              │
│              FORGE_ENCRYPTION_KEY                     │
│              (من البيئة)                              │
│                                                      │
│  قيمة مُخزّنة ──► فك تشفير AES-256-GCM ──► نصية     │
│                       │                              │
│              FORGE_ENCRYPTION_KEY                     │
│                                                      │
└─────────────────────────────────────────────────────┘

تحذير

يجب تعيين FORGE_ENCRYPTION_KEY في بيئتك قبل بدء التطبيق. إذا فُقد المفتاح، تصبح جميع الإعدادات المُشفّرة غير قابلة للاسترداد. احتفظ بنسخة احتياطية من هذا المفتاح بشكل آمن ولا تُدخله أبداً في التحكم بالإصدارات.

نصيحة

فقط الإعدادات التي تحتوي بيانات اعتماد أو أسرار يجب أن تستخدم نوع encrypted. الأمثلة الشائعة تشمل كلمات مرور SMTP ومفاتيح API السرية ورموز مزودي الدفع.

واجهة الإدارة

تُنظّم صفحة إعدادات الإدارة الإعدادات حسب المجموعة مع عناصر تحكم إدخال مناسبة:

String -- حقل إدخال نصي
Boolean -- مفتاح تبديل
Number -- إدخال رقمي مع تحقق
JSON -- محرر كود مع تمييز بناء الجملة
Encrypted -- حقل إدخال كلمة مرور (القيمة تُخفى بعد الحفظ)

الإعدادات الحساسة (حيث is_sensitive = true) تعرض قيمها كنقاط مُقنّعة في واجهة الإدارة. القيمة الفعلية تُكشف فقط عندما ينقر المسؤول صراحة للإظهار.

تحذير

الإعدادات المُشفّرة تُعرض كـ •••••••• في لوحة الإدارة. عند التحرير، يظهر الحقل فارغاً. إرسال قيمة فارغة لحقل مُشفّر يحافظ على القيمة الموجودة -- لا يمسحها.

API العام

نقطة نهاية الإعدادات العامة تُرجع فقط الإعدادات حيث is_public = true:

bash

GET /api/settings

مثال على الاستجابة

json

{
  "general": {
    "app_name": "تطبيقي",
    "app_url": "https://example.com",
    "timezone": "UTC"
  },
  "auth": {
    "allow_registration": true,
    "password_min_length": 8
  },
  "storage": {
    "max_upload_size": 10,
    "allowed_types": ["image/jpeg", "image/png", "application/pdf"]
  }
}

نصيحة

الإعدادات الخاصة (بيانات اعتماد قاعدة البيانات، مفاتيح API، الإعدادات الداخلية) لا تُكشف أبداً من خلال API العام، بغض النظر عن دور المستخدم الطالب.

الاستخدام في الخلفية

rust

// Get a typed setting value
let app_name: String = settings_service.get("general", "app_name").await?;
let session_lifetime: i64 = settings_service.get("auth", "session_lifetime").await?;
let allow_reg: bool = settings_service.get("auth", "allow_registration").await?;

// Get an encrypted setting (automatically decrypted)
let smtp_password: String = settings_service.get("email", "email_password").await?;

// Update a setting
settings_service.set("general", "app_name", "New App Name").await?;

الإعدادات ​

نظرة عامة ​

مخطط قاعدة البيانات ​

مجموعات الإعدادات ​

عام ​

المصادقة ​

البريد الإلكتروني ​

التخزين ​

التشفير ​

واجهة الإدارة ​

API العام ​

مثال على الاستجابة ​

الاستخدام في الخلفية ​