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

مقدمة

إدارة المستخدمين المسجلين — استرجاع الملفات الشخصية، تحديث البيانات، والتعامل مع حالة الحساب.

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

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

يدير موديل Users المستخدم المصادق عليه بالفعل: استرجاع الملف الشخصي، تحديث بيانات النموذج وكائن state المخصص، أرشفة أو حذف الحساب، إدارة سلة التسوق وقائمة الرغبات لكل مستخدم (أو ضيف)، وتسجيل رموز FCM لإشعارات الدفع.

التسجيل وتسجيل الدخول غير موجودين هنا — إنهما موجودان في موديل AuthProvider. يعمل موديل Users مع المستخدم الذي تم تفويضه بالفعل بواسطة AuthProvider.

🚀 بدء سريع​

قم بتهيئة الموديل من defineOneEntry:


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

استرجع المستخدم الحالي وقم بتحديث كائن state المخصص له (يفترض وجود جلسة مصادق عليها — انظر AuthProvider):

// Fetch the authorized user's profile and state.
const user = await Users.getUser("en_US");

console.log(user.id, user.identifier);

// Update the user, preserving existing state.
await Users.updateUser({
  formIdentifier: user.formIdentifier,
  formData: user.formData,
  state: { ...user.state, orderCount: (user.state.orderCount || 0) + 1 },
});

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

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

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

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

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

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

{
  id: 8,                                    // User ID
  identifier: 'test@test.ru',               // User identifier (email/login)
  authProviderIdentifier: 'email',          // Auth provider type
  formIdentifier: 'reg',                    // Registration form identifier
  formData: [                               // User profile data
    { marker: 'name_reg', type: 'string', value: 'Ivan' },
    { marker: 'phone_reg', type: 'string', value: '+19258382556' },
  ],
  groups: [1],                              // User groups for permissions
  state: {},                                // Custom application data
  moduleFormConfigs: [],                    // Additional form configurations
}

كائن الحالة​

يمكنك تخزين أي بيانات خاصة بالتطبيق في كائن state الخاص بكل مستخدم. عند تحديث المستخدم، أضف البيانات التي تحتاجها إلى state؛ ستعيد استدعاءات getUser() اللاحقة هذه البيانات.

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

احرص دائمًا على الحفاظ على الحالة الحالية عند التحديث — قم بتوزيعها حتى لا تفقد حقولًا أخرى:

// ❌ Bad - overwrites the entire state
const state = { orderCount: 1 };

// ✅ Good - preserve existing state
const state = {
  ...user.state,
  orderCount: (user.state.orderCount || 0) + 1,
};

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

يتطلب تفويض​

كل طريقة مستخدم تتطلب جلسة مصادق عليها — قم بمصادقة المستخدم أولاً من خلال موديل AuthProvider. تعمل طرق السلة وقائمة الرغبات أيضًا للـ ضيوف (انظر قسم السلة وقائمة الرغبات أدناه).

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

تتبع بيانات ملف المستخدم النماذج المكونة في لوحة تحكم OneEntry:

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

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

  • قم بتخزين البيانات الخاصة بالتطبيق فقط؛ لا تضع كلمات المرور، الرموز، أو بيانات البطاقة في state.
  • حافظ على تنظيمها باستخدام كائنات متداخلة وأسماء متسقة.
  • قم بالتحديث عن طريق توزيع state الحالي (انظر أعلاه) — لا تكتب فوقه بشكل أعمى.

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

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

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

التصفح​

للقوائم الخاصة بالسلة / قائمة الرغبات ومجموعات أخرى، قم بالتصفح عبر النتائج بدلاً من تحميل كل شيء دفعة واحدة.

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

الطريقةالوصفحالة الاستخدام
getUser() 🔐الحصول على بيانات المستخدم المصرح بهاسترجاع ملف المستخدم الحالي
updateUser() 🔐تحديث معلومات المستخدمتحديثات الملف الشخصي، تغييرات الحالة
archiveUser() 🔐أرشفة حساب المستخدمحذف ناعم لحساب المستخدم
deleteUser() 🔐حذف المستخدم بشكل دائمحذف قاسي لحساب المستخدم
addFCMToken() 🔐إضافة رمز FCM لإشعارات الدفعتفعيل إشعارات الدفع
deleteFCMToken() 🔐إزالة رمز FCMتعطيل إشعارات الدفع
getCart()الحصول على سلة المستخدم أو الضيفقراءة السلة الحالية
setCart()استبدال السلة بالكاملمزامنة سلة جانب العميل
addCartItem()إضافة عنصر إلى السلةإجراء "إضافة إلى السلة"
removeCartItem()إزالة عنصر من السلةإجراء "إزالة من السلة"
getWishlist()الحصول على قائمة رغبات المستخدم أو الضيفقراءة قائمة الرغبات الحالية
setWishlist()استبدال قائمة الرغبات بالكاملمزامنة قائمة رغبات جانب العميل
addWishlistItem()إضافة عنصر إلى قائمة الرغباتإجراء "إضافة إلى قائمة الرغبات"
removeWishlistItem()إزالة عنصر من قائمة الرغباتإجراء "إزالة من قائمة الرغبات"

🔐 تشير إلى الطرق التي تتطلب جلسة مستخدم مصادق عليها (AuthProvider). تعمل طرق السلة وقائمة الرغبات أيضًا للضيوف.

🛒 السلة وقائمة الرغبات​

تعمل طرق السلة وقائمة الرغبات لكل من المستخدمين المصرح لهم والضيوف. بالنسبة للضيف، يرسل SDK رأس x-guest-id بحيث تكون السلة / قائمة الرغبات مرتبطة بالزائر المجهول الصحيح - انظر وضع الضيف. بمجرد تسجيل دخول الضيف، تعمل نفس الطرق على بيانات المستخدم المصرح به.

تغذي هذه الطرق أيضًا كتل التخصيص (مثل تكملة السلة، السلة المماثلة و قائمة الرغبات المماثلة) ويمكن دمجها مع تتبع نشاط المستخدم.

❓ الأسئلة الشائعة (FAQ)​

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

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

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

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

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

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

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

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

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

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

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

  • قم بالمصادقة أولاً - كل طريقة مستخدم تتطلب جلسة مصادق عليها (انظر موديل AuthProvider).
  • احفظ الحالة الحالية - وزع البيانات الحالية عند تحديث state.
  • لا تخزن بيانات حساسة في الحالة - احتفظ بكلمات المرور، الرموز، وبيانات البطاقة خارج state.
  • قم بتخزين بيانات المستخدم - قلل من استدعاءات API للبيانات التي يتم الوصول إليها بشكل متكرر.

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