سير التسجيل

شرح تفصيلي لكيفية عمل تسجيل الوكيل من البداية حتى الموافقة.

نظرة عامة

سير التسجيل يضم ثلاثة أطراف:

1. وكيل الذكاء الاصطناعي - يبدأ التسجيل عبر الواجهة البرمجية
2. المشغّل البشري - يستلم البريد ويوافق
3. SupportRetriever - يعالج وينشئ الحساب

السير خطوة بخطوة

1. الوكيل يبدأ التسجيل

النقطة الطرفية: POST /api/agent/register

الطلب:

{
  "operator_email": "human@company.com",
  "agent_name": "Cursor AI",
  "agent_version": "1.0",
  "purpose": "Setting up support form for new project"
}

ما يحدث:

• التحقق من صيغة البريد
• فحص البريد المؤقت
• فحص حد المعدل (لكل بريد، لكل IP، عام)
• إنشاء رمز التحقق
• إنشاء سجل التسجيل في قاعدة البيانات
• إرسال بريد التحقق للمشغّل

الاستجابة:

{
  "registration_id": "abc-123-def-456",
  "status": "pending_verification",
  "message": "If this email exists, a verification email has been sent."
}

مهم: صيغة الاستجابة نفسها سواء وُجد البريد أم لا (لمنع تعداد البريد).

2. المشغّل البشري يستلم البريد

يستلم المشغّل بريداً يتضمن:

• اسم الوكيل والإصدار
• الغرض المذكور من الوكيل
• تحذير: "We cannot verify this agent's identity"
• أزرار Approve / Decline / Report

موضوع البريد: "An AI agent wants to set up customer support for you"

3. المشغّل ينقر الموافقة

يفتح /agent-verify?token=xxx الذي يعرض:

للمستخدمين الجدد:

• نموذج إنشاء كلمة المرور
• خانة شروط الخدمة
• تحقق Turnstile
• زر "Approve & Create Account"

للمستخدمين الحاليين:

• عرض ما يمكن/لا يمكن للوكيل فعله
• تحقق Turnstile
• زر "Approve Access" (لا حاجة لكلمة مرور)

4. إنشاء الحساب

ما يحدث في الخلفية:

• إنشاء حساب المستخدم (إن كان جديداً) أو ربطه (إن كان موجوداً)
• إنشاء النموذج الافتراضي تلقائياً
• إنشاء مفتاح الواجهة البرمجية
• تعليم التسجيل بأنه "approved"
• تخزين مفتاح الواجهة مؤقتاً لاسترجاع الوكيل

5. الوكيل ياستعلم عن الحالة

النقطة الطرفية: GET /api/agent/status?registration_id=xxx

أثناء الانتظار:

{
  "status": "pending_verification",
  "message": "Waiting for operator approval"
}

عند الموافقة:

{
  "status": "approved",
  "api_key": "sr_live_abc123...",
  "form_url": "https://supportretriever.com/form/uuid",
  "form_id": "uuid",
  "message": "Registration approved. Store this API key securely - it will not be shown again."
}

مهم: مفتاح الواجهة يُعاد مرة واحدة فقط. خزّنه بأمان فوراً.

حد المعدل

طلبات التسجيل محدودة المعدل:

• لكل بريد: حد أقصى طلب واحد كل 24 ساعة
• لكل IP: حد أقصى 5 طلبات في الساعة
• عالمي: حد أقصى 100 طلب في الساعة

إن تجاوزت الحد، ستصلك حالة 429 مع رسالة خطأ.

انتهاء صلاحية الرمز

رموز التحقق تنتهي بعد 24 ساعة. إن لم يوافق المشغّل خلال 24 ساعة:

• يصبح الرمز غير صالح
• تتغير حالة التسجيل إلى "expired"
• يستلم الوكيل حالة "expired" عند الاستعلام

قيم الحالة

معالجة الأخطاء

صيغة البريد غير صالحة

{
  "error": "Invalid email format"
}

بريد مؤقت

{
  "error": "Disposable email addresses are not allowed"
}

تجاوز حد المعدل

{
  "error": "Rate limit exceeded: max 1 request per email per 24 hours"
}

التسجيل غير موجود

{
  "error": "Registration not found"
}

ميزات الأمان

• منع تعداد البريد: نفس صيغة الاستجابة بغض النظر عن وجود البريد
• حد المعدل: منع إساءة الاستخدام وقصف البريد
• انتهاء الرمز: نافذة 24 ساعة للموافقة
• تحقق Turnstile: حماية من البوتات في صفحة الموافقة
• مفتاح واجهة لمرة واحدة: يُعرض المفتاح مرة واحدة ثم يُمسح

مواضيع ذات صلة

• Getting Started
• Error Codes
• النموذج Customization