PouyaKhajavi
/
divar-crawler
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
Browse Source

docs: update main and frontend READMEs with linux docker deployment guide

master
PouyaKhajavi 1 day ago
parent
ac301db614
commit
fde183aa78
2 changed files with 102 additions and 79 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 124
      README.md
  2. 57
      frontend/README.md

124
README.md
View File

@ -1,6 +1,6 @@
# 🕵️‍♂️ دیدبان دیوار (Smart Divar Crawler)
یک سامانه هوشمند و داشبورد تعاملی برای پایش خودکار، فیلترینگ و ارزیابی آگهی‌های وب‌سایت دیوار با استفاده از هوش مصنوعی (OpenAI GPT-4o-mini) و اطلاع‌رسانی فوری از طریق تلگرام.
یک سامانه هوشمند و داشبورد تعاملی برای پایش خودکار، فیلترینگ و ارزیابی آگهی‌های وب‌سایت دیوار با استفاده از هوش مصنوعی (OpenAI / OpenRouter API) و اطلاع‌رسانی فوری از طریق تلگرام.
---
@ -16,6 +16,7 @@
- فید آگهی‌های کشف شده با قابلیت فیلتر بر اساس تسک و وضعیت پرچم‌گذاری.
- تست و اجرای دستی فوری کرالرها.
- سیستم پایش سلامت (Health Check) پایگاه‌داده و سرویس پیام‌رسان.
- **آماده‌سازی کامل جهت استقرار داکر (Docker & Linux Ready)**: تنظیمات چندکانتینره بهینه شامل دیتابیس PostgreSQL، بروکر Redis، Celery Worker و فرانت‌اند React.
---
@ -23,16 +24,21 @@
### **بخش بک‌اند (Backend)**
- **فریم‌ورک**: Django 5.x & Django REST Framework (DRF)
- **پردازش پس‌زمینه (Task Queue)**: Celery & Celery-Beat
- **پایگاه‌داده**: SQLite (قابل ارتقا به PostgreSQL/PostgreSQL در محیط تولید)
- **هوش مصنوعی**: OpenAI Python SDK (مدل `gpt-4o-mini` با پاسخ‌های ساختاریافته)
- **پردازش پس‌زمینه (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 (بصورت کامپوننت‌های بهینه‌سازی شده)
- **طراحی و استایل**: Vanilla CSS & TailwindCSS (کامپوننت‌های مدرن و شیشه‌ای)
- **آیکون‌ها**: Lucide React
### **محیط اجرای کانتینری (Infrastructure)**
- **محیط کانتینری**: Docker & Docker Compose
- **کارگزار پیام / کش**: Redis 7 Alpine
- **پایگاه‌داده پروداکشن**: PostgreSQL 16 Alpine
---
## 📂 ساختار پروژه
@ -51,101 +57,79 @@ divar-crawler/
│ │ ├── App.jsx # کامپوننت و ساختار اصلی فرانت‌اند (داشبورد)
│ │ ├── App.css # استایل‌های برنامه
│ │ └── main.jsx # نقطه ورود برنامه React
│ ├── Dockerfile # داکرفایل اختصاصی فرانت‌اند
│ └── vite.config.js # تنظیمات پروکسی و وب سرور فرانت‌اند
│
├── .node/ # نسخه پرتابل و محلی Node.js مخصوص ویندوز (جهت بیلد آسان)
├── .venv/ # محیط مجازی پایتون
├── Dockerfile.backend # داکرفایل اختصاصی بک‌اند و ورکرها
├── docker-compose.yml # فایل ارکستراسیون سرویس‌های داکر
├── entrypoint.sh # اسکریپت نقطه ورود کانتینر بک‌اند (با تصحیح خودکار CRLF/LF)
├── .dockerignore # بهینه‌سازی حجم بیلد و جلوگیری از انتقال فایل‌های زاید
├── requirements.txt # وابستگی‌های پایتون
├── .env.example # الگوی متغیرهای محیطی
└── .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
```
برای بیلد و اجرای کامل تمامی سرویس‌ها روی سیستم لینوکس یا سرور لینوکس (شامل PostgreSQL، Redis، Backend، Celery Worker و Frontend):
۲. بسته‌های مورد نیاز پایتون را نصب کنید:
### ۱. تنظیم متغیرهای محیطی
فایل `.env.example` را به `.env` کپی کنید:
```bash
pip install -r requirements.txt
cp .env.example .env
```
مقادیر `OPENAI_API_KEY` و `TELEGRAM_BOT_TOKEN` را در فایل `.env` تنظیم کنید.
۳. ساختار پایگاه‌داده را بسازید (اجرای مهاجرت‌ها):
### ۲. بیلد و اجرای داکر
```bash
python backend/manage.py migrate
```
۴. سرور توسعه جنگو را روشن کنید:
```bash
python backend/manage.py runserver
docker compose up --build -d
```
اکنون بک‌اند جنگو روی پورت `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
docker compose ps
```
3. برای پایش خودکار دوره‌ای تسک‌ها، سرویس مدیریت زمان‌بندی (Celery Beat) را روشن کنید:
جهت مشاهده لاگ‌های همزمان:
```bash
celery -A core beat -l info
docker compose logs -f
```
---
### ۳. دسترسی به داشبورد و API
- **داشبورد فرانت‌اند React**: `http://<SERVER_IP>:5173/`
- **بک‌اند جنگو REST API**: `http://<SERVER_IP>:8000/api/`
- **بررسی سلامت سیستم**: `http://<SERVER_IP>:8000/api/health/`
### ۴. راه‌اندازی بخش فرانت‌اند (React)
---
پروژه شامل یک نسخه محلی و آماده از Node.js در پوشه `.node` است که نیازی به نصب سراسری Node در ویندوز ندارد.
## ⚙️ راه‌اندازی و اجرا در محیط توسعه محلی (Local Windows)
۱. وارد پوشه فرانت‌اند شوید:
### ۱. تنظیم فایل `.env`
```powershell
cd frontend
copy .env.example .env
```
۲. وابستگی‌های فرانت‌اند را نصب کنید (در صورت نیاز):
### ۲. اجرای بک‌اند جنگو
```powershell
..\.node\npm.cmd install
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python backend/manage.py migrate
python backend/manage.py runserver
```
۳. برنامه را در حالت توسعه (Development) اجرا کنید:
### ۳. اجرای فرانت‌اند React
```powershell
cd frontend
..\.node\npm.cmd install
..\.node\npm.cmd run dev
```
اکنون فرانت‌اند در آدرس `http://localhost:5173/` قابل دسترس خواهد بود و درخواست‌ها را به صورت خودکار به پورت `8000` بک‌اند پروکسی می‌کند.
۴. جهت خروجی گرفتن برای محیط تولید (Production Build):
```powershell
..\.node\npm.cmd run build
```
داشبورد روی `http://localhost:5173/` اجرا خواهد شد.
---
## 🧪 اجرای تست‌های واحد (Unit Tests)
برای اجرای تمامی تست‌های مربوط به کرالر، ارزیابی، و سناریوهای بک‌اند دستور زیر را وارد کنید:
جهت حصول اطمینان از سلامت تمامی اندپوینت‌ها و مدل‌ها:
```bash
.venv\Scripts\python backend/manage.py test backend
```
@ -156,11 +140,11 @@ cd frontend
- **تسک‌های پایش (`/api/crawlers/`)**:
- `GET /api/crawlers/`: دریافت لیست تمام تسک‌ها.
- `POST /api/crawlers/`: ثبت یک تسک کرالر جدید.
- `DELETE /api/crawlers/<id>/`: حذف تسک (همراه با حذف آبشاری اجراها و ارزیابی‌های مربوطه).
- `POST /api/crawlers/<id>/trigger/`: اجرای فوری دستی کرالر.
- `GET /api/crawlers/<id>/runs/`: دریافت سوابق و وضعیت اجراهای تسک.
- `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`).
- `GET /api/ads/`: دریافت لیست آگهی‌ها (با فیلتر `is_flagged` و `crawl_task`).
- **سلامت سامانه (`/api/health/`)**:
- `GET /api/health/`: بررسی پایداری پایگاه‌داده و اتصال ردیس (پینگ ردیس در زمان فعال بودن Celery Eager Mode اختیاری محسوب شده و خطای ۵۰۳ ایجاد نمی‌کند).
- `GET /api/health/`: بررسی اتصال دیتابیس و ردیس.

