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

---

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

```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
│   ├── 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` کپی کنید:
```bash
cp .env.example .env
```
مقادیر `OPENAI_API_KEY` و `TELEGRAM_BOT_TOKEN` را در فایل `.env` تنظیم کنید.

### ۲. بیلد و اجرای داکر
```bash
docker compose up --build -d
```
جهت مشاهده وضعیت سرویس‌ها:
```bash
docker compose ps
```
جهت مشاهده لاگ‌های همزمان:
```bash
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`
```powershell
copy .env.example .env
```

### ۲. اجرای بک‌اند جنگو
```powershell
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python backend/manage.py migrate
python backend/manage.py runserver
```

### ۳. اجرای فرانت‌اند React
```powershell
cd frontend
..\.node\npm.cmd install
..\.node\npm.cmd run dev
```
داشبورد روی `http://localhost:5173/` اجرا خواهد شد.

---

## 🧪 اجرای تست‌های واحد (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/`: بررسی اتصال دیتابیس و ردیس.