# راهنمای لاگ‌های Live Session API

این مستند توضیح می‌دهد که هر API چه لاگ‌هایی تولید می‌کند و چگونه می‌توان از آنها برای debug استفاده کرد.

## 📋 فرمت لاگ‌ها

همه لاگ‌ها با یک prefix مشخص شروع می‌شوند:
- `[LiveSession Create]` - مربوط به ساخت روم
- `[LiveSession Token]` - مربوط به گرفتن توکن ورود
- `[Online Validate]` - مربوط به اعتبارسنجی وضعیت دوره

## 🔹 API: ساخت روم (Create Room)

**Endpoint:** `POST /api/courses/<course-slug>/online/room/create/`

### جریان لاگ‌ها:

1. **شروع درخواست:**
   ```
   INFO [LiveSession Create] Request from user_id=10 for course=algebra-10
   ```

2. **بررسی دسترسی:**
   - **موفق:**
     ```
     INFO [LiveSession Create] Permission granted for user_id=10 course=algebra-10
     ```
   - **رد شده:**
     ```
     WARNING [LiveSession Create] Permission denied - user_id=27 course=algebra-10
     ```

3. **فراخوانی PlugNMeet:**
   ```
   INFO [LiveSession Create] Calling PlugNMeet API - room_id=algebra-10-20231014102530 course=algebra-10
   ```

4. **نتیجه PlugNMeet:**
   - **موفق:**
     ```
     INFO [LiveSession Create] PlugNMeet room created successfully - room_id=algebra-10-20231014102530
     ```
   - **خطای پیکربندی:**
     ```
     ERROR [LiveSession Create] Configuration error - PLUGNMEET_API_KEY is not configured
     ```
   - **خطای API:**
     ```
     ERROR [LiveSession Create] PlugNMeet API error - room_id=algebra-10-20231014102530 error=Room already exists
     ```

5. **ذخیره در دیتابیس:**
   - **Session جدید:**
     ```
     INFO [LiveSession Create] New session created - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
     ```
   - **Session موجود:**
     ```
     INFO [LiveSession Create] Existing session reactivated - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
     INFO [LiveSession Create] Session updated - session_id=7 fields=['subject', 'started_at']
     ```

6. **نتیجه نهایی:**
   ```
   INFO [LiveSession Create] Success - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10 user_id=10
   ```

### سناریوهای خطا:

| خطا | لاگ | دلیل |
|-----|-----|------|
| Permission Denied | `WARNING [LiveSession Create] Permission denied - user_id=27 course=algebra-10` | کاربر استاد نیست |
| Configuration Error | `ERROR [LiveSession Create] Configuration error - ...` | تنظیمات PlugNMeet ناقص |
| PlugNMeet API Error | `ERROR [LiveSession Create] PlugNMeet API error - ...` | سرویس PlugNMeet پاسخ خطا داده |

---

## 🔹 API: گرفتن توکن (Get Join Token)

**Endpoint:** `POST /api/courses/online/room/token/`

### جریان لاگ‌ها:

1. **شروع درخواست:**
   ```
   INFO [LiveSession Token] Request from user_id=27 for course=algebra-10
   ```

2. **پیدا کردن دوره:**
   - **موفق:**
     ```
     (بدون لاگ - به مرحله بعد می‌رود)
     ```
   - **پیدا نشد:**
     ```
     WARNING [LiveSession Token] Course not found - course=algebra-10 user_id=27
     ```

3. **بررسی تنظیمات دوره:**
   - **دوره آنلاین نیست:**
     ```
     WARNING [LiveSession Token] Course not configured for online - course=algebra-10 user_id=27
     ```

4. **پیدا کردن Session فعال:**
   - **موفق:**
     ```
     INFO [LiveSession Token] Active session found - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
     ```
   - **پیدا نشد:**
     ```
     WARNING [LiveSession Token] No active session found - course=algebra-10 user_id=27
     ```

5. **تشخیص نقش کاربر:**
   ```
   INFO [LiveSession Token] User role determined - user_id=27 role=student course=algebra-10
   ```
   یا
   ```
   INFO [LiveSession Token] User role determined - user_id=10 role=professor course=algebra-10
   ```