57
frontend/README.md
View File

@ -1,16 +1,55 @@
# React + Vite
# 💻 Divar Crawler Dashboard (React + Vite)
This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
The frontend client for the **Intelligent Divar Ads Crawler**, built with React 18, Vite, Lucide React icons, and TailwindCSS.
Currently, two official plugins are available:
---
- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
## 🎨 Features & Capabilities
## React Compiler
- **Crawler Management**: Dynamic form modal for creating and updating Divar crawl tasks (title, Divar search URL, AI prompt, interval, allowed hours window, Telegram channel, active status).
- **Manual Trigger**: Immediate execution button to test scraper and AI evaluation flows on-demand.
- **Ads Feed**: Filterable view of scraped ads displaying price, location, AI evaluation decision (`is_flagged`), confidence score, and extracted reasoning.
- **Execution History Logs**: Detailed execution run logs with status indicators (`RUNNING`, `SUCCESS`, `FAILED`) and error log modals.
- **System Health Indicator**: Real-time polling monitoring status of PostgreSQL database and Redis background broker.
The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
---
## Expanding the Oxlint configuration
## 🛠 Project Structure
If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and Oxlint's TypeScript related rules in your project.
```text
frontend/
├── src/
│ ├── App.jsx # Main dashboard component handling tabs, modals, and API integration
│ ├── App.css # Custom styles and glassmorphism styling
│ ├── index.css # Tailwind & global font declarations
│ └── main.jsx # React application entry point
├── Dockerfile # Node 22 slim docker environment configuration
├── package.json # Project dependencies & scripts
└── vite.config.js # API proxy configuration (`/api` -> backend:8000 or 127.0.0.1:8000)
```
---
## 🚀 Running Locally
### Development Mode (Local Node)
```bash
npm install
npm run dev
```
The application will run at `http://localhost:5173/` and proxy API calls to `http://127.0.0.1:8000`.
### Production Build
```bash
npm run build
```
---
## 🐳 Docker Execution
The frontend is included as part of the multi-container stack in the root `docker-compose.yml`:
```bash
docker compose up frontend -d
```
Environment variable `VITE_BACKEND_URL=http://backend:8000` is automatically configured to route API traffic within the Docker network.
Write Preview
Loading…
Cancel
Save