# راهنمای استفاده از endpoint های ورود به کلاس آنلاین

این فایل برای تیم‌های `frontend` و `flutter` نوشته شده و فقط توضیح می‌دهد:

- هر endpoint چه کاری انجام می‌دهد
- در چه شرایطی باید از آن استفاده شود
- ترتیب درست استفاده از endpoint ها چیست

این راهنما وارد کدنویسی React یا Flutter نمی‌شود و فقط منطق استفاده را توضیح می‌دهد.

## هدف کلی

کاربر برای ورود به کلاس آنلاین دو حالت دارد:

1. کلاس هنوز توسط استاد شروع نشده است
2. کلاس از قبل شروع شده و room فعال است

رفتار درست فرانت باید بر اساس همین دو حالت تعیین شود.

## اصل مهم

فرانت نباید با درخواست اشتباه باعث ساختن کلاس توسط دانشجو شود.

بنابراین:

- اگر کلاس شروع نشده باشد، کاربر باید وارد `waiting page` شود
- اگر کلاس شروع شده باشد، کاربر باید مستقیم `join token` واقعی بگیرد و وارد کلاس شود

## endpoint ها

### 1. بررسی وضعیت کلاس

#### Endpoint

`GET /api/courses/<course-slug>/online/validate/`

#### کاربرد

این endpoint برای تصمیم‌گیری اولیه فرانت است.

با این endpoint می‌توان فهمید:

- آیا کلاس الان آنلاین است یا نه
- آیا کاربر اجازه ورود به کلاس را دارد یا نه
- آیا کاربر استاد است و می‌تواند کلاس را شروع کند یا نه

#### خروجی مهم

فیلدهای مهم در `metadata`:

- `is_online`
- `can_join_live_session`
- `can_create_live_session`
- `has_finished`

#### زمان استفاده

این endpoint باید قبل از تصمیم نهایی برای ورود به کلاس صدا زده شود.

#### تصمیم‌گیری بر اساس پاسخ

- اگر `is_online = true` و `can_join_live_session = true`
  فرانت باید مستقیم به سراغ گرفتن `join token` واقعی برود

- اگر `is_online = false`
  فرانت نباید مستقیم سراغ `room/token` برود و باید از flow صفحه انتظار استفاده کند

- اگر `can_create_live_session = true`
کاربر استاد است و  فرانت باید مستقیم به سراغ گرفتن `join token` واقعی برود

---

### 2. ساخت لینک ورود موقت برای waiting page

#### Endpoint

`POST /api/courses/<course_id>/online/token/`

#### کاربرد

این endpoint برای ورود به waiting flow استفاده می‌شود.

این endpoint:

- یک `temporary token` می‌سازد
- یک URL ورود به `conference_client` برمی‌گرداند

#### چه زمانی باید استفاده شود

فقط وقتی که کلاس هنوز شروع نشده است.

#### چه زمانی نباید استفاده شود

اگر کلاس از قبل شروع شده و room فعال است، نباید این endpoint مسیر اصلی ورود باشد.

در آن حالت باید مستقیم `join token` واقعی گرفته شود.

#### ورودی

- `course_id` در URL
- هدر احراز هویت کاربر

بدنه عملا می‌تواند خالی باشد.

#### خروجی

پاسخ شامل این فیلدهاست:

- `token`
- `url`
- `expires_in`


### 3. گرفتن join token واقعی برای ورود مستقیم به کلاس

#### Endpoint

`POST /api/courses/online/room/token/`

#### کاربرد

این endpoint `access_token` واقعی PlugNMeet را می‌سازد.

با این token کاربر مستقیم وارد کلاس می‌شود.

#### چه زمانی باید استفاده شود

وقتی که کلاس از قبل شروع شده و room فعال است.

#### چه زمانی نباید استفاده شود

وقتی هنوز کلاس شروع نشده است.

در آن حالت این endpoint مسیر مناسب ورود نیست و باید از waiting flow استفاده شود.

#### ورودی

بدنه:

`course_slug`

به همراه هدر احراز هویت کاربر

#### خروجی

پاسخ شامل:

- `room_id`
- `token`

#### رفتار درست بعد از دریافت پاسخ

کاربر باید مستقیم به `conference_client` با `access_token` هدایت شود.

مثال:

`https://meet.imamjavad.online/?access_token=<access_token>`


## ترتیب درست استفاده در فرانت

### سناریو 1: کاربر روی دکمه ورود به کلاس می‌زند

ترتیب درست:

1. فرانت وضعیت کلاس را با `online/validate` بررسی کند
2. اگر کلاس فعال بود:
   - `online/room/token/`
   - هدایت مستقیم با `access_token`
3. اگر کلاس فعال نبود:
   - `online/token/`
   - هدایت کاربر به waiting page

## منطق تصمیم‌گیری پیشنهادی

- `is_online = true`
  مسیر درست: ورود مستقیم به کلاس

- `is_online = false`
  مسیر درست: waiting page

## رفتار داخل conference_client

`conference_client` الان دو ورودی را می‌فهمد:

### حالت اول: ورود مستقیم

اگر URL شامل این باشد:

- `access_token`

کاربر مستقیم وارد flow اصلی کلاس می‌شود.

### حالت دوم: waiting flow

اگر URL شامل این باشد:

- `token`
- `slug`

کاربر وارد waiting/pre-join flow می‌شود.

در این حالت:

1. temporary token به auth token واقعی تبدیل می‌شود
2. وضعیت کلاس از Django خوانده می‌شود
3. اگر کلاس هنوز شروع نشده باشد، waiting page نمایش داده می‌شود
4. اگر کلاس شروع شده باشد، دکمه ورود به کلاس نمایش داده می‌شود
5. اگر کاربر استاد باشد و کلاس شروع نشده باشد، دکمه شروع کلاس نمایش داده می‌شود

## آپدیت خودکار وضعیت

در waiting flow، وضعیت کلاس به صورت polling دوره‌ای از Django بررسی می‌شود.

بنابراین:

- اگر استاد کلاس را شروع کند، صفحه انتظار به‌روزرسانی می‌شود
- اگر استاد کلاس را ببندد، وضعیت صفحه دوباره به حالت انتظار/پایان بازمی‌گردد

## جمع‌بندی نهایی

### برای فرانت اصلی سایت یا اپ

- ابتدا همیشه `online/validate`
- اگر کلاس فعال بود: `online/room/token/`
- اگر کلاس فعال نبود: `online/token/`

### برای conference_client

- اگر `access_token` داشت: ورود مستقیم
- اگر `token + slug` داشت: waiting flow

### قاعده مهم

`online/token/` برای قبل از شروع کلاس است

`online/room/token/` برای وقتی است که کلاس واقعا شروع شده است