hf-data-engine/docs/persian/README_FA.md

# 🚀 Crypto Monitor ULTIMATE - نسخه توسعه‌یافته

یک سیستم مانیتورینگ و تحلیل کریپتوکارنسی قدرتمند با پشتیبانی از **100+ ارائه‌دهنده API رایگان** و سیستم پیشرفته **Provider Pool Management**.

## ✨ ویژگی‌های کلیدی

### 🎯 مدیریت ارائه‌دهندگان (Provider Management)
- ✅ **100+ ارائه‌دهنده API رایگان** از دسته‌بندی‌های مختلف
- 🔄 **سیستم Pool با استراتژی‌های چرخش مختلف**
  - Round Robin
  - Priority-based
  - Weighted Random
  - Least Used
  - Fastest Response
- 🛡️ **Circuit Breaker** برای جلوگیری از درخواست‌های مکرر به سرویس‌های خراب
- ⚡ **Rate Limiting هوشمند** برای هر ارائه‌دهنده
- 📊 **آمارگیری دقیق** از عملکرد هر ارائه‌دهنده
- 🔍 **Health Check خودکار** و دوره‌ای

### 📈 دسته‌بندی ارائه‌دهندگان

#### 💰 بازار و قیمت‌گذاری (Market Data)
- CoinGecko, CoinPaprika, CoinCap
- CryptoCompare, Nomics, Messari
- LiveCoinWatch, Cryptorank, CoinLore, CoinCodex

#### 🔗 اکسپلورر‌های بلاکچین (Blockchain Explorers)
- Etherscan, BscScan, PolygonScan
- Arbiscan, Optimistic Etherscan
- Blockchair, Blockchain.info, Ethplorer

#### 🏦 دیفای (DeFi Protocols)
- DefiLlama, Aave, Compound
- Uniswap V3, PancakeSwap, SushiSwap
- Curve Finance, 1inch, Yearn Finance

#### 🖼️ NFT
- OpenSea, Rarible, Reservoir, NFTPort

#### 📰 اخبار و شبکه‌های اجتماعی (News & Social)
- CryptoPanic, NewsAPI
- CoinDesk RSS, Cointelegraph RSS, Bitcoinist RSS
- Reddit Crypto, LunarCrush

#### 💭 تحلیل احساسات (Sentiment Analysis)
- Alternative.me (Fear & Greed Index)
- Santiment, LunarCrush

#### 📊 تحلیل و آنالیتیکس (Analytics)
- Glassnode, IntoTheBlock
- Coin Metrics, Kaiko

#### 💱 صرافی‌ها (Exchanges)
- Binance, Kraken, Coinbase
- Bitfinex, Huobi, KuCoin
- OKX, Gate.io, Bybit

#### 🤗 Hugging Face Models
- مدل‌های تحلیل احساسات (Sentiment Analysis)
- مدل‌های دسته‌بندی متن (Text Classification)
- مدل‌های Zero-Shot Classification

## 🏗️ معماری سیستم

```

┌─────────────────────────────────────────────────┐

│           Unified Dashboard (HTML/JS)           │

│  📊 نمایش داده‌ها | 🔄 مدیریت Pools | 📈 آمار │

└────────────────────┬────────────────────────────┘

                     │

                     ▼

┌─────────────────────────────────────────────────┐

│         FastAPI Server (Python)                 │

│  🌐 REST API | WebSocket | Background Tasks    │

└────────────────────┬────────────────────────────┘

                     │

                     ▼

┌─────────────────────────────────────────────────┐

│         Provider Manager (Core Logic)           │

│  🔄 Rotation | 🛡️ Circuit Breaker | 📊 Stats   │

└────────────────────┬────────────────────────────┘

                     │

     ┌───────────────┼───────────────┐

     ▼               ▼               ▼

┌─────────┐    ┌─────────┐    ┌─────────┐

│ Pool 1  │    │ Pool 2  │    │ Pool N  │

│ Market  │    │  DeFi   │    │   NFT   │

└────┬────┘    └────┬────┘    └────┬────┘

     │              │              │

     └──────┬───────┴──────┬───────┘

            ▼              ▼

    ┌──────────────┐  ┌──────────────┐

    │  Provider 1  │  │  Provider N  │

    │ (CoinGecko)  │  │  (Binance)   │

    └──────────────┘  └──────────────┘

```

## 📦 نصب و راه‌اندازی

### پیش‌نیازها
```bash

Python 3.8+

pip

```

### نصب وابستگی‌ها
```bash

pip install fastapi uvicorn aiohttp pydantic

```

