Dovodi_Backend/docs/online_class_entry_flow.md

Online Class Entry Scenario

1. دریافت توکن ورود به کلاس آنلاین

• هدف: کاربر لاگین‌شده لینک ورود موقت به کلاس بگیرد.
• درخواست: POST /api/courses/{course_id}/online/token/ به همراه توکن احراز هویت کاربر.
• ورودی اختیاری: redirect_path (مسیر نسبی در فرانت برای صفحه کلاس).
• خروجی: توکن یک‌بارمصرف ذخیره‌شده در Redis + آدرس نهایی ورود (دامنه فرانت + Query Param توکن).

نمونه curl

curl --request POST \
  --url https://api.example.com/api/courses/42/online/token/ \
  --header 'Authorization: Token USER_AUTH_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "redirect_path": "online-classroom"
  }'

نمونه پاسخ

{
  "token": "5f7b8c...e1",
  "url": "https://front.example.com/online-classroom?token=5f7b8c...e1",
  "expires_in": 300
}

2. اعتبارسنجی توکن و دریافت داده‌های کلاس

• هدف: فرانت با توکن دریافتی اطلاعات کلاس، پروفایل کاربر و متادیتا را بگیرد.
• درخواست: POST /api/courses/online/token/validate/
• ورودی: token
• خروجی: آبجکت دوره (سریالایز کامل)، پروفایل کاربر، و متادیتا شامل وضعیت کلاس، زمان‌ها و وضعیت حضور استاد.

نمونه curl

curl --request POST \
  --url https://api.example.com/api/courses/online/token/validate/ \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "5f7b8c...e1"
  }'

نمونه پاسخ

{
  "course": {
    "id": 42,
    "title": "درس اخلاق",
    "status": "ongoing",
    "timing": {
      "monday": "18:00",
      "wednesday": "18:00"
    },
    "online_link": "https://meeting.example.com/class/42",
    "is_online": true,
    "professor": {
      "id": 7,
      "fullname": "استاد رضایی"
    }
  },
  "user": {
    "id": 105,
    "fullname": "علی احمدی",
    "email": "ali@example.com"
  },
  "metadata": {
    "status": "ongoing",
    "is_online": true,
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "scheduled_times": {
      "monday": "18:00",
      "wednesday": "18:00"
    },
    "generated_at": "2024-10-05T10:15:30Z",
    "validated_at": "2024-10-05T10:16:05.123456Z"
  }
}

نکات پیاده‌سازی در فرانت‌اند

1. پس از دریافت پاسخ مرحله‌ٔ اول، کاربر را به url بازگردانی کنید.
2. در صفحه کلاس، توکن از Query String خوانده شده و به مرحله‌ٔ دوم ارسال شود.
3. در صورت خطا (Expiry یا Invalid)، فرانت باید کاربر را به صفحه‌ٔ اصلی یا خطا هدایت کند و درخواست توکن جدید بدهد.
4. expires_in نشان می‌دهد لینک چه مدت اعتبار دارد؛ بهتر است شمارش معکوس یا تلاش خودکار برای تمدید توکن داشته باشید.