جداول البحث

يوفر FORGE نظام جداول بحث عام لإدارة البيانات المرجعية من نوع مفتاح-قيمة المستخدمة في جميع أنحاء تطبيقك. تُدير جداول البحث القوائم المنسدلة ونصوص الحالة وقوائم التصنيفات وأي مجموعة قيم معيارية أخرى يحتاج المسؤولون لإدارتها بدون تغييرات في الكود.

نظرة عامة

بدلاً من كتابة قيم enum مباشرة في الكود أو إنشاء جداول منفصلة لكل قائمة منسدلة، يخزن نظام البحث جميع البيانات المرجعية في جدول واحد مُجمّع حسب type. يمكن للمسؤولين إضافة وتحرير وترجمة وإعادة ترتيب القيم من خلال لوحة الإدارة.

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

يخزن جدول lookups جميع القيم المرجعية:

العمود	النوع	الوصف
`id`	`UUID`	المفتاح الأساسي
`type`	`VARCHAR(100)`	اسم المجموعة (مثل `status`، `priority`)
`key`	`VARCHAR(100)`	معرّف قابل للقراءة آلياً
`value`	`VARCHAR(255)`	قيمة العرض القابلة للقراءة بشرياً
`translations`	`JSONB`	القيم المترجمة حسب اللغة
`is_active`	`BOOLEAN`	ما إذا كانت هذه القيمة متاحة للاختيار
`sort_order`	`INTEGER`	ترتيب العرض ضمن مجموعة النوع
`created_at`	`TIMESTAMP`	طابع زمني لإنشاء السجل
`updated_at`	`TIMESTAMP`	طابع زمني لآخر تحديث

مثال على البيانات

┌──────────┬────────────┬──────────────┬─────────────┐
│   type   │    key     │    value     │ sort_order  │
├──────────┼────────────┼──────────────┼─────────────┤
│ status   │ active     │ نشط          │ 1           │
│ status   │ inactive   │ غير نشط      │ 2           │
│ status   │ pending    │ قيد الانتظار │ 3           │
│ priority │ low        │ منخفض        │ 1           │
│ priority │ medium     │ متوسط        │ 2           │
│ priority │ high       │ عالي         │ 3           │
│ priority │ critical   │ حرج          │ 4           │
│ category │ blog       │ مقال مدونة   │ 1           │
│ category │ news       │ خبر          │ 2           │
│ category │ tutorial   │ شرح تعليمي   │ 3           │
└──────────┴────────────┴──────────────┴─────────────┘

بنية كائن الترجمات

json

{
  "en": { "value": "Active" },
  "ar": { "value": "نشط" },
  "fr": { "value": "Actif" }
}

نقاط نهاية API

الطريقة	المسار	الوصف
`GET`	`/api/lookups?type=status`	استرجاع جميع القيم النشطة لنوع محدد

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

json

[
  {
    "id": "uuid-1",
    "type": "status",
    "key": "active",
    "value": "نشط",
    "sort_order": 1
  },
  {
    "id": "uuid-2",
    "type": "status",
    "key": "inactive",
    "value": "غير نشط",
    "sort_order": 2
  },
  {
    "id": "uuid-3",
    "type": "status",
    "key": "pending",
    "value": "قيد الانتظار",
    "sort_order": 3
  }
]

نصيحة

تُرجع API فقط القيم حيث is_active = true، مُرتّبة حسب sort_order. يتم إرجاع القيم المترجمة تلقائياً بناءً على رأس Accept-Language في الطلب.

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

توفر لوحة الإدارة واجهة إدارة مُجمّعة:

قائمة الأنواع -- عرض جميع أنواع البحث مع عدد القيم في كل نوع
إدارة القيم -- إضافة وتحرير وإعادة ترتيب وتعطيل القيم ضمن نوع
محرر الترجمة -- ترجمة القيم لكل لغة نشطة
الإجراءات المجمعة -- تفعيل أو تعطيل قيم متعددة دفعة واحدة

إنشاء نوع بحث جديد

لإضافة نوع بحث جديد، أنشئ ببساطة قيمة باسم type جديد. يُجمّع النظام القيم تلقائياً حسب نوعها.

تحذير

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

الاستخدام في كود التطبيق

الخلفية

rust

// Get all active statuses
let statuses = lookup_service.get_by_type("status").await?;

// Get a single value by type and key
let status = lookup_service.get_by_type_and_key("status", "active").await?;

الواجهة الأمامية

tsx

// Use lookup to populate a dropdown
const { data: statuses } = useLookups("status");

<select>
  {statuses?.map((item) => (
    <option key={item.key} value={item.key}>
      {item.value}
    </option>
  ))}
</select>

حالات الاستخدام الشائعة

النوع	الغرض
`status`	حالات السجل (نشط، غير نشط، إلخ.)
`priority`	مستويات الأولوية للتذاكر أو المهام
`category`	تصنيفات المحتوى أو المنتجات
`country`	قائمة الدول لنماذج العناوين
`currency`	العملات المدعومة
`gender`	خيارات الجنس للملفات الشخصية
`department`	الأقسام التنظيمية

نصيحة

يتم تخزين البحث مؤقتاً في الخلفية. بعد تحديث القيم من خلال لوحة الإدارة، يتم إلغاء التخزين المؤقت تلقائياً حتى تسري التغييرات فوراً.

جداول البحث ​

نظرة عامة ​

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

مثال على البيانات ​

بنية كائن الترجمات ​

نقاط نهاية API ​

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

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

إنشاء نوع بحث جديد ​

الاستخدام في كود التطبيق ​

الخلفية ​

الواجهة الأمامية ​

حالات الاستخدام الشائعة ​