### اجرای سرور
```bash

# روش 1: مستقیم

python api_server_extended.py



# روش 2: با uvicorn

uvicorn api_server_extended:app --reload --host 0.0.0.0 --port 8000

```

### دسترسی به داشبورد
```

http://localhost:8000

```

## 🔧 استفاده از API

### 🌐 Endpoints اصلی

#### **وضعیت سیستم**
```http

GET /health

GET /api/status

GET /api/stats

```

#### **مدیریت ارائه‌دهندگان**
```http

GET    /api/providers                    # لیست همه

GET    /api/providers/{provider_id}      # جزئیات یک ارائه‌دهنده

POST   /api/providers/{provider_id}/health-check

GET    /api/providers/category/{category}

```

#### **مدیریت Pool‌ها**
```http

GET    /api/pools                        # لیست همه Pool‌ها

GET    /api/pools/{pool_id}              # جزئیات یک Pool

POST   /api/pools                        # ایجاد Pool جدید

DELETE /api/pools/{pool_id}              # حذف Pool



POST   /api/pools/{pool_id}/members      # افزودن عضو

DELETE /api/pools/{pool_id}/members/{provider_id}

POST   /api/pools/{pool_id}/rotate       # چرخش دستی

GET    /api/pools/history                # تاریخچه چرخش‌ها

```

### 📝 نمونه‌های استفاده

#### ایجاد Pool جدید
```bash

curl -X POST http://localhost:8000/api/pools \

  -H "Content-Type: application/json" \

  -d '{

    "name": "My Market Pool",

    "category": "market_data",

    "rotation_strategy": "weighted",

    "description": "Pool for market data providers"

  }'

```

#### افزودن ارائه‌دهنده به Pool
```bash

curl -X POST http://localhost:8000/api/pools/my_market_pool/members \

  -H "Content-Type: application/json" \

  -d '{

    "provider_id": "coingecko",

    "priority": 10,

    "weight": 100

  }'

```

#### چرخش Pool
```bash

curl -X POST http://localhost:8000/api/pools/my_market_pool/rotate \

  -H "Content-Type: application/json" \

  -d '{"reason": "manual rotation"}'

```

## 🎮 استفاده از Python API

```python

import asyncio

from provider_manager import ProviderManager



async def main():

    # ایجاد مدیر

    manager = ProviderManager()

    

    # بررسی سلامت همه

    await manager.health_check_all()

    

    # دریافت ارائه‌دهنده از Pool

    provider = manager.get_next_from_pool("primary_market_data_pool")

    if provider:

        print(f"Selected: {provider.name}")

        print(f"Success Rate: {provider.success_rate}%")

    

    # آمار کلی

    stats = manager.get_all_stats()

    print(f"Total Providers: {stats['summary']['total_providers']}")

    print(f"Online: {stats['summary']['online']}")

    

    # صادرکردن آمار

    manager.export_stats("my_stats.json")

    

    await manager.close_session()



asyncio.run(main())

```

## 📊 استراتژی‌های چرخش Pool

### 1️⃣ Round Robin
هر بار به ترتیب یک ارائه‌دهنده انتخاب می‌شود.
```python

rotation_strategy = "round_robin"

```

### 2️⃣ Priority-Based
ارائه‌دهنده با بالاترین اولویت انتخاب می‌شود.
```python

rotation_strategy = "priority"

# Provider with priority=10 selected over priority=5

```

### 3️⃣ Weighted Random
انتخاب تصادفی با وزن‌دهی.
```python

rotation_strategy = "weighted"

# Provider with weight=100 has 2x chance vs weight=50

```

### 4️⃣ Least Used
ارائه‌دهنده‌ای که کمتر استفاده شده انتخاب می‌شود.
```python

rotation_strategy = "least_used"

```

### 5️⃣ Fastest Response
ارائه‌دهنده با سریع‌ترین زمان پاسخ انتخاب می‌شود.
```python

rotation_strategy = "fastest_response"

```

## 🛡️ Circuit Breaker

سیستم Circuit Breaker به‌طور خودکار ارائه‌دهندگان مشکل‌دار را غیرفعال می‌کند:

- **آستانه**: 5 خطای متوالی
- **مدت زمان قطع**: 60 ثانیه
- **بازیابی خودکار**: پس از اتمام timeout

```python

# Circuit Breaker خودکار در Provider

if provider.consecutive_failures >= 5:

    provider.circuit_breaker_open = True

    provider.circuit_breaker_open_until = time.time() + 60

```

