# 🕵️‍♂️ دیدبان دیوار (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

---

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

```text
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` تغییر دهید:
```bash
copy .env.example .env
```
سپس مقادیر زیر را در آن تنظیم کنید:
- `OPENAI_API_KEY`: کلید اختصاصی API وب‌سایت OpenAI (جهت پردازش هوشمند آگهی‌ها).
- `TELEGRAM_BOT_TOKEN`: توکن ربات تلگرامی شما (جهت ارسال پیام).
- `CORS_ALLOWED_ORIGINS` و `ALLOWED_HOSTS`: آدرس‌های مجاز برای دسترسی به برنامه.

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

---

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

۱. محیط مجازی پایتون را فعال کنید:
```powershell
.venv\Scripts\Activate.ps1
```

۲. بسته‌های مورد نیاز پایتون را نصب کنید:
```bash
pip install -r requirements.txt
```

۳. ساختار پایگاه‌داده را بسازید (اجرای مهاجرت‌ها):
```bash
python backend/manage.py migrate
```

۴. سرور توسعه جنگو را روشن کنید:
```bash
python backend/manage.py runserver
```
اکنون بک‌اند جنگو روی پورت `8000` در دسترس است. برای بررسی وضعیت سرویس‌ها می‌توانید به آدرس `http://127.0.0.1:8000/api/health/` مراجعه کنید.

---

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

در صورتی که می‌خواهید تسک‌ها به صورت کاملاً غیرهمزمان و واقعی پایش شوند:
1. مقدار `CELERY_TASK_ALWAYS_EAGER` را در تنظیمات به `False` تغییر داده و مطمئن شوید که سرور Redis روی سیستم شما فعال است.
2. با اجرای دستور زیر در یک ترمینال جداگانه، ورکر سلری را اجرا کنید:
```bash
celery -A core worker -l info
```
3. برای پایش خودکار دوره‌ای تسک‌ها، سرویس مدیریت زمان‌بندی (Celery Beat) را روشن کنید:
```bash
celery -A core beat -l info
```

---

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

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

۱. وارد پوشه فرانت‌اند شوید:
```powershell
cd frontend
```

۲. وابستگی‌های فرانت‌اند را نصب کنید (در صورت نیاز):
```powershell
..\.node\npm.cmd install
```

۳. برنامه را در حالت توسعه (Development) اجرا کنید:
```powershell
..\.node\npm.cmd run dev
```
اکنون فرانت‌اند در آدرس `http://localhost:5173/` قابل دسترس خواهد بود و درخواست‌ها را به صورت خودکار به پورت `8000` بک‌اند پروکسی می‌کند.

۴. جهت خروجی گرفتن برای محیط تولید (Production Build):
```powershell
..\.node\npm.cmd run build
```

---

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

برای اجرای تمامی تست‌های مربوط به کرالر، ارزیابی، و سناریوهای بک‌اند دستور زیر را وارد کنید:
```bash
.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 اختیاری محسوب شده و خطای ۵۰۳ ایجاد نمی‌کند).