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

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://<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/`: بررسی اتصال دیتابیس و ردیس.

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.