## 📈 مانیتورینگ و لاگ

### بررسی سلامت دوره‌ای
سیستم هر 30 ثانیه به‌طور خودکار سلامت همه ارائه‌دهندگان را بررسی می‌کند.

### آمارگیری
- **تعداد کل درخواست‌ها**
- **درخواست‌های موفق/ناموفق**
- **نرخ موفقیت (Success Rate)**
- **میانگین زمان پاسخ**
- **تعداد چرخش‌های Pool**

### صادرکردن آمار
```python

manager.export_stats("stats_export.json")

```

## 🔐 مدیریت API Key

برای ارائه‌دهندگانی که نیاز به API Key دارند:

1. فایل `.env` بسازید:
```env

# Market Data

COINMARKETCAP_API_KEY=your_key_here

CRYPTOCOMPARE_API_KEY=your_key_here



# Blockchain Data

ALCHEMY_API_KEY=your_key_here

INFURA_API_KEY=your_key_here



# News

NEWSAPI_KEY=your_key_here



# Analytics

GLASSNODE_API_KEY=your_key_here

```

2. در کد خود از `python-dotenv` استفاده کنید:
```python

from dotenv import load_dotenv

import os



load_dotenv()

api_key = os.getenv("COINMARKETCAP_API_KEY")

```

## 🎨 داشبورد وب

داشبورد شامل تب‌های زیر است:

### 📊 Market
- آمار کلی بازار
- لیست کریپتوکارنسی‌های برتر
- نمودارها (Dominance, Fear & Greed)
- ترندینگ و DeFi

### 📡 API Monitor
- وضعیت همه ارائه‌دهندگان
- زمان پاسخ
- آخرین بررسی سلامت
- تحلیل احساسات (HuggingFace)

### ⚡ Advanced
- لیست API‌ها
- اکسپورت JSON/CSV
- پشتیبان‌گیری
- پاک‌سازی Cache
- لاگ فعالیت‌ها

### ⚙️ Admin
- افزودن API جدید
- تنظیمات
- آمار کلی

### 🤗 HuggingFace
- وضعیت سلامت
- لیست مدل‌ها و دیتاست‌ها
- جستجو در Registry
- تحلیل احساسات آنلاین

### 🔄 Pools
- مدیریت Pool‌ها
- افزودن/حذف اعضا
- چرخش دستی
- تاریخچه چرخش‌ها
- آمار تفصیلی

## 🧪 تست

```bash

# تست Provider Manager

python provider_manager.py



# تست سرور API

python api_server_extended.py

```

## 📄 فایل‌های پروژه

```

crypto-monitor-hf-full-fixed-v4-realapis/

├── unified_dashboard.html           # داشبورد وب اصلی

├── providers_config_extended.json   # تنظیمات 100+ ارائه‌دهنده

├── provider_manager.py              # هسته مدیریت Provider & Pool

├── api_server_extended.py           # سرور FastAPI

├── README_FA.md                     # راهنمای فارسی (این فایل)

└── .env.example                     # نمونه متغیرهای محیطی

```

## 🚀 ویژگی‌های آینده

- [ ] پشتیبانی از WebSocket برای داده‌های Realtime
- [ ] سیستم صف (Queue) برای درخواست‌های سنگین
- [ ] Cache با Redis
- [ ] Dashboard پیشرفته با React/Vue
- [ ] Alerting System (Telegram/Email)
- [ ] Machine Learning برای پیش‌بینی بهترین Provider
- [ ] Multi-tenant Support
- [ ] Docker & Kubernetes Support

## 🤝 مشارکت

برای مشارکت:
1. Fork کنید
2. یک branch جدید بسازید: `git checkout -b feature/amazing-feature`
3. تغییرات را commit کنید: `git commit -m 'Add amazing feature'`
4. Push کنید: `git push origin feature/amazing-feature`
5. Pull Request ایجاد کنید

## 📝 لایسنس

این پروژه تحت لایسنس MIT منتشر شده است.

## 💬 پشتیبانی

در صورت بروز مشکل یا سوال:
- Issue در GitHub باز کنید
- به بخش Discussions مراجعه کنید

## 🙏 تشکر

از تمام ارائه‌دهندگان API رایگان که این پروژه را ممکن کردند:
- CoinGecko, CoinPaprika, CoinCap
- Etherscan, BscScan و تمام Block Explorers
- DefiLlama, OpenSea و...
- Hugging Face برای مدل‌های ML

---

**ساخته شده با ❤️ برای جامعه کریپتو**