From fde183aa78a1e66713ed9c0deaba7a6d39ace530 Mon Sep 17 00:00:00 2001 From: PouyaKhajavi Date: Sun, 9 Aug 2026 13:24:24 +0330 Subject: [PATCH] docs: update main and frontend READMEs with linux docker deployment guide --- README.md | 124 ++++++++++++++++++++------------------------- frontend/README.md | 57 +++++++++++++++++---- 2 files changed, 102 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 4375b0f..909b1f1 100644 --- a/README.md +++ b/README.md @@ -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://:5173/` +- **بک‌اند جنگو REST API**: `http://:8000/api/` +- **بررسی سلامت سیستم**: `http://: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//`: حذف تسک (همراه با حذف آبشاری اجراها و ارزیابی‌های مربوطه). - - `POST /api/crawlers//trigger/`: اجرای فوری دستی کرالر. - - `GET /api/crawlers//runs/`: دریافت سوابق و وضعیت اجراهای تسک. + - `POST /api/crawlers/`: ثبت تسک کرالر جدید. + - `DELETE /api/crawlers//`: حذف تسک و اجراهای مربوطه. + - `POST /api/crawlers//trigger/`: اجرای فوری و دستی کرالر. + - `GET /api/crawlers//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/`: بررسی اتصال دیتابیس و ردیس. diff --git a/frontend/README.md b/frontend/README.md index d937833..2fcf55b 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -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.