تدفقات المصادقة

يساعدك هذا الدليل على اختيار نمط المصادقة المناسب لتطبيق HeroMate.

استخدمه عند تقرير:

• ما إذا كان يمكن للمستخدمين التسجيل بأنفسهم
• ما إذا كان يجب أن يكون الوصول بدعوة فقط
• متى تستخدم endpoints من نوع jwt
• متى تستخدم endpoints من نوع api_key
• كيف تنظّم استدعاءات الواجهة مقابل الخادم

القاعدة الأساسية

في HeroMate، يجب أن تستخدم endpoints HTTP الموجّهة للتطبيق أحد هذين الوضعين:

• jwt: الطلب مرتبط بمستخدم مسجّل الدخول
• api_key: الطلب مرتبط بمفتاح المشروع، عادة من كود جانب الخادم

لا تصمّم endpoints عامة دون مصادقة.

جدول القرار السريع

التدفق 1: تطبيق عام مع تسجيل المستخدمين

استخدم هذا عندما:

• ينشئ المستخدمون حساباتهم بأنفسهم
• للتطبيق تسجيل دخول أو ملف شخصي أو لوحة تحكم أو بيانات يملكها المستخدم
• تحتاج سير العمل إلى current_user أو current_user_id

الإعداد الموصى به:

1. فعّل التسجيل في Auth.
2. أبقِ تأكيد البريد مفعّلاً ما لم يكن هناك سبب قوي لتعطيله.
3. استخدم dypai.auth.signUp() و dypai.auth.signInWithPassword() من التطبيق.
4. احمِ endpoints الأعمال بـ auth_mode: "jwt".
5. استخدم allowed_roles فقط عندما تحتاج قيوداً حسب الدور.

مثال نموذجي:

• موقع تسويقي
• تطبيق SaaS
• لوحة تحكم العميل

const dypai = createClient(process.env.NEXT_PUBLIC_DYPAI_URL!);

await dypai.auth.signUp({
  email,
  password,
  full_name,
});

استخدم jwt لشاشات التطبيق وإجراءات المستخدم:

const { data } = await dypai.api.get('get_profile');

التدفق 2: تطبيق خاص دون تسجيل مفتوح

استخدم هذا عندما:

• لا يجب أن ينشئ المستخدمون حسابات بأنفسهم
• يقرر فريقك من يحصل على الوصول
• هذا مشروع عميل أو لوحة داخلية أو بوابة شركاء أو أداة للموظفين

الإعداد الموصى به:

1. لا تعرض تسجيلاً ذاتياً في الواجهة.
2. أنشئ المستخدمين من تدفقات المدير/الخلفية.
3. أرسل روابط دعوة أو روابط إعداد بأسلوب الاستعادة.
4. دع المستخدم يعيّن كلمة مروره في تطبيقك.
5. أبقِ endpoints التطبيق في وضع jwt.

مثال نموذجي:

• المكتب الخلفي للشركة
• تطبيق خاص لعميل محدد
• منتج B2B بدعوة فقط

الإعداد الموصى به:

1. ينشئ المدير المستخدم أو يدعوه.
2. يفتح المستخدم رابط دعوة إلى مسار رد النداء في تطبيقك.
3. يُصدر SDK حدث PASSWORD_RECOVERY.
4. تعرض واجهتك شاشة تعيين كلمة المرور.
5. يعمل المستخدم بعد ذلك بشكل طبيعي بمصادقة جلسة JWT.

dypai.auth.onAuthStateChange((event) => {
  if (event === 'PASSWORD_RECOVERY') {
    // Show set-password screen
  }
});

التدفق 3: تطبيق داخلي يجهّزه المدير

هذا نسخة أصرم من نمط التطبيق الخاص.

استخدم هذا عندما:

• يمكن للموظفين أو المشغّلين أو المتعاونين الداخليين فقط الدخول
• يُنشئ فريقك كل الحسابات
• الأدوار مهمة جداً (admin و editor و viewer وغيرها)

الإعداد الموصى به:

1. لا واجهة تسجيل عامة.
2. ينشئ المدير المستخدمين.
3. يمر الوصول إلى وظائف التطبيق عبر endpoints من نوع jwt.
4. قيّد endpoints الحساسة بـ allowed_roles.

مثال لتقسيم الأدوار:

• admin: إدارة المستخدمين والنظام
• editor: العمل التشغيلي
• viewer: وصول للقراءة فقط

التدفق 4: من خادم إلى خادم أو مهام خلفية

استخدم هذا عندما:

• لا توجد جلسة مستخدم بشري
• يحتاج عامل أو مهمة cron أو وكيل webhook أو عملية خلفية إلى استدعاء المحرك
• لا يجب أن يعتمد الطلب على هوية المستخدم

الإعداد الموصى به:

1. اضبط endpoint المستهدف بـ auth_mode: "api_key".
2. استدعِه من كود جانب الخادم فقط.
3. أرسل X-API-KEY.
4. لا تعرض المفتاح في كود المتصفح.

أماكن جيدة لاستخدامه:

• Next.js Route Handlers
• Next.js Server Actions
• Server Components التي تستدعي منطقاً للخلفية فقط
• عمال Node
• مهام Python
• مهام cron

const dypai = createClient(
  process.env.DYPAI_URL!,
  process.env.DYPAI_API_KEY
);

await dypai.api.post('sync_data', payload);

بنية مختلطة: واجهة + مهام خادم

هذا شائع جداً وعادة أنظف إعداد.

النمط:

• تستخدم واجهة المتصفح/التطبيق jwt
• تستخدم مهام الخادم وتكاملات الخلفية api_key

مثال للتقسيم:

• create_order -> jwt
• sync_erp_orders -> api_key

هذا يتجنب تعريض بيانات اعتماد الخلفية في العميل مع إبقاء التدفقات الموجّهة للمستخدم بسيطة.

ما يجب تجنّبه

تجنّب هذه الأنماط:

• استخدام api_key من كود مكشوف في المتصفح
• تصميم endpoints مفتوحة/عامة دون مصادقة
• خلط منطق خاص بالمستخدم في endpoints من نوع api_key
• إرسال user_id يدوياً عندما يجب أن يوفّره سياق JWT
• استخدام api_key لإجراءات الواجهة العادية عندما يكون jwt هو النموذج الصحيح

التوصية حسب نوع التطبيق

تطبيق مستهلك / SaaS

• التسجيل: نعم
• تسجيل الدخول: نعم
• وضع endpoint الرئيسي: jwt
• endpoints خلفية اختيارية: api_key

تطبيق عميل خاص

• التسجيل: لا
• الدعوة/التجهيز: نعم
• وضع endpoint الرئيسي: jwt
• تدفق إعداد المدير: دعوة/تعيين كلمة المرور

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

• التسجيل: لا
• التجهيز: المدير فقط
• وضع endpoint الرئيسي: jwt
• allowed_roles قوي: نعم

طبقة تكامل في الخلفية

• التسجيل: غير ذي صلة
• جلسة المستخدم: لا
• وضع endpoint الرئيسي: api_key

توصية عملية

إذا لم تكن متأكداً، ابدأ بهذا:

1. لشاشات التطبيق الموجّهة للمستخدم، استخدم jwt.
2. لأتمتة الخلفية فقط، استخدم api_key.
3. إذا كان يجب ألا يسجّل المستخدمون بأنفسهم، أزل واجهة التسجيل واستخدم تدفقات الدعوة/التجهيز.

الخطوات التالية