6. **بررسی دسترسی (برای دانشجو):**
   - **ثبت‌نام نشده:**
     ```
     WARNING [LiveSession Token] Access denied - user_id=27 not enrolled in course=algebra-10
     ```

7. **درخواست توکن از PlugNMeet:**
   ```
   INFO [LiveSession Token] Requesting token from PlugNMeet - room_id=algebra-10-20231014102530 user_id=27 role=student
   ```

8. **نتیجه PlugNMeet:**
   - **موفق:**
     ```
     INFO [LiveSession Token] Token generated successfully - room_id=algebra-10-20231014102530 user_id=27
     ```
   - **خطا:**
     ```
     ERROR [LiveSession Token] Configuration error - PLUGNMEET_API_KEY is not configured
     ```
     یا
     ```
     ERROR [LiveSession Token] PlugNMeet API error - room_id=algebra-10-20231014102530 user_id=27 error=Room not found
     ```

9. **نتیجه نهایی:**
   ```
   INFO [LiveSession Token] Success - room_id=algebra-10-20231014102530 user_id=27 role=student course=algebra-10
   ```

### سناریوهای خطا:

| خطا | لاگ | دلیل |
|-----|-----|------|
| Course Not Found | `WARNING [LiveSession Token] Course not found - ...` | slug اشتباه است |
| Course Not Online | `WARNING [LiveSession Token] Course not configured for online - ...` | دوره آنلاین نیست |
| No Active Session | `WARNING [LiveSession Token] No active session found - ...` | هیچ session فعالی وجود ندارد |
| Access Denied | `WARNING [LiveSession Token] Access denied - user_id=X not enrolled in course=Y` | دانشجو در کلاس ثبت‌نام نکرده |
| PlugNMeet Error | `ERROR [LiveSession Token] PlugNMeet API error - ...` | مشکل در سرویس PlugNMeet |

---

## 🔹 API: اعتبارسنجی (Online Validate)

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

### جریان لاگ‌ها:

1. **شروع درخواست:**
   ```
   INFO [Online Validate] Request received
   ```

2. **Decode توکن:**
   - **موفق:**
     ```
     INFO [Online Validate] Token decoded successfully
     ```
   - **خطا:**
     ```
     ERROR [Online Validate] Token decode failed - error=Token has expired
     ```

3. **بررسی Payload:**
   - **نامعتبر:**
     ```
     WARNING [Online Validate] Invalid token payload - course_id=None user_id=10
     ```

4. **شروع پردازش:**
   ```
   INFO [Online Validate] Processing for user_id=10 course_id=42
   ```

5. **پیدا کردن دوره:**
   ```
   INFO [Online Validate] Course found - slug=algebra-10 is_online=True
   ```

6. **ساخت Metadata:**
   ```
   DEBUG [Online Validate Metadata] user_id=10 course=algebra-10 can_manage=True is_online=True can_join=True
   ```

7. **نتیجه نهایی:**
   ```
   INFO [Online Validate] Success - user_id=10 course=algebra-10 can_create=False can_join=True
   ```

### سناریوهای خطا:

| خطا | لاگ | دلیل |
|-----|-----|------|
| Token Decode Error | `ERROR [Online Validate] Token decode failed - ...` | توکن منقضی یا نامعتبر |
| Invalid Payload | `WARNING [Online Validate] Invalid token payload - ...` | payload توکن ناقص است |

---

## 🔍 نحوه استفاده از لاگ‌ها برای Debug

### 1. بررسی جریان کامل یک درخواست:

برای دنبال کردن یک درخواست خاص، بر اساس `user_id` یا `course` فیلتر کنید:

```bash
# برای user خاص
tail -f /var/log/app.log | grep "user_id=27"

# برای course خاص
tail -f /var/log/app.log | grep "course=algebra-10"

# برای room خاص
tail -f /var/log/app.log | grep "room_id=algebra-10-20231014102530"
```

### 2. پیدا کردن خطاها:

```bash
# همه خطاهای LiveSession
tail -f /var/log/app.log | grep -E "\[LiveSession (Create|Token)\]" | grep ERROR

# خطاهای PlugNMeet
tail -f /var/log/app.log | grep "PlugNMeet API error"

# خطاهای دسترسی
tail -f /var/log/app.log | grep -E "(Permission denied|Access denied)"
```

### 3. بررسی وضعیت سیستم:

