🕵️‍♂️ دیدبان دیوار (Smart Divar Crawler)

یک سامانه هوشمند و داشبورد تعاملی برای پایش خودکار، فیلترینگ و ارزیابی آگهی‌های وب‌سایت دیوار با استفاده از هوش مصنوعی (OpenAI / OpenRouter API) و اطلاع‌رسانی فوری از طریق تلگرام.

---

🚀 ویژگی‌های کلیدی

• تعریف پویای تسک‌های پایش (Crawl Tasks): ثبت لینک‌های فیلتر شده دسته‌بندی‌های دیوار به همراه بازه زمانی پایش (مثلاً هر ۱۵ دقیقه) و ساعت شروع/پایان مجاز فعالیت روزانه.
• ارزیابی هوشمند با هوش مصنوعی (AI Evaluation): تحلیل محتوای متنی، قیمت و مشخصات آگهی‌ها بر اساس پرامپت دلخواه کاربر (مثلاً: "بررسی کن آیا آگهی رهن کامل فوری و زیر قیمت منطقه است یا خیر") با استفاده از فرمت پاسخ ساختاریافته (Structured JSON).
• فیلترینگ و پرچم‌گذاری دقیق: دسته‌بندی و جداسازی هوشمند آگهی‌های منطبق بر معیارهای کاربر.
• اطلاع‌رسانی فوری تلگرام: ارسال سریع آگهی‌های تأیید شده به همراه جزئیات و علت انتخاب هوش مصنوعی به کانال تلگرام مشخص شده.
• داشبورد تعاملی و زیبا:
  • ثبت و مدیریت کرالرها (تسک‌ها).
  • لاگ جزئیات اجراهای گذشته (تعداد آگهی‌های اسکرپ شده، ارزیابی شده و پرچم‌گذاری شده).
  • فید آگهی‌های کشف شده با قابلیت فیلتر بر اساس تسک و وضعیت پرچم‌گذاری.
  • تست و اجرای دستی فوری کرالرها.
  • سیستم پایش سلامت (Health Check) پایگاه‌داده و سرویس پیام‌رسان.
• آماده‌سازی کامل جهت استقرار داکر (Docker & Linux Ready): تنظیمات چندکانتینره بهینه شامل دیتابیس PostgreSQL، بروکر Redis، Celery Worker و فرانت‌اند React.

---

🛠 تکنولوژی‌های مورد استفاده

بخش بک‌اند (Backend)

• فریم‌ورک: Django 5.x & Django REST Framework (DRF)
• پردازش پس‌زمینه (Task Queue): Celery & Celery-Beat (با پشتیبانی از Gevent)
• پایگاه‌داده: PostgreSQL 16 (در حالت داکر) / SQLite3 (در حالت توسعه محلی)
• هوش مصنوعی: OpenAI Python SDK / OpenRouter API (با خروجی‌های ساختاریافته Structured JSON)
• ابزار اسکرپینگ: BeautifulSoup4 & Requests

بخش فرانت‌اند (Frontend)

• فریم‌ورک: React 18 & Vite
• طراحی و استایل: Vanilla CSS & TailwindCSS (کامپوننت‌های مدرن و شیشه‌ای)
• آیکون‌ها: Lucide React

محیط اجرای کانتینری (Infrastructure)

• محیط کانتینری: Docker & Docker Compose
• کارگزار پیام / کش: Redis 7 Alpine
• پایگاه‌داده پروداکشن: PostgreSQL 16 Alpine

---

📂 ساختار پروژه

