انتقل إلى المحتوى الرئيسي

المقدمة

🎯 ماذا يفعل هذا الموديل؟​

يتيح لك موديل Users إدارة المستخدمين المسجلين. في منصة OneEntry، توجد الأدوات اللازمة للعمل مع المستخدمين المسجلين.

📖 شرح بسيط​

تحتاج كل تطبيق إلى إدارة المستخدمين:

  • 📝 ملفات تعريف المستخدمين - إدارة معلومات المستخدم
  • 💾 بيانات المستخدم المخصصة - تخزين البيانات الخاصة بالتطبيق (كائن الحالة)
  • 🔍 بحث المستخدم - البحث وتصنيف المستخدمين

✨ المفاهيم الأساسية​

ما هو المستخدم؟​

المستخدم هو حساب مسجل في تطبيقك:

  • المعلومات الأساسية - الاسم، البريد الإلكتروني، الهاتف
  • المصادقة - تخزين كلمات المرور بشكل آمن
  • كائن الحالة - بيانات التطبيق المخصصة
  • الطوابع الزمنية - تاريخ التسجيل، آخر تسجيل دخول
  • الحالة - نشط، غير نشط، محظور
  • الأذونات - أدوار المستخدمين ومستويات الوصول

هيكل المستخدم​

كل مستخدم له هذا الهيكل:

