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

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

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

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

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

```json
{
  "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`: زمان شروع - برای محاسبه مدت سپری‌شده

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

```json
{
  "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
  }
}
```

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

```json
{
  "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
    }
  }
}
```

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

```json
{
  "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
  }
}
```

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

```json
{
  "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` - همه با میکروفون خاموش وارد می‌شوند
- **فقط میزبان (استاد)** می‌تواند این محدودیت‌ها را برداشته و به دانشجو اجازه دهد

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

```json
{
  "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 فعال دوره را پیدا می‌کند:
  ```python
  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` خودکار برای دانشجو (همه قفل)

### پاسخ موفق

```json
{
  "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. **ساخت روم** (در صورت نیاز): 
   ```json
   POST /online/room/create/
   Body: {
     "room_id": "algebra-10-1704880365000",  // اختیاری
     "subject": "کلاس جبر"                    // اختیاری
   }
   ```
   **نکته**: فقط این دو فیلد! بک‌اند خودش `metadata` و تنظیمات امنیتی را اعمال می‌کند.

3. **گرفتن توکن**: 
   ```json
   POST /online/room/token/
   Body: {
     "course_slug": "algebra-10"  // فقط این!
   }
   ```
   **نکته**: بک‌اند خودش live session فعال را پیدا می‌کند و `room_id` را می‌گیرد.

4. **ورود به کلاس**: 
   ```javascript
   window.open(`https://meet.newhorizonco.uk/?access_token=${token}`, "_blank");
   ```

### سناریوی دانشجو
1. **دریافت وضعیت**: با `GET /online/validate/` وضعیت را بگیرید.
   - اگر `is_online = true` و `can_join_live_session = true` → دکمه «ورود به کلاس» را نمایش دهید.
   
2. **گرفتن توکن و ورود**: 
   ```json
   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` استفاده کرده و در فرانت اختلاف با زمان فعلی را محاسبه کنید