ehsan-dashboards/dashboards/VPN_chanel/README.md

138 lines
7.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# NetVibe VPN - Telegram Content Aggregation & Automated Publishing Pipeline
سیستم جامع و چندعاملی (Multi-Agent) برای رصد خودکار کانال‌های مرجع تلگرام در حوزه فیلترشکن، پروکسی و هوش مصنوعی، بازنویسی هوشمند و جذاب با لحن عامیانه ایرانی، داشبورد نظارت و ویرایش سردبیر تحت Next.js و دیسپچر انتشار خودکار به کانال رسمی `@NetVibe_VPN`.
---
## 🏗️ معماری سیستم و ایجنت‌ها
```
┌────────────────────────────────────────────────────────┐
│ Telegram Public Web │
│ (Channels: VPN, Proxy, Bypass, AI Tools) │
└───────────────────────────┬────────────────────────────┘
│
▼
┌───────────────────────────┐
│ Agent A: Web Scraper │ (httpx + BeautifulSoup)
│ (No Bot / No Ban Risk) │
└─────────────┬─────────────┘
│ Saves to raw_posts
▼
┌───────────────────────────┐
│ PostgreSQL / SQLAlchemy │ (Persistent storage & DDL)
└─────────────┬─────────────┘
│
▼
┌───────────────────────────┐
│ Agent B: LLM Curator │ (Persian Copywriting + Active Learning)
│ (GPT-4o + Few-shot Diff) │
└─────────────┬─────────────┘
│ Generates content_drafts
▼
┌───────────────────────────┐
│ Next.js Curation Panel │ (Review, Edit, Inline Diff, Tooltips)
│ (Editor / Human Gate) │
└─────────────┬─────────────┘
│ Approves into publish_queue
▼
┌───────────────────────────┐
│ Agent C: Auto Publisher │ (python-telegram-bot / Telegram Bot API)
│ (Scheduled Worker) │
└─────────────┬─────────────┘
│
▼
┌───────────────────────────┐
│ Official Telegram Channel │
│ @NetVibe_VPN │
└───────────────────────────┘
```
---
## 🌟 ویژگی‌های کلیدی
1. **Agent A (اسکرپر عمومی تلگرام)**:
- بدون نیاز به اکانت تلگرام یا سشن MTProto (حذف کامل ریسک بن شدن).
- استخراج عنوان، متن پیام، عکس/ویدیو، تعداد بازدید، واکنش‌ها و تاریخ پیام از `https://t.me/s/{channel}`.
- جلوگیری از ذخیره پست‌های تکراری با کلید یکتای ترکیبی `(channel_id, message_id)`.
2. **Agent B (موتور سنتز و یادگیری فعال)**:
- نگارش با لحن خودمانی، عامیانه، رفاقتی و به شدت روان فارسی متناسب با برند NetVibe.
- استخراج تفاوت‌ها (Diff Tracking) بین خروجی اولیه هوش مصنوعی و ویرایش‌های نهایی سردبیر با الگوریتم توالی‌یابی کاراکتری.
- تزریق خودکار تجربیات و خط‌قرمزهای سردبیر به عنوان نمونه‌های پرامپت (Active Few-shot In-context Learning).
3. **Agent C (دیسپچر انتشار خودکار)**:
- پایش مداوم صف انتشار در دیتابیس (`publish_queue`).
- ارسال مستقیم به کانال `@NetVibe_VPN` به همراه مدیا (عکس/ویدیو) و کپشن با فرمت Markdown.
- ثبت شناسه پیام منتشرشده (`telegram_msg_id`) و مدیریت خطاها با امکان تلاش مجدد.
4. **پنل مدیریت Next.js (App Router + Tailwind CSS)**:
- صندوق بررسی و ویرایش پیش‌نویس‌ها با ادیتور متنی زنده.
- رعایت دقیق استاندارد Enterprise: **تمامی کارت‌ها، ستون‌های جداول و دکمه‌ها دارای آیکون راهنما (i) (Info Tooltip) با توضیح کامل هستند.**
- مانیتورینگ وضعیت کانال‌ها و صف انتشار زمان‌بندی‌شده.
---
## 🗄️ ساختار جداول دیتابیس (PostgreSQL)
فایل مایگریشن در مسیر `backend/migrations/001_initial_schema.sql` قرار دارد:
- `channels`: ثبت کانال‌های تحت نظر، عنوان، حوزه و وضعیت رصد.
- `raw_posts`: پست‌های خام استخراج‌شده همراه با بازدید، مدیا و لینک اصلی.
- `content_drafts`: پیش‌نویس‌های تولیدشده توسط هوش مصنوعی با وضعیت‌های `pending`, `approved`, `edited`, `rejected`, `published`.
- `feedback_logs`: سوابق دیف‌های ویراستار انسانی، درصد شباهت، دسته‌بندی تغییرات و دلایل رد.
- `publish_queue`: صف زمان‌بندی‌شده انتشار با وضعیت‌های `queued`, `publishing`, `success`, `failed`.
---
## 🚀 راهنمای راه‌اندازی سریع
### روش ۱: اجرا با Docker Compose (پیشنهادی)
```bash
cd /workspace/personal/VPN_chanel
cp .env.example .env
# مقادیر TELEGRAM_BOT_TOKEN و OPENAI_API_KEY را در .env تکمیل کنید
docker compose up -d
```
- بک‌اند: `http://localhost:8000/docs`
- فرانت‌اند: `http://localhost:3000`
---
### روش ۲: راه‌اندازی محلی (Development)
#### راه‌اندازی بک‌اند:
```bash
cd /workspace/personal/VPN_chanel/backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# اجرای سرور API
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
#### راه‌اندازی فرانت‌اند:
```bash
cd /workspace/personal/VPN_chanel/frontend
npm install
npm run dev
```
---
## 📡 مسیرهای اصلی API
| متد | مسیر | توضیحات |
| :--- | :--- | :--- |
| `GET` | `/api/v1/channels` | دریافت لیست کانال‌های تحت پایش |
| `POST` | `/api/v1/channels` | افزودن کانال جدید به لیست رصد |
| `POST` | `/api/v1/pipeline/scrape-and-curate` | اجرای آنی فرآیند اسکرپ و تولید پیش‌نویس |
| `GET` | `/api/v1/drafts?status=pending` | دریافت پیش‌نویس‌ها جهت بررسی |
| `POST` | `/api/v1/drafts/{id}/action` | تایید، ویرایش یا رد پیش‌نویس |
| `GET` | `/api/v1/queue` | مشاهده صف زمان‌بندی انتشار |
| `POST` | `/api/v1/pipeline/dispatch-now` | ارسال فوری پست‌های صف به تلگرام |
| `GET` | `/api/v1/feedback-logs` | مشاهده تاریخچه ویرایش‌ها و یادگیری هوش مصنوعی |