```bash
# همه درخواست‌های ساخت روم
tail -f /var/log/app.log | grep "\[LiveSession Create\] Request"

# همه درخواست‌های توکن
tail -f /var/log/app.log | grep "\[LiveSession Token\] Request"

# تشخیص نقش کاربران
tail -f /var/log/app.log | grep "User role determined"
```

### 4. آمار سریع:

```bash
# تعداد room های ساخته شده امروز
grep "LiveSession Create.*Success" /var/log/app.log | grep "$(date +%Y-%m-%d)" | wc -l

# تعداد توکن‌های صادر شده
grep "LiveSession Token.*Success" /var/log/app.log | grep "$(date +%Y-%m-%d)" | wc -l

# تعداد خطاها
grep "ERROR.*LiveSession" /var/log/app.log | grep "$(date +%Y-%m-%d)" | wc -l
```

---

## ⚙️ تنظیمات Logging

برای فعال کردن لاگ‌ها، در `settings.py`:

```python
LOGGING = {
    'version': 1,
    'disable_existing_loggers': False,
    'formatters': {
        'verbose': {
            'format': '{levelname} {asctime} {module} {message}',
            'style': '{',
        },
    },
    'handlers': {
        'file': {
            'level': 'INFO',
            'class': 'logging.FileHandler',
            'filename': '/var/log/app.log',
            'formatter': 'verbose',
        },
        'console': {
            'level': 'INFO',
            'class': 'logging.StreamHandler',
            'formatter': 'verbose',
        },
    },
    'loggers': {
        'apps.course.views.live_session': {
            'handlers': ['file', 'console'],
            'level': 'INFO',
            'propagate': False,
        },
        'apps.course.views.course': {
            'handlers': ['file', 'console'],
            'level': 'INFO',
            'propagate': False,
        },
    },
}
```

### سطوح لاگ:

- **INFO**: جریان عادی - شروع درخواست، موفقیت عملیات
- **WARNING**: وضعیت غیرعادی اما قابل کنترل - دسترسی رد شده، دوره پیدا نشد
- **ERROR**: خطاهای سیستم - مشکل PlugNMeet، خطای پیکربندی
- **DEBUG**: جزئیات بیشتر - ساخت metadata، مقادیر داخلی

برای debug بیشتر، `level` را به `DEBUG` تغییر دهید.

---

## 📊 مثال: جریان کامل یک Session

```
INFO [LiveSession Create] Request from user_id=10 for course=algebra-10
INFO [LiveSession Create] Permission granted for user_id=10 course=algebra-10
INFO [LiveSession Create] Calling PlugNMeet API - room_id=algebra-10-20231014102530 course=algebra-10
INFO [LiveSession Create] PlugNMeet room created successfully - room_id=algebra-10-20231014102530
INFO [LiveSession Create] New session created - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
INFO [LiveSession Create] Success - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10 user_id=10

INFO [LiveSession Token] Request from user_id=10 for course=algebra-10
INFO [LiveSession Token] Active session found - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
INFO [LiveSession Token] User role determined - user_id=10 role=professor course=algebra-10
INFO [LiveSession Token] Requesting token from PlugNMeet - room_id=algebra-10-20231014102530 user_id=10 role=professor
INFO [LiveSession Token] Token generated successfully - room_id=algebra-10-20231014102530 user_id=10
INFO [LiveSession Token] Success - room_id=algebra-10-20231014102530 user_id=10 role=professor course=algebra-10

INFO [LiveSession Token] Request from user_id=27 for course=algebra-10
INFO [LiveSession Token] Active session found - session_id=7 room_id=algebra-10-20231014102530 course=algebra-10
INFO [LiveSession Token] User role determined - user_id=27 role=student course=algebra-10
INFO [LiveSession Token] Requesting token from PlugNMeet - room_id=algebra-10-20231014102530 user_id=27 role=student
INFO [LiveSession Token] Token generated successfully - room_id=algebra-10-20231014102530 user_id=27
INFO [LiveSession Token] Success - room_id=algebra-10-20231014102530 user_id=27 role=student course=algebra-10
```

این جریان نشان می‌دهد:
1. استاد روم را ساخت
2. استاد توکن گرفت و وارد شد (role=professor)
3. دانشجو توکن گرفت و وارد شد (role=student)