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

یک سامانه هوشمند و داشبورد تعاملی برای پایش خودکار، فیلترینگ و ارزیابی آگهی‌های وب‌سایت دیوار با استفاده از هوش مصنوعی (OpenAI GPT-4o-mini) و اطلاع‌رسانی فوری از طریق تلگرام.

---

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

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

---

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

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

• فریم‌ورک: Django 5.x & Django REST Framework (DRF)
• پردازش پس‌زمینه (Task Queue): Celery & Celery-Beat
• پایگاه‌داده: SQLite (قابل ارتقا به PostgreSQL/PostgreSQL در محیط تولید)
• هوش مصنوعی: OpenAI Python SDK (مدل gpt-4o-mini با پاسخ‌های ساختاریافته)
• ابزار اسکرپینگ: BeautifulSoup4 & Requests

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

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

---

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

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
│   └── vite.config.js        # تنظیمات پروکسی و وب سرور فرانت‌اند
│
├── .node/                    # نسخه پرتابل و محلی Node.js مخصوص ویندوز (جهت بیلد آسان)
├── .venv/                    # محیط مجازی پایتون
└── .env                      # تنظیمات و متغیرهای محرمانه محیطی

---

⚙️ راهنمای راه‌اندازی و اجرا (محیط ویندوز)

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

ابتدا یک کپی از فایل .env.example تهیه کرده و نام آن را به .env تغییر دهید:

copy .env.example .env

سپس مقادیر زیر را در آن تنظیم کنید:

• OPENAI_API_KEY: کلید اختصاصی API وب‌سایت OpenAI (جهت پردازش هوشمند آگهی‌ها).
• TELEGRAM_BOT_TOKEN: توکن ربات تلگرامی شما (جهت ارسال پیام).
• CORS_ALLOWED_ORIGINS و ALLOWED_HOSTS: آدرس‌های مجاز برای دسترسی به برنامه.

نکته: در حالت توسعه محلی، به طور پیش‌فرض CELERY_TASK_ALWAYS_EAGER=True قرار دارد، به این معنی که پردازش‌ها به صورت آنی در سرور اصلی جنگو اجرا می‌شوند و نیازی به نصب و اجرای ردیس (Redis) به صورت محلی ندارید.

---

۲. راه‌اندازی بخش بک‌اند (Django)

۱. محیط مجازی پایتون را فعال کنید:

.venv\Scripts\Activate.ps1

۲. بسته‌های مورد نیاز پایتون را نصب کنید:

pip install -r requirements.txt

۳. ساختار پایگاه‌داده را بسازید (اجرای مهاجرت‌ها):

python backend/manage.py migrate

۴. سرور توسعه جنگو را روشن کنید:

python backend/manage.py runserver

اکنون بک‌اند جنگو روی پورت 8000 در دسترس است. برای بررسی وضعیت سرویس‌ها می‌توانید به آدرس http://127.0.0.1:8000/api/health/ مراجعه کنید.

---

۳. اجرای پردازش‌های پس‌زمینه (Celery & Redis - اختیاری در محیط توسعه)

در صورتی که می‌خواهید تسک‌ها به صورت کاملاً غیرهمزمان و واقعی پایش شوند:

1. مقدار CELERY_TASK_ALWAYS_EAGER را در تنظیمات به False تغییر داده و مطمئن شوید که سرور Redis روی سیستم شما فعال است.
2. با اجرای دستور زیر در یک ترمینال جداگانه، ورکر سلری را اجرا کنید:

celery -A core worker -l info

3. برای پایش خودکار دوره‌ای تسک‌ها، سرویس مدیریت زمان‌بندی (Celery Beat) را روشن کنید:

celery -A core beat -l info

---

۴. راه‌اندازی بخش فرانت‌اند (React)

پروژه شامل یک نسخه محلی و آماده از Node.js در پوشه .node است که نیازی به نصب سراسری Node در ویندوز ندارد.

۱. وارد پوشه فرانت‌اند شوید:

cd frontend

۲. وابستگی‌های فرانت‌اند را نصب کنید (در صورت نیاز):

..\.node\npm.cmd install

۳. برنامه را در حالت توسعه (Development) اجرا کنید:

..\.node\npm.cmd run dev

اکنون فرانت‌اند در آدرس http://localhost:5173/ قابل دسترس خواهد بود و درخواست‌ها را به صورت خودکار به پورت 8000 بک‌اند پروکسی می‌کند.

۴. جهت خروجی گرفتن برای محیط تولید (Production Build):

..\.node\npm.cmd run build

---

🧪 اجرای تست‌های واحد (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/: بررسی پایداری پایگاه‌داده و اتصال ردیس (پینگ ردیس در زمان فعال بودن Celery Eager Mode اختیاری محسوب شده و خطای ۵۰۳ ایجاد نمی‌کند).