docs/components/WEBSOCKET_GUIDE.md

# 📡 راهنمای استفاده از WebSocket API

## 🎯 مقدمه

این سیستم از WebSocket برای ارتباط بلادرنگ (Real-time) بین سرور و کلاینت استفاده می‌کند که سرعت و کارایی بسیار بالاتری نسبت به HTTP polling دارد.

## 🚀 مزایای WebSocket نسبت به HTTP

| ویژگی | HTTP Polling | WebSocket |
|-------|--------------|-----------|
| سرعت | کند (1-5 ثانیه تاخیر) | فوری (< 100ms) |
| منابع سرور | بالا | پایین |
| پهنای باند | زیاد | کم |
| اتصال | Multiple | Single (دائمی) |
| Overhead | بالا (headers هر بار) | خیلی کم |

## 📦 فایل‌های اضافه شده

### Backend:
- `backend/services/connection_manager.py` - مدیریت اتصالات WebSocket
- تغییرات در `api_server_extended.py` - اضافه شدن endpoint‌های WebSocket

### Frontend:
- `static/js/websocket-client.js` - کلاینت JavaScript
- `static/css/connection-status.css` - استایل‌های بصری
- `test_websocket.html` - صفحه تست

## 🔌 اتصال به WebSocket

### از JavaScript:

```javascript

// استفاده از کلاینت آماده

const wsClient = new CryptoWebSocketClient();



// یا اتصال دستی

const ws = new WebSocket('ws://localhost:8000/ws');



ws.onopen = () => {

    console.log('متصل شد!');

};



ws.onmessage = (event) => {

    const data = JSON.parse(event.data);

    console.log('پیام دریافت شد:', data);

};

```

### از Python:

```python

import asyncio

import websockets

import json



async def connect():

    uri = "ws://localhost:8000/ws"

    async with websockets.connect(uri) as websocket:

        # دریافت پیام welcome

        welcome = await websocket.recv()

        print(f"دریافت: {welcome}")

        

        # ارسال پیام

        await websocket.send(json.dumps({

            "type": "subscribe",

            "group": "market"

        }))

        

        # دریافت پیام‌ها

        async for message in websocket:

            data = json.loads(message)

            print(f"داده جدید: {data}")



asyncio.run(connect())

```

## 📨 انواع پیام‌ها

### 1. پیام‌های سیستمی (Server → Client)

#### Welcome Message
```json

{

    "type": "welcome",

    "session_id": "550e8400-e29b-41d4-a716-446655440000",

    "message": "به سیستم مانیتورینگ کریپتو خوش آمدید",

    "timestamp": "2024-01-15T10:30:00"

}

```

#### Stats Update (هر 30 ثانیه)
```json

{

    "type": "stats_update",

    "data": {

        "active_connections": 15,

        "total_sessions": 23,

        "messages_sent": 1250,

        "messages_received": 450,

        "client_types": {

            "browser": 12,

            "api": 2,

            "mobile": 1

        },

        "subscriptions": {

            "market": 8,

            "prices": 10,

            "all": 15

        }

    },

    "timestamp": "2024-01-15T10:30:30"

}

```

#### Provider Stats
```json

{

    "type": "provider_stats",

    "data": {

        "summary": {

            "total_providers": 150,

            "online": 142,

            "offline": 8,

            "overall_success_rate": 95.5

        }

    },

    "timestamp": "2024-01-15T10:30:30"

}

```

#### Market Update
```json

{

    "type": "market_update",

    "data": {

        "btc": { "price": 43250, "change_24h": 2.5 },

        "eth": { "price": 2280, "change_24h": -1.2 }

    },

    "timestamp": "2024-01-15T10:30:45"

}

```

#### Price Update
```json

{

    "type": "price_update",

    "data": {

        "symbol": "BTC",

        "price": 43250.50,

        "change_24h": 2.35

    },

    "timestamp": "2024-01-15T10:30:50"

}

```

#### Alert
```json

{

    "type": "alert",

    "data": {

        "alert_type": "price_threshold",

        "message": "قیمت بیت‌کوین از ۴۵۰۰۰ دلار عبور کرد",

        "severity": "info"

    },

    "timestamp": "2024-01-15T10:31:00"

}

```

#### Heartbeat
```json

{

    "type": "heartbeat",

    "timestamp": "2024-01-15T10:31:10"

}

```

### 2. پیام‌های کلاینت (Client → Server)

#### Subscribe
```json

{

    "type": "subscribe",

    "group": "market"

}

```

گروه‌های موجود:
- `market` - به‌روزرسانی‌های بازار
- `prices` - تغییرات قیمت
- `news` - اخبار
- `alerts` - هشدارها
- `all` - همه

#### Unsubscribe
```json

{

    "type": "unsubscribe",

    "group": "market"

}

```

#### Request Stats
```json

{

    "type": "get_stats"

}

```

#### Ping
```json

{

    "type": "ping"

}

```

## 🎨 استفاده از کامپوننت‌های بصری

### 1. نوار وضعیت اتصال

