dovodi
/
Dovodi_Backend
3
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
85 Commits
1 Branch
0 Tags
70 MiB
 
 
Tree: 1b0f813855
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from '1b0f813855'
${ noResults }
Dovodi_Backend/docs/live-session-api.md

11 KiB
Raw Blame History

راهنمای اتصال فرانت‌اند به API لایو کلاس

این مستند جریان کامل «ایجاد روم لایو»، «گرفتن توکن ورود» و «مدیریت ورود استاد و دانشجو» را توضیح می‌دهد.

۱. اعتبارسنجی وضعیت دوره

GET /api/courses/<course-slug>/online/validate/
Headers:
  Authorization: Token <USER_TOKEN>

پاسخ نمونه (استاد، کلاس آنلاین در حال اجرا)

{
  "course": {
    "id": 42,
    "slug": "algebra-10",
    "title": "کلاس جبر",
    "is_online": true,
    "online_link": "https://imamjavad.app/courses/algebra-10/live",
    "status": "ongoing",
    "professor": {
      "id": 10,
      "fullname": "استاد نمونه",
      "slug": "ostad-nemoone",
      "avatar": "https://imamjavad.app/media/users/avatars/2025/10/ostad.jpg"
    }
  },
  "user": {
    "id": 10,
    "email": "prof@example.com",
    "fullname": "استاد نمونه",
    "avatar": "https://imamjavad.app/media/users/avatars/2025/10/ostad.jpg",
    "roles": ["professor"],
    "is_staff": false
  },
  "metadata": {
    "status": "ongoing",
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "can_create_live_session": false,
    "can_join_live_session": true,
    "scheduled_times": {
      "day": "monday",
      "start_time": "09:00",
      "timezone": "Asia/Tehran"
    },
    "generated_at": "2025-10-14T01:32:45+03:30",
    "validated_at": "2025-10-14T01:33:10+03:30",
    "redirect_path": null,
    "is_online": true,
    "active_room_id": "algebra-1402",
    "livesession_started_at": "2025-10-14T01:15:00+03:30",
    "livesession_ended_at": null,
    "live_session": {
      "id": 7,
      "room_id": "algebra-1402",
      "subject": "کلاس جبر فصل ۱",
      "started_at": "2025-10-14T01:15:00+03:30",
      "ended_at": null
    }
  }
}
  • can_create_live_session: اگر true → استاد می‌تواند روم جدید بسازد (فقط وقتی کلاس آفلاین است)
  • can_join_live_session: اگر true → کاربر می‌تواند به کلاس فعال بپیوندد (استاد یا دانشجو)
  • active_room_id: room_id کلاس فعال (برای نمایش در UI)
  • livesession_started_at: زمان شروع - برای محاسبه مدت سپری‌شده

پاسخ نمونه (استاد، کلاس آفلاین)

{
  "course": { "id": 42, "title": "کلاس جبر" },
  "user": { "id": 10, "fullname": "استاد نمونه" },
  "metadata": {
    "status": "ongoing",
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "can_create_live_session": true,
    "can_join_live_session": false,
    "scheduled_times": { "day": "monday", "time": "09:00" },
    "generated_at": "2025-10-14T01:32:45+03:30",
    "validated_at": "2025-10-14T01:33:10+03:30",
    "redirect_path": null,
    "is_online": false,
    "active_room_id": null,
    "livesession_started_at": null,
    "livesession_ended_at": null,
    "live_session": null
  }
}

پاسخ نمونه (دانشجو ثبت‌نام‌کرده، کلاس آنلاین)

{
  "course": { "id": 42, "title": "کلاس جبر" },
  "user": { "id": 27, "fullname": "دانشجو نمونه" },
  "metadata": {
    "status": "ongoing",
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "can_create_live_session": false,
    "can_join_live_session": true,
    "scheduled_times": { "day": "monday", "time": "09:00" },
    "generated_at": "2025-10-14T01:32:45+03:30",
    "validated_at": "2025-10-14T01:33:10+03:30",
    "redirect_path": null,
    "is_online": true,
    "active_room_id": "algebra-1402",
    "livesession_started_at": "2025-10-14T01:15:00+03:30",
    "livesession_ended_at": null,
    "live_session": {
      "id": 7,
      "room_id": "algebra-1402",
      "subject": "کلاس جبر فصل ۱",
      "started_at": "2025-10-14T01:15:00+03:30",
      "ended_at": null
    }
  }
}

پاسخ نمونه (دانشجو ثبت‌نام‌کرده، کلاس آفلاین)

{
  "course": { "id": 42, "title": "کلاس جبر" },
  "user": { "id": 27, "fullname": "دانشجو نمونه" },
  "metadata": {
    "status": "ongoing",
    "has_started": true,
    "has_finished": false,
    "professor_in_class": false,
    "can_create_live_session": false,
    "can_join_live_session": false,
    "scheduled_times": { "day": "monday", "time": "09:00" },
    "generated_at": "2025-10-14T01:32:45+03:30",
    "validated_at": "2025-10-14T01:33:10+03:30",
    "redirect_path": null,
    "is_online": false,
    "active_room_id": null,
    "livesession_started_at": null,
    "livesession_ended_at": null,
    "live_session": null
  }
}

پاسخ نمونه (کاربر بدون دسترسی)

{
  "status": "error",
  "code": "app_api_error",
  "status_code": 403,
  "message": "An error occurred while processing the request.",
  "errors": [
    { "message": "You do not have access to this course." }
  ]
}

۲. ساخت یا فعال کردن روم (استاد)

POST /api/courses/<course-slug>/online/room/create/
Headers:
  Authorization: Token <USER_TOKEN>
  Content-Type: application/json

