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://imamjavad.newhorizonco.uk/join-class?token=5f7b8c...e1&slug=dars-akhlagh",
  "expires_in": 300
}

نکته: URL ثابت است: https://imamjavad.newhorizonco.uk/join-class?token={TOKEN}&slug={COURSE_SLUG}

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": "درس اخلاق",
    "slug": "dars-akhlagh",
    "category": {
      "name": "علوم اسلامی",
      "slug": "islamic-sciences",
      "course_count": 15
    },
    "access": true,
    "participant_count": 85,
    "professor": {
      "id": 7,
      "fullname": "استاد رضایی",
      "slug": "rezaei",
      "avatar": "https://api.example.com/media/avatars/rezaei.jpg",
      "email": "rezaei@example.com",
      "phone_number": "+1234567890",
      "info": "استاد دانشگاه",
      "skill": "فقه و اصول",
      "city": "قم",
      "country": "ایران",
      "birthdate": "1975-05-15",
      "gender": "male"
    },
    "is_professor": false,
    "thumbnail": "https://api.example.com/media/courses/akhlagh.jpg",
    "video_type": "link",
    "video_file": null,
    "video_link": "https://example.com/intro-video.mp4",
    "is_online": true,
    "online_link": "https://meeting.example.com/class/42",
    "level": "intermediate",
    "description": "دوره جامع اخلاق اسلامی...",
    "duration": "3 ماه",
    "lessons_count": 12,
    "lessons_complated_count": 5,
    "short_description": "آشنایی با مبانی اخلاق اسلامی",
    "status": "ongoing",
    "is_free": false,
    "price": "50000.00",
    "discount_percentage": 10,
    "final_price": "45000.00",
    "timing": {
      "monday": "18:00",
      "wednesday": "18:00"
    },
    "features": ["ضبط جلسات", "گواهینامه معتبر", "پشتیبانی 24 ساعته"],
    "last_lesson_id": 6,
    "room_id": 123,
    "user_transaction_status": "approved"
  },
  "user": {
    "id": 105,
    "device_id": "device-xyz-123",
    "fcm": "fcm-token-abc",
    "fullname": "علی احمدی",
    "slug": "ali-ahmadi",
    "avatar": "https://api.example.com/media/avatars/ali.jpg",
    "email": "ali@example.com",
    "phone_number": "+9876543210",
    "info": "دانشجو",
    "skill": "برنامه‌نویسی",
    "city": "تهران",
    "country": "ایران",
    "birthdate": "1995-08-20",
    "gender": "male"
  },
  "metadata": {
    "status": "ongoing",
    "is_online": true,
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "can_start_online_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",
    "livesession_started_at": "2024-10-05T10:15:30Z",
    
  }
}

توضیحات فیلدهای مهم:

• course: شامل تمام اطلاعات دوره شامل استاد، دسته‌بندی، درس‌ها، قیمت و...
• user: پروفایل کامل کاربری که توکن را اعتبارسنجی کرده
• metadata.can_start_online_class: true برای استاد دوره، false برای دانشجویان (فقط استاد می‌تواند کلاس را شروع کند)
• metadata.professor_in_class: نشان می‌دهد استاد در حال حاضر در کلاس حضور دارد یا خیر
• metadata.has_started: دوره شروع شده است (ongoing یا finished)
• metadata.has_finished: دوره به پایان رسیده است (finished)

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

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