docs: update readme run instructions and refine gitignore patterns

.gitignore

@@ -43,3 +43,11 @@ node_modules/
 # OS generated files
 .DS_Store
 Thumbs.db
+
+# Documentation and planning artifacts
+checklist.md
+implementation-plan.md
+product-scenario.md
+project-architecture.md
+next-steps.md
+

README.md

@@ -0,0 +1,166 @@
+# 🕵️‍♂️ دیدبان دیوار (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 اختیاری محسوب شده و خطای ۵۰۳ ایجاد نمی‌کند).