divar-crawler/
│
├── backend/                  # کدها و تنظیمات بک‌اند جنگو
│   ├── config/               # تنظیمات اصلی جنگو (settings.py, urls.py)
│   ├── core/                 # ماژول‌های پایه و ساختاری (Health-checks, Celery setup)
│   ├── crawler/              # مدیریت تسک‌های پایش و پردازش HTML دیوار
│   └── ads/                  # ذخیره آگهی‌ها، ارزیابی هوش مصنوعی و اطلاع‌رسانی تلگرام
│
├── frontend/                 # فرانت‌اند سمت کلاینت (Vite + React)
│   ├── src/
│   │   ├── App.jsx           # کامپوننت و ساختار اصلی فرانت‌اند (داشبورد)
│   │   ├── App.css           # استایل‌های برنامه
│   │   └── main.jsx          # نقطه ورود برنامه React
│   ├── Dockerfile            # داکرفایل اختصاصی فرانت‌اند
│   └── vite.config.js        # تنظیمات پروکسی و وب سرور فرانت‌اند
│
├── Dockerfile.backend        # داکرفایل اختصاصی بک‌اند و ورکرها
├── docker-compose.yml        # فایل ارکستراسیون سرویس‌های داکر
├── entrypoint.sh             # اسکریپت نقطه ورود کانتینر بک‌اند (با تصحیح خودکار CRLF/LF)
├── .dockerignore             # بهینه‌سازی حجم بیلد و جلوگیری از انتقال فایل‌های زاید
├── requirements.txt          # وابستگی‌های پایتون
├── .env.example              # الگوی متغیرهای محیطی
└── .env                      # تنظیمات و متغیرهای محرمانه محیطی

---

🐳 راه‌اندازی با داکر (روی لینوکس یا سرور لینوکس) - روش پیشنهادی

برای بیلد و اجرای کامل تمامی سرویس‌ها روی سیستم لینوکس یا سرور لینوکس (شامل PostgreSQL، Redis، Backend، Celery Worker و Frontend):

۱. تنظیم متغیرهای محیطی

فایل .env.example را به .env کپی کنید:

cp .env.example .env

مقادیر OPENAI_API_KEY و TELEGRAM_BOT_TOKEN را در فایل .env تنظیم کنید.

۲. بیلد و اجرای داکر

docker compose up --build -d

جهت مشاهده وضعیت سرویس‌ها:

docker compose ps

جهت مشاهده لاگ‌های همزمان:

docker compose logs -f

۳. دسترسی به داشبورد و API

• داشبورد فرانت‌اند React: http://<SERVER_IP>:5173/
• بک‌اند جنگو REST API: http://<SERVER_IP>:8000/api/
• بررسی سلامت سیستم: http://<SERVER_IP>:8000/api/health/

---

⚙️ راه‌اندازی و اجرا در محیط توسعه محلی (Local Windows)

۱. تنظیم فایل .env

copy .env.example .env

۲. اجرای بک‌اند جنگو

.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python backend/manage.py migrate
python backend/manage.py runserver

۳. اجرای فرانت‌اند React

cd frontend
..\.node\npm.cmd install
..\.node\npm.cmd run dev

داشبورد روی http://localhost:5173/ اجرا خواهد شد.

---

🧪 اجرای تست‌های واحد (Unit Tests)

جهت حصول اطمینان از سلامت تمامی اندپوینت‌ها و مدل‌ها:

.venv\Scripts\python backend/manage.py test backend

---

📡 اندپوینت‌های اصلی API

• تسک‌های پایش (/api/crawlers/):
  • GET /api/crawlers/: دریافت لیست تمام تسک‌ها.
  • POST /api/crawlers/: ثبت تسک کرالر جدید.
  • DELETE /api/crawlers/<id>/: حذف تسک و اجراهای مربوطه.
  • POST /api/crawlers/<id>/trigger/: اجرای فوری و دستی کرالر.
  • GET /api/crawlers/<id>/runs/: سوابق اجراهای گذشته.
• آگهی‌ها و ارزیابی‌ها (/api/ads/):
  • GET /api/ads/: دریافت لیست آگهی‌ها (با فیلتر is_flagged و crawl_task).
• سلامت سامانه (/api/health/):
  • GET /api/health/: بررسی اتصال دیتابیس و ردیس.