From d7295c49d0dad4be3a7f5fae9608899a1ffcc814 Mon Sep 17 00:00:00 2001 From: PouyaKhajavi Date: Sun, 9 Aug 2026 08:14:45 +0330 Subject: [PATCH] docs: update readme run instructions and refine gitignore patterns --- .gitignore | 8 +++ README.md | 166 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 174 insertions(+) diff --git a/.gitignore b/.gitignore index c44f1cf..876fde2 100644 --- a/.gitignore +++ b/.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 + diff --git a/README.md b/README.md index e69de29..4375b0f 100644 --- a/README.md +++ b/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//`: حذف تسک (همراه با حذف آبشاری اجراها و ارزیابی‌های مربوطه). + - `POST /api/crawlers//trigger/`: اجرای فوری دستی کرالر. + - `GET /api/crawlers//runs/`: دریافت سوابق و وضعیت اجراهای تسک. +- **آگهی‌ها و ارزیابی‌ها (`/api/ads/`)**: + - `GET /api/ads/`: لیست تمام ارزیابی‌های انجام شده (فیلتر بر اساس `is_flagged` و `crawl_task`). +- **سلامت سامانه (`/api/health/`)**: + - `GET /api/health/`: بررسی پایداری پایگاه‌داده و اتصال ردیس (پینگ ردیس در زمان فعال بودن Celery Eager Mode اختیاری محسوب شده و خطای ۵۰۳ ایجاد نمی‌کند).