```html

<!-- اضافه کردن به صفحه -->

<div class="connection-status-bar" id="ws-connection-status">

    <div class="ws-connection-info">

        <span class="status-dot status-dot-offline" id="ws-status-dot"></span>

        <span class="ws-status-text" id="ws-status-text">در حال اتصال...</span>

    </div>

    

    <div class="online-users-widget">

        <div class="online-users-count">

            <span class="users-icon">👥</span>

            <span class="count-number" id="active-users-count">0</span>

            <span class="count-label">کاربر آنلاین</span>

        </div>

    </div>

</div>

```

### 2. اضافه کردن CSS و JS

```html

<head>

    <link rel="stylesheet" href="/static/css/connection-status.css">

</head>

<body>

    <!-- محتوا -->

    

    <script src="/static/js/websocket-client.js"></script>

</body>

```

### 3. استفاده از Client

```javascript

// کلاینت به صورت خودکار متصل می‌شود

// در دسترس از طریق window.wsClient



// ثبت handler سفارشی

window.wsClient.on('custom_event', (message) => {

    console.log('رویداد سفارشی:', message);

});



// اتصال به وضعیت اتصال

window.wsClient.onConnection((isConnected) => {

    if (isConnected) {

        console.log('✅ متصل شد');

    } else {

        console.log('❌ قطع شد');

    }

});



// ارسال پیام

window.wsClient.send({

    type: 'custom_action',

    data: { value: 123 }

});

```

## 🔧 API Endpoints

### GET `/api/sessions`
دریافت لیست session‌های فعال

**Response:**
```json

{

    "sessions": {

        "550e8400-...": {

            "session_id": "550e8400-...",

            "client_type": "browser",

            "connected_at": "2024-01-15T10:00:00",

            "last_activity": "2024-01-15T10:30:00"

        }

    },

    "stats": {

        "active_connections": 15,

        "total_sessions": 23

    }

}

```

### GET `/api/sessions/stats`
دریافت آمار اتصالات

**Response:**
```json

{

    "active_connections": 15,

    "total_sessions": 23,

    "messages_sent": 1250,

    "messages_received": 450,

    "client_types": {

        "browser": 12,

        "api": 2

    }

}

```

### POST `/api/broadcast`
ارسال پیام به همه کلاینت‌ها

**Request:**
```json

{

    "message": {

        "type": "notification",

        "text": "سیستم به‌روز شد"

    },

    "group": "all"

}

```

## 🧪 تست

### 1. باز کردن صفحه تست:
```

http://localhost:8000/test_websocket.html

```

### 2. چک کردن اتصال:
- نوار بالای صفحه باید سبز شود (متصل)
- تعداد کاربران آنلاین باید نمایش داده شود

### 3. تست دستورات:
- کلیک روی دکمه‌های مختلف
- مشاهده لاگ پیام‌ها در پنل پایین

### 4. تست چند تب:
- باز کردن چند تب مرورگر
- تعداد کاربران آنلاین باید افزایش یابد

## 📊 مانیتورینگ

### لاگ‌های سرور:
```bash

# مشاهده لاگ‌های WebSocket

tail -f logs/app.log | grep "WebSocket"

```

### متریک‌ها:
- تعداد اتصالات فعال
- تعداد کل session‌ها
- پیام‌های ارسالی/دریافتی
- توزیع انواع کلاینت

## 🔒 امنیت

### توصیه‌ها:
1. برای production از `wss://` (WebSocket Secure) استفاده کنید
2. محدودیت تعداد اتصال برای هر IP
3. Rate limiting برای پیام‌ها
4. اعتبارسنجی token برای authentication

### مثال با Token:
```javascript

const ws = new WebSocket('ws://localhost:8000/ws');

ws.onopen = () => {

    ws.send(JSON.stringify({

        type: 'auth',

        token: 'YOUR_JWT_TOKEN'

    }));

};

```

## 🐛 عیب‌یابی

### مشکل: اتصال برقرار نمی‌شود
```bash

# چک کردن اجرای سرور

curl http://localhost:8000/health



# بررسی پورت

netstat -an | grep 8000

```

### مشکل: اتصال قطع می‌شود
- Heartbeat فعال است؟
- Proxy یا Firewall مشکل ندارد؟
- Log‌های سرور را بررسی کنید

### مشکل: پیام‌ها دریافت نمی‌شوند
- Subscribe کرده‌اید؟
- نوع پیام صحیح است؟
- کنسول مرورگر را بررسی کنید

## 📚 منابع بیشتر

- [WebSocket API - MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
- [FastAPI WebSockets](https://fastapi.tiangolo.com/advanced/websockets/)
- [websockets Python library](https://websockets.readthedocs.io/)

## 🎓 مثال کامل Integration

```html

<!DOCTYPE html>

<html lang="fa" dir="rtl">

<head>

    <link rel="stylesheet" href="/static/css/connection-status.css">

</head>

<body>

    <!-- UI Components -->

    <div class="connection-status-bar" id="ws-connection-status">

        <!-- ... -->

    </div>



    <div class="dashboard">

        <h1>تعداد کاربران: <span id="user-count">0</span></h1>

    </div>



    <script src="/static/js/websocket-client.js"></script>

    <script>

        // Custom logic

        if (window.wsClient) {

            window.wsClient.on('stats_update', (msg) => {

                document.getElementById('user-count').textContent = 

                    msg.data.active_connections;

            });

        }

    </script>

</body>

</html>

```

---

**نکته مهم:** این سیستم به صورت خودکار reconnect می‌کند و نیازی به مدیریت دستی ندارید!