{
  id: 8,                                    // معرف المستخدم
  identifier: 'test@test.ru',               // معرف المستخدم (البريد الإلكتروني/تسجيل الدخول)
  authProviderIdentifier: 'email',          // نوع مزود المصادقة
  formIdentifier: 'reg',                    // معرف نموذج التسجيل
  formData: [                               // بيانات ملف تعريف المستخدم
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // مجموعات المستخدم لأغراض الأذونات
  state: {},                                // بيانات التطبيق المخصصة
  moduleFormConfigs: [],                    // تكوينات إضافية للنموذج
  total: "1"                                // العدد الإجمالي (لأغراض الترقيم)
}

الحقول الرئيسية:

  • id - معرف المستخدم الفريد
  • identifier - تسجيل دخول المستخدم (البريد الإلكتروني، الهاتف، اسم المستخدم)
  • authProviderIdentifier - طريقة المصادقة المستخدمة (البريد الإلكتروني، الهاتف، إلخ)
  • formData - مصفوفة من حقول النموذج بمعلومات ملف تعريف المستخدم
  • groups - مصفوفة من معرفات المجموعات للتحكم في الوصول
  • state - كائن JSON مخصص لبيانات التطبيق

الحصول على المستخدم مع بيانات الحالة المخصصة​

الفوائد:

  • 🔒 آمن - تشفير كلمات المرور، مصادقة آمنة
  • 📋 مُعتمد - التحقق من البريد الإلكتروني والبيانات
  • 🔄 مُصادق - جلسات تعتمد على الرموز
  • 💾 مستمر - البيانات مخزنة في قاعدة البيانات

كائن حالة المستخدم​

يمكنك تخزين البيانات اللازمة لعمل تطبيقك في كائن الحالة. عند تغيير المستخدم، أضف البيانات اللازمة إلى الحالة. عندما يتم استلام بيانات المستخدم لاحقًا، ستحتوي على كائن الحالة.

مثال نضيف فيه معلومات إلى المستخدم حول عدد الطلبات التي قام بها. أضف حقل "orderCount" بالقيمة إلى كائن الحالة.

كائن الحالة هو تخزين بيانات مخصص لكل مستخدم:

حالة الاستخداممثال الحالةالوصف
التجارة الإلكترونية{ orderCount: 5, totalSpent: 499.99 }تتبع تاريخ الشراء
موقع المحتوى{ articlesRead: 25, bookmarks: [1,2,3] }تتبع استهلاك المحتوى
تطبيق اجتماعي{ postsCount: 42, followers: 150 }تتبع المقاييس الاجتماعية
الألعاب{ level: 15, score: 9500, achievements: [...] }تتبع تقدم اللعبة
SaaS{ plan: 'premium', usage: 75 }تتبع بيانات الاشتراك

سير عمل المستخدم​

1. يقوم المستخدم بملء نموذج التسجيل
   (البريد الإلكتروني، كلمة المرور، الاسم)
   ↓
2. يتم استدعاء createUser()
   (تقوم OneEntry بالتحقق من صحة كلمة المرور وتشفيرها)
   ↓
3. تم إنشاء حساب المستخدم
   (يتم تخزينه في قاعدة البيانات)
   ↓
4. يقوم المستخدم بتسجيل الدخول
   (تتحقق authenticateUser() من بيانات الاعتماد)
   ↓
5. يتم إرجاع رمز المصادقة
   (يستخدم للطلبات اللاحقة)
   ↓
6. يقوم التطبيق بتحديث حالة المستخدم
   (بيانات مخصصة مثل orderCount)
   ↓
7. يتم جلب بيانات المستخدم حسب الحاجة
   (getUserById() مع الحالة الحالية)

لماذا تستخدم موديل المستخدمين؟​

الفائدةالوصف
مصادقة آمنةتشفير كلمات المرور، إدارة الرموز
إدارة المستخدمينقراءة، تحديث، حذف المستخدمين
تخزين بيانات مخصصةكائن الحالة لبيانات التطبيق المخصصة
التحقق من البريد الإلكترونيالتحقق التلقائي من تنسيق البريد الإلكتروني
منع التكراريمنع تسجيل البريد الإلكتروني المكرر
إدارة الجلساتمصادقة تعتمد على الرموز

📋 ما تحتاج إلى معرفته​

مزود المصادقة​

يتم إدارة المستخدمين في OneEntry من خلال نظام مزود المصادقة الذي يتعامل مع آليات التسجيل والمصادقة.

النقاط الرئيسية:

  • يسجل المستخدمون من خلال النماذج المكونة في لوحة إدارة OneEntry
  • يرتبط كل مستخدم بمزود مصادقة (البريد الإلكتروني، الهاتف، إلخ)
  • يتم تخزين بيانات المستخدم في حقول النموذج المحددة بواسطة formData
  • يتم تخزين بيانات التعريف الإضافية في كائن state

كائن حالة المستخدم مرن​

يمكن أن يخزن كائن الحالة أي بيانات JSON مخصصة

أفضل الممارسات:

  • تخزين البيانات الخاصة بالتطبيق فقط
  • الحفاظ على تنظيم كائن الحالة مع الكائنات المتداخلة
  • تحديث كائن الحالة بالكامل (نشر البيانات الموجودة)
  • عدم تخزين البيانات الحساسة في الحالة

أمان كلمة المرور​

تتعامل OneEntry مع أمان كلمة المرور تلقائيًا

مسؤوليتك:

  • فرض متطلبات كلمة المرور (الطول، التعقيد)
  • التحقق من كلمة المرور على جانب العميل قبل الإرسال
  • عدم تسجيل كلمات المرور
  • استخدام HTTPS لجميع طلبات المصادقة

إدارة رموز المصادقة​

قم بتخزين واستخدام رموز المصادقة بشكل آمن

أفضل الممارسات للرموز:

  • التخزين في ملفات تعريف الارتباط HTTP-only عند الإمكان
  • استخدام أوقات انتهاء قصيرة (1-2 ساعة)
  • تنفيذ رموز التحديث للجلسات الطويلة
  • مسح الرمز عند تسجيل الخروج
  • عدم كشف الرموز في عناوين URL

التحقق من تسجيل المستخدم​

تحقق دائمًا من إدخال المستخدم قبل التسجيل

تحديث حالة المستخدم بأمان​

احفظ دائمًا الحالة الحالية عند التحديث:

// ❌ سيء - يكتب الحالة بالكامل
const userstate = {
  orderCount: 1
}

// ✅ جيد - يحفظ الحالة الحالية
const userstate = {
  ...user.state, // نشر الحالة الحالية
  orderCount: (user.state.orderCount || 0) + 1  // تحديث حقل محدد
}

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

تمنع OneEntry تسجيل البريد الإلكتروني المكرر تلقائيًا

أفضل ممارسة: تحقق من حالة الخطأ وقدم رسالة سهلة الفهم للمستخدم.

ترقيم المستخدمين​

للقواعد الكبيرة من المستخدمين، قم دائمًا بترقيم عند جلب عدة مستخدمين

💡 ملاحظات مهمة​

المصادقة مطلوبة​

تتطلب معظم طرق المستخدمين مصادقة من خلال موديل AuthProvider. تأكد من مصادقة المستخدم أولاً قبل استدعاء طرق إدارة المستخدمين.

بيانات نموذج المستخدم​

تكون بيانات المستخدم منظمة وفقًا للنماذج المكونة في لوحة إدارة OneEntry:

  • لكل مستخدم معرف formIdentifier يشير إلى نموذج التسجيل المستخدم
  • يتم تخزين بيانات المستخدم في مصفوفة formData مع علامات، أنواع، وقيم
  • تشمل أنواع الحقول المدعومة: سلسلة، عدد صحيح، عدد عشري، تاريخ، تاريخ ووقت، وقت، نص، نص مع رأس، صورة، مجموعة من الصور، ملف، زر اختيار، قائمة، كيان، فترة زمنية

إرشادات كائن الحالة​

أفضل الممارسات لكائن الحالة:

  • تخزين البيانات الخاصة بالتطبيق فقط
  • الحفاظ على تنظيم الحالة مع الكائنات المتداخلة
  • تحديث الحالة بالكامل (نشر البيانات الموجودة)
  • عدم تخزين البيانات الحساسة (كلمات المرور، الرموز)
  • عدم تخزين بيانات ثنائية كبيرة
  • استخدام تسميات متسقة

إشعارات الدفع​

استخدم addFCMToken() و deleteFCMToken() لإدارة رموز Firebase Cloud Messaging لإرسال إشعارات الدفع إلى المستخدمين.

بيانات الإشعار​

عند تحديث المستخدمين، يمكنك تقديم كائن notificationData يحتوي على:

  • email - عنوان البريد الإلكتروني للإشعارات
  • phonePush - مصفوفة من أرقام الهواتف لإشعارات الدفع
  • phoneSMS - رقم الهاتف لإشعارات SMS

📊 جدول مرجعي سريع​

الطريقةالوصفحالة الاستخدام
getUser()الحصول على بيانات المستخدم المصرح بهجلب ملف تعريف المستخدم الحالي
updateUser()تحديث معلومات المستخدمتحديثات الملف الشخصي، تغييرات الحالة
archiveUser()أرشفة حساب المستخدمحذف ناعم لحساب المستخدم
deleteUser()حذف المستخدم بشكل دائمحذف نهائي لحساب المستخدم
addFCMToken()إضافة رمز FCM لإشعارات الدفعتمكين إشعارات الدفع
deleteFCMToken()إزالة رمز FCMتعطيل إشعارات الدفع

❓ الأسئلة الشائعة​

ما هو كائن حالة المستخدم وكيف يجب أن أستخدمه؟​

كائن الحالة هو تخزين JSON مرن لبيانات المستخدم الخاصة بالتطبيق. استخدمه لتتبع مقاييس مخصصة مثل عدد الطلبات، التفضيلات، أو التقدم. احرص دائمًا على نشر الحالة الموجودة عند التحديث لتجنب الكتابة فوق بيانات أخرى.

كيف يمكنني تحديث معلومات ملف تعريف المستخدم؟​

استخدم updateUser() لتعديل بيانات ملف تعريف المستخدم. يمكنك تحديث حقول بيانات النموذج، إعدادات الإشعارات، وكائن الحالة. تذكر أن تقوم بمصادقة المستخدم أولاً باستخدام موديل AuthProvider.

ما الفرق بين archiveUser() و deleteUser()؟​

archiveUser() هو حذف ناعم يخفي المستخدم ولكنه يحتفظ بالبيانات (يمكن استعادته). deleteUser() يزيل المستخدم بشكل دائم وجميع البيانات المرتبطة (لا يمكن التراجع عنه). استخدم الأرشفة ما لم تكن بحاجة إلى إزالة البيانات بالكامل.

كيف يمكنني التعامل مع إشعارات الدفع للمستخدمين؟​

استخدم addFCMToken() لتسجيل رمز Firebase Cloud Messaging للمستخدم. هذا يمكّن من إرسال إشعارات الدفع إلى أجهزتهم. استخدم deleteFCMToken() عندما يقومون بتسجيل الخروج أو تعطيل الإشعارات.

هل يمكنني تخزين بيانات حساسة في كائن حالة المستخدم؟​

لا! لا تقم أبدًا بتخزين كلمات المرور، الرموز، أرقام بطاقات الائتمان، أو أي بيانات حساسة أخرى في كائن الحالة. ليس مشفرًا خصيصًا للبيانات الحساسة. استخدم أنظمة آمنة ومخصصة للمعلومات الحساسة.

كيف يمكنني جلب بيانات المستخدم بعد التسجيل؟​

بعد التسجيل الناجح والمصادقة، استخدم getUser() لجلب بيانات المستخدم المصرح به، بما في ذلك معلومات ملف تعريفه وكائن الحالة المخصص.

🎓 أفضل الممارسات​

  • تحقق من الإدخال قبل التسجيل - تحقق من تنسيق البريد الإلكتروني، قوة كلمة المرور
  • استخدم HTTPS للمصادقة - تشفير جميع طلبات تسجيل الدخول
  • تنفيذ متطلبات كلمة المرور - الحد الأدنى 8 أحرف، حالة مختلطة، أرقام
  • تخزين الرموز بشكل آمن - ملفات تعريف الارتباط HTTP-only أو التخزين الآمن
  • الحفاظ على الحالة الحالية - نشر البيانات الموجودة عند تحديث الحالة
  • التعامل مع البريد الإلكتروني المكرر - التقاط أخطاء 409 وعرض رسالة سهلة الفهم
  • تنفيذ تسجيل الخروج - مسح الرموز وبيانات الجلسة
  • تخزين بيانات المستخدم في الذاكرة المؤقتة - تقليل استدعاءات API للمستخدمين الذين يتم الوصول إليهم بشكل متكرر

مزيد من المعلومات حول إدارة المستخدمين في لوحة إدارة OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/category/users

تعريف موديل المستخدمين​


const { Users } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

🔗 الوثائق ذات الصلة​