Body (نمونه):
{
  "subject": "کلاس جبر فصل ۱"         // اختیاری؛ پیش‌فرض عنوان دوره + "Live Session"
}

⚠️ نکات مهم:

  • فرانت نباید metadata ارسال کند!
  • بک‌اند به‌طور خودکار تنظیمات امنیتی را اعمال می‌کند:
    • lock_microphone: true - میکروفون برای همه قفل است
    • lock_webcam: true - وبکم برای همه قفل است
    • lock_screen_sharing: true - اشتراک صفحه برای همه قفل است
    • mute_on_start: true - همه با میکروفون خاموش وارد می‌شوند
  • فقط میزبان (استاد) می‌تواند این محدودیت‌ها را برداشته و به دانشجو اجازه دهد

پاسخ موفق (۲۰۱ یا ۲۰۰)

{
  "session": {
    "id": 7,
    "room_id": "algebra-1402",
    "subject": "کلاس جبر فصل ۱",
    "started_at": "2025-10-14T01:32:45+03:30"
  },
  "plugnmeet": {
    "status": "success",
    "room_id": "algebra-1402",
    "...": "پاسخ کامل PlugNMeet"
  }
}

۳. گرفتن توکن ورود به روم

POST /api/courses/online/room/token/
Headers:
  Authorization: Token <USER_TOKEN>
  Content-Type: application/json

Body:
{
  "course_slug": "algebra-10"
}

⚠️ نکات مهم:

  • فرانت فقط course_slug ارسال می‌کند!
  • بک‌اند از Authorization header کاربر را شناسایی می‌کند
  • بک‌اند خودش live session فعال دوره را پیدا می‌کند: 
    course = Course.objects.get(slug=course_slug)
session = CourseLiveSession.objects.get(course=course, ended_at__isnull=True)
room_id = session.room_id
  • بک‌اند خودش همه اطلاعات کاربر را می‌سازد:
    • user_id از request.user.id
    • name از user.get_full_name() یا user.email
    • is_admin از user.can_manage_course(course) - تشخیص خودکار استاد/دانشجو
    • profilePic از user.avatar
    • lock_settings خودکار برای دانشجو (همه قفل)

پاسخ موفق

{
  "room_id": "algebra-1402",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "plugnmeet": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires": 300,
    "...": "پاسخ کامل PlugNMeet"
  }
}

نحوه استفاده:

  • token باید در URL سرویس PlugNMeet استفاده شود: 
    https://meet.newhorizonco.uk/?access_token=<token>
  • بک‌اند خودکار تشخیص می‌دهد:
    • استاد: is_admin: true → همه دسترسی‌ها بدون محدودیت
    • دانشجو: is_admin: false + lock_settings → میکروفون، وبکم و اشتراک صفحه قفل است

سناریوهای پیشنهادی برای پیاده‌سازی فرانت

سناریوی استاد

  1. دریافت وضعیت: با GET /online/validate/ وضعیت را بگیرید.

    • اگر can_create_live_session = true است → دکمه «ساخت کلاس» را نشان دهید.
    • اگر can_join_live_session = true است → دکمه «ورود به کلاس» را نشان دهید.

  2. ساخت روم (در صورت نیاز):

    POST /online/room/create/
Body: {
  "room_id": "algebra-10-1704880365000",  // اختیاری
  "subject": "کلاس جبر"                    // اختیاری
}

    نکته: فقط این دو فیلد! بک‌اند خودش metadata و تنظیمات امنیتی را اعمال می‌کند.

  3. گرفتن توکن:

    POST /online/room/token/
Body: {
  "course_slug": "algebra-10"  // فقط این!
}

    نکته: بک‌اند خودش live session فعال را پیدا می‌کند و room_id را می‌گیرد.

  4. ورود به کلاس:

    window.open(`https://meet.newhorizonco.uk/?access_token=${token}`, "_blank");

سناریوی دانشجو

  1. دریافت وضعیت: با GET /online/validate/ وضعیت را بگیرید.

    • اگر is_online = true و can_join_live_session = true → دکمه «ورود به کلاس» را نمایش دهید.

  2. گرفتن توکن و ورود:

    POST /online/room/token/
Body: {
  "course_slug": "algebra-10"  // فقط این!
}

    سپس با token دریافتی به PlugNMeet وارد شوید.

✅ آنچه بک‌اند خودکار انجام می‌دهد:

موقع ساخت روم:

  • ✅ تعیین default_lock_settings (همه true)
  • ✅ تعیین room_features.mute_on_start: true
  • ✅ ساخت metadata کامل برای PlugNMeet

موقع گرفتن توکن:

  • ✅ پیدا کردن live session فعال از course_slug
  • ✅ گرفتن room_id از session
  • ✅ تشخیص is_admin با user.can_manage_course(course)
  • ✅ ساخت user_info کامل (user_id, name, profilePic)
  • ✅ اضافه کردن lock_settings برای دانشجو

❌ آنچه فرانت نباید ارسال کند:

  • ❌ metadata موقع ساخت روم
  • ❌ room_id موقع گرفتن توکن
  • ❌ user_info, is_admin, lock_settings

🔐 نکات امنیتی:

  • همه تنظیمات امنیتی در سمت سرور کنترل می‌شود
  • فرانت نمی‌تواند تنظیمات را دستکاری کند
  • بک‌اند تعیین می‌کند چه کسی استاد است و چه کسی دانشجو
  • زمانی که استاد وارد لایو شده است، can_create_live_session برابر false می‌شود
  • برای نمایش مدت سپری‌شده، از livesession_started_at استفاده کرده و در فرانت اختلاف با زمان فعلی را محاسبه کنید