Browse Source
feat(backend): configure celery settings and add eager-mode resilient health check
master
feat(backend): configure celery settings and add eager-mode resilient health check
master
PouyaKhajavi
1 day ago
8 changed files with 40 additions and 892 deletions
-
3backend/config/__init__.py
-
11backend/config/settings.py
-
20backend/core/celery.py
-
7backend/core/views.py
-
44checklist.md
-
128implementation-plan.md
-
162product-scenario.md
-
557project-architecture.md
@ -0,0 +1,3 @@ |
|||||
|
from core.celery import app as celery_app |
||||
|
|
||||
|
__all__ = ('celery_app',) |
||||
@ -0,0 +1,20 @@ |
|||||
|
import os |
||||
|
from celery import Celery |
||||
|
|
||||
|
# Set the default Django settings module for the 'celery' program. |
||||
|
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'config.settings') |
||||
|
|
||||
|
app = Celery('core') |
||||
|
|
||||
|
# Using a string here means the worker doesn't have to serialize |
||||
|
# the configuration object to child processes. |
||||
|
# - namespace='CELERY' means all celery-related configuration keys |
||||
|
# should have a `CELERY_` prefix. |
||||
|
app.config_from_object('django.conf:settings', namespace='CELERY') |
||||
|
|
||||
|
# Load task modules from all registered Django apps. |
||||
|
app.autodiscover_tasks() |
||||
|
|
||||
|
@app.task(bind=True, ignore_result=True) |
||||
|
def debug_task(self): |
||||
|
print(f'Request: {self.request!r}') |
||||
@ -1,44 +0,0 @@ |
|||||
# Project Checklist - Intelligent Divar Ads Crawler |
|
||||
|
|
||||
This checklist tracks the implementation progress of the Intelligent Divar Ads Crawler with AI flagging and Telegram alerts. |
|
||||
|
|
||||
## 1. Project Setup & Infrastructure |
|
||||
- [x] Create Python virtual environment and set up `requirements.txt` |
|
||||
- [ ] Configure Docker environment (`docker-compose.yml` & `Dockerfiles`) |
|
||||
- [x] Setup environment variables template (`.env.example`) |
|
||||
|
|
||||
## 2. Backend Base & Models |
|
||||
- [x] Implement core abstract base models (`BaseModel`, `TimeStampedModel` in `core/models.py`) |
|
||||
- [x] Implement Crawler app models (`CrawlTask` and `CrawlRun` in `crawler/models.py`) |
|
||||
- [x] Implement Ads app models (`Ad`, `AdEvaluation`, and `NotificationLog` in `ads/models.py`) |
|
||||
- [x] Generate database migrations and apply them |
|
||||
|
|
||||
## 3. API Views, Serializers, and Routing (DRF) |
|
||||
- [x] Create API health check endpoint (`/api/health/`) |
|
||||
- [x] Create `CrawlTask` and `CrawlRun` serializers and views |
|
||||
- [x] Implement manual trigger action (`/api/crawlers/<id>/trigger/`) and runs history (`/api/crawlers/<id>/runs/`) |
|
||||
- [x] Create `Ad`, `AdEvaluation`, and `NotificationLog` serializers and views |
|
||||
- [x] Implement ads filtering by `crawl_task` and `is_flagged` (`/api/ads/`) |
|
||||
- [x] Write backend unit tests for all implemented API endpoints and ensure they pass |
|
||||
|
|
||||
## 4. Background Tasks & Scheduler (Celery) |
|
||||
- [ ] Configure Celery app and connect to Django settings (`core/celery.py`) |
|
||||
- [ ] Setup Celery dynamic database scheduler (`django-celery-beat`) |
|
||||
- [ ] Implement crawler pipeline task (`run_crawl_pipeline` in `crawler/tasks.py`) |
|
||||
- [ ] Add scraping/extraction logic for Divar public listings |
|
||||
|
|
||||
## 5. AI Flagging & Telegram Notification |
|
||||
- [ ] Implement AI analysis with LLM Structured Outputs in `ads/tasks.py` |
|
||||
- [ ] Implement Telegram Bot notification sender in `ads/tasks.py` |
|
||||
- [ ] Connect full pipeline (Scrape -> AI Flag -> Telegram Alert) |
|
||||
|
|
||||
## 6. Frontend Dashboard (React + Vite) |
|
||||
- [x] Initialize React project in `frontend/` |
|
||||
- [x] Create layout and custom CSS styling |
|
||||
- [x] Build Crawler Management page (list, create, edit, trigger, log view) |
|
||||
- [x] Build Ads Feed page (display filtered ads with AI evaluation details) |
|
||||
- [x] Connect React frontend to Django REST APIs |
|
||||
|
|
||||
## 7. Verification & Production Readiness |
|
||||
- [ ] Run full system manual QA (Edge cases, errors, network failure) |
|
||||
- [ ] Optimize logging, performance, and rate limiting |
|
||||
@ -1,128 +0,0 @@ |
|||||
# Implementation Plan - Intelligent Divar Ads Crawler |
|
||||
|
|
||||
This implementation plan outlines the phase-by-phase development of the **Intelligent Divar Ads Crawler** with AI Flagging and Telegram Notification. It is strictly based on the reference specifications: [product-scenario.md](file:///c:/projects/divar-crawler/product-scenario.md) and [project-architecture.md](file:///c:/projects/divar-crawler/project-architecture.md). |
|
||||
|
|
||||
## User Review Required |
|
||||
|
|
||||
> [!IMPORTANT] |
|
||||
> The crawler will parse public search/category pages from Divar. In this MVP phase, we assume standard HTML/API structures of Divar. If Divar implements aggressive rate limiting or Cloudflare checks, we may need to introduce proxy lists, user-agent rotation, or captcha solvers in a later phase. |
|
||||
|
|
||||
> [!NOTE] |
|
||||
> For the LLM integration, we plan to default to `gpt-4o-mini` (or an equivalent cost-effective model like `gemini-1.5-flash` or `claude-3-haiku` depending on the `.env` configuration). We will use Structured Outputs (JSON Schema mode) to guarantee schema compliance. |
|
||||
|
|
||||
## Open Questions |
|
||||
|
|
||||
> [!NOTE] |
|
||||
> None at the moment. The technical specifications and requirements are fully defined in the reference documents. If any specific preference arises during implementation (e.g., custom bot formats or specific UI themes), it will be addressed. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
## Proposed Changes |
|
||||
|
|
||||
### Docker & Infrastructure Configuration |
|
||||
|
|
||||
We will establish the docker containerization structure to orchestrate all services: PostgreSQL, Redis, Django Backend, Celery Worker, Celery Beat, and React Frontend. |
|
||||
|
|
||||
#### [NEW] [docker-compose.yml](file:///c:/projects/divar-crawler/docker-compose.yml) |
|
||||
- Defines the multi-container setup containing services: `postgres`, `redis`, `backend`, `frontend`, `celery_worker`, and `celery_beat`. |
|
||||
- Connects them via custom networks, environment variables, healthchecks, and volumes. |
|
||||
|
|
||||
#### [NEW] [.env.example](file:///c:/projects/divar-crawler/.env.example) |
|
||||
- Exposes templates for all necessary environment variables: `DJANGO_SECRET_KEY`, `POSTGRES_*`, `REDIS_URL`, `LLM_API_*`, `TELEGRAM_BOT_TOKEN`, and `ALLOWED_HOSTS`. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### Backend Service |
|
||||
|
|
||||
The backend will be a Django application using Django REST Framework (DRF), Celery for background processing, and Django-Celery-Beat for dynamic scheduler tasks. |
|
||||
|
|
||||
#### [NEW] [requirements.txt](file:///c:/projects/divar-crawler/backend/requirements.txt) |
|
||||
- Defines dependencies: `django`, `djangorestframework`, `django-cors-headers`, `celery`, `redis`, `psycopg2-binary`, `django-celery-beat`, `requests`, `openai`, `pydantic`. |
|
||||
|
|
||||
#### [NEW] [Dockerfile](file:///c:/projects/divar-crawler/backend/Dockerfile) |
|
||||
- Configures Python environment, installs requirements, and runs migration/development server. |
|
||||
|
|
||||
#### [NEW] [core/settings.py](file:///c:/projects/divar-crawler/backend/core/settings.py) |
|
||||
- Configures Django applications, PostgreSQL connection, Redis caching/broker settings, Celery setup, and DRF authentication. |
|
||||
|
|
||||
#### [NEW] [core/celery.py](file:///c:/projects/divar-crawler/backend/core/celery.py) |
|
||||
- Initializes Celery and connects it to Django settings. |
|
||||
|
|
||||
#### [NEW] [core/urls.py](file:///c:/projects/divar-crawler/backend/core/urls.py) |
|
||||
- Root URL dispatcher that redirects API traffic to appropriate modules (`/api/v1/crawlers/` and `/api/v1/ads/`). |
|
||||
|
|
||||
#### [NEW] [crawlers/models.py](file:///c:/projects/divar-crawler/backend/crawlers/models.py) |
|
||||
- Implements `CrawlTask` and `CrawlRun` models with validation, constraints, and indexes. |
|
||||
|
|
||||
#### [NEW] [crawlers/tasks.py](file:///c:/projects/divar-crawler/backend/crawlers/tasks.py) |
|
||||
- Implements `run_crawl_pipeline` task: fetches HTML/JSON from Divar, extracts ads, passes new ads for evaluation, handles exceptions, and updates `CrawlRun`. |
|
||||
|
|
||||
#### [NEW] [crawlers/serializers.py](file:///c:/projects/divar-crawler/backend/crawlers/serializers.py) |
|
||||
- Implements serializers for `CrawlTask` and `CrawlRun` models. |
|
||||
|
|
||||
#### [NEW] [crawlers/views.py](file:///c:/projects/divar-crawler/backend/crawlers/views.py) |
|
||||
- Implements API endpoints for Crawl CRUD, dynamic trigger (`/trigger/`), and execution logs. |
|
||||
|
|
||||
#### [NEW] [crawlers/urls.py](file:///c:/projects/divar-crawler/backend/crawlers/urls.py) |
|
||||
- Registers URL patterns for crawler endpoints. |
|
||||
|
|
||||
#### [NEW] [ads/models.py](file:///c:/projects/divar-crawler/backend/ads/models.py) |
|
||||
- Implements `Ad`, `AdEvaluation`, and `NotificationLog` models with unique constraints and indexes. |
|
||||
|
|
||||
#### [NEW] [ads/tasks.py](file:///c:/projects/divar-crawler/backend/ads/tasks.py) |
|
||||
- Implements `evaluate_ad_with_ai` task (calling LLM with JSON Schema) and `send_telegram_notification` task. |
|
||||
|
|
||||
#### [NEW] [ads/serializers.py](file:///c:/projects/divar-crawler/backend/ads/serializers.py) |
|
||||
- Implements serializers for `Ad`, `AdEvaluation`, and `NotificationLog` models. |
|
||||
|
|
||||
#### [NEW] [ads/views.py](file:///c:/projects/divar-crawler/backend/ads/views.py) |
|
||||
- Implements API endpoints for viewing and filtering ads (`/api/v1/ads/`). |
|
||||
|
|
||||
#### [NEW] [ads/urls.py](file:///c:/projects/divar-crawler/backend/ads/urls.py) |
|
||||
- Registers URL patterns for ads endpoints. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### Frontend Service |
|
||||
|
|
||||
The dashboard will be built using React with Vite. It interacts with the backend APIs to manage crawlers and view ads. |
|
||||
|
|
||||
#### [NEW] [package.json](file:///c:/projects/divar-crawler/frontend/package.json) |
|
||||
- React, React-DOM, TailwindCSS/Vanilla CSS setup, Axios, Lucide React (for icons), and React Router DOM. |
|
||||
|
|
||||
#### [NEW] [Dockerfile](file:///c:/projects/divar-crawler/frontend/Dockerfile) |
|
||||
- Multi-stage build for development/production. |
|
||||
|
|
||||
#### [NEW] [vite.config.js](file:///c:/projects/divar-crawler/frontend/vite.config.js) |
|
||||
- Proxy setting for `/api` to avoid CORS issues in local development. |
|
||||
|
|
||||
#### [NEW] [index.html](file:///c:/projects/divar-crawler/frontend/index.html) |
|
||||
- Main HTML landing page containing container root element. |
|
||||
|
|
||||
#### [NEW] [src/index.css](file:///c:/projects/divar-crawler/frontend/src/index.css) |
|
||||
- Custom premium CSS styles and theme settings. |
|
||||
|
|
||||
#### [NEW] [src/App.jsx](file:///c:/projects/divar-crawler/frontend/src/App.jsx) |
|
||||
- Setup routing and page layouts (Crawler Management Page, Ads Feed, Execution Log). |
|
||||
|
|
||||
#### [NEW] [src/main.jsx](file:///c:/projects/divar-crawler/frontend/src/main.jsx) |
|
||||
- Entry point of the React application. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
## Verification Plan |
|
||||
|
|
||||
### Automated Verification |
|
||||
After building the docker environment, we will verify the services are active by running: |
|
||||
- `docker compose ps` - check that all 6 services are running. |
|
||||
- Run database migrations: `docker compose exec backend python manage.py migrate` |
|
||||
- Create superuser: `docker compose exec backend python manage.py createsuperuser` |
|
||||
- Check API health endpoint: `curl http://localhost:8000/api/v1/health/` |
|
||||
|
|
||||
### Manual Verification |
|
||||
1. **Crawl Task CRUD:** Log into the admin/dashboard, create a Crawl task with a specific search link (e.g. Tehran buy-apartment query), interval = 5 minutes, specific LLM prompt, and a valid Telegram Channel. |
|
||||
2. **Dynamic Trigger:** Click "Run Now" in the dashboard and monitor the logs (`docker compose logs -f celery_worker`). |
|
||||
3. **Check PostgreSQL:** Verify that crawled ads are stored in the database. |
|
||||
4. **AI Evaluation Check:** Verify that ads matching/not matching the prompt are correctly flagged `is_flagged = true` or `false` in `AdEvaluation` table. |
|
||||
5. **Telegram Notification:** Verify that only flagged ads are sent to the Telegram channel. |
|
||||
6. **Timeframe Checks:** Update the crawl task window to test that executions outside the hour range are skipped. |
|
||||
@ -1,162 +0,0 @@ |
|||||
# سند سناریوی محصول (Product Scenario) |
|
||||
## سامانه کرال هوشمند آگهیهای دیوار با پرچمگذاری AI و اطلاعرسانی تلگرامی |
|
||||
|
|
||||
این سند به عنوان مرجع توصیف محصول، فرآیندها، نیازمندیها و قوانین تجاری سامانه کرال هوشمند دیوار تدوین شده است و مبنای پیادهسازی و راستیآزمایی محصول خواهد بود. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱. خلاصهٔ محصول (Product Summary) |
|
||||
سامانه کرال هوشمند دیوار، ابزاری است که به کاربران اجازه میدهد آگهیهای ثبت شده در سایت دیوار را بر اساس دستهبندیها یا فیلترهای جستجوی خاص بهصورت خودکار و دورهای پایش (Crawl) کنند. پس از جمعآوری آگهیها، سیستم محتوای هر آگهی را با استفاده از مدلهای زبانی بزرگ (LLM) تحلیل کرده و بر اساس معیارهای تعیین شده در «پرامپت تشخیصی»، آگهیهای هدف را شناسایی و پرچمگذاری (Flag) میکند. در نهایت، آگهیهای پرچمگذاری شده به کانالهای تلگرامی متناظر با هر کرال ارسال میشوند تا کاربر در لحظه از فرصتها مطلع گردد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲. هدف و ارزش اصلی (Core Goal and Value) |
|
||||
کاهش زمان و هزینهٔ جستجوی دستی آگهیهای دیوار و شناسایی هوشمند فرصتهای معاملاتی/کاری خاص. |
|
||||
ارزش کلیدی سامانه: **فیلتراسیون پیشرفته و معنایی (Semantic)** که با فیلترهای معمولی دیوار (مانند قیمت و متراژ) غیرقابل پیادهسازی است. به عنوان مثال: "پیدا کردن آپارتمانهایی در منطقه غرب تهران که مالک آنها به دلیل مهاجرت مایل به معاوضه با خودرو است." |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۳. کاربران و نقشها (Users and Roles) |
|
||||
در این نسخه (MVP)، سیستم تککاربره یا دارای یک نقش پیشفرض (مدیر سیستم / کاربر نهایی) است: |
|
||||
* **کاربر/مدیر (User/Admin):** دسترسی کامل به داشبورد وب جهت تعریف کرالها، مشاهده نتایج تحلیل AI، تنظیم پرامپتها، پایش وضعیت کرالها و تنظیمات اتصال تلگرام. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۴. سناریوی اصلی کاربر از ابتدا تا انتها (End-to-End Main User Scenario) |
|
||||
1. **ورود و راهاندازی اولیه:** کاربر وارد داشبورد وب سامانه میشود. |
|
||||
2. **تعریف کرال جدید:** کاربر دکمه «ایجاد کرال جدید» را میزند و اطلاعات زیر را وارد میکند: |
|
||||
* عنوان کرال: "خرید آپارتمان فوری زیر قیمت" |
|
||||
* لینک جستجوی دیوار: `https://divar.ir/s/tehran/buy-apartment?query=...` |
|
||||
* پرامپت تشخیصی: "بررسی کن آیا فروشنده پول لازم است یا به دلیل مهاجرت عجله دارد؟" |
|
||||
* فاصلهٔ زمانی اجرا: "هر ۱۵ دقیقه" |
|
||||
* پنجرهٔ زمانی مجاز: "از ساعت ۰۸:۰۰ الی ۲۳:۰۰" |
|
||||
* کانال تلگرام: `@my_divar_alerts` |
|
||||
* وضعیت: "فعال" |
|
||||
3. **زمانبندی و کرال:** موتور زمانبندی (Celery Beat) در فواصل تعیینشده کرال را اجرا میکند. آگهیهای جدیدِ لینک دیوار جمعآوری شده و اطلاعات پایه (عنوان، توضیحات، قیمت، لینک، عکسها) در دیتابیس ذخیره میشوند. |
|
||||
4. **ارزیابی هوشمند (AI Evaluation):** برای هر آگهی جدید که قبلاً ارزیابی نشده است، یک تسک پسزمینه ایجاد میشود. متن آگهی به همراه پرامپت تشخیصی به LLM ارسال میشود. |
|
||||
5. **دریافت نتیجه ساختاریافته:** LLM مشخص میکند که آیا آگهی شرایط پرچمگذاری را دارد یا خیر (`is_flagged: true/false`) و دلایل آن را به همراه سطح اطمینان (`confidence`) بازمیگرداند. |
|
||||
6. **اطلاعرسانی تلگرامی:** در صورت مثبت بودن پرچم (`is_flagged: true`)، ربات تلگرام پیامی حاوی اطلاعات کلیدی آگهی، دلایل هوش مصنوعی و لینک آگهی را به کانال تعیینشده ارسال میکند. |
|
||||
7. **مشاهده داشبورد:** کاربر در پنل خود لیست تمام آگهیهای دریافت شده، وضعیت پرچم آنها و نتایج تحلیل AI را مشاهده و فیلتر میکند. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۵. User Stories مهم (Key User Stories) |
|
||||
* **داشبورد مدیریت کرال:** به عنوان کاربر، من میخواهم بتوانم کرالهای جدید بسازم، ویرایش کنم، غیرفعال سازم یا حذف کنم تا بتوانم پایش جستجوهای مختلف را مدیریت کنم. |
|
||||
* **پایش هوشمند:** به عنوان کاربر، من میخواهم سیستم بهطور خودکار در بازههای زمانی معین کار کند تا نیازی به اجرای دستی و آنلاین بودن همیشگی من نباشد. |
|
||||
* **تحلیل AI:** به عنوان کاربر، من میخواهم محتوای متنی آگهیها با دقت تحلیل شده و تنها مواردی که با پرامپت من همخوانی دارند فیلتر شوند تا از هدررفت زمان جلوگیری شود. |
|
||||
* **اطلاعرسانی سریع:** به عنوان کاربر، من میخواهم آگهیهای پرچمشده بلافاصله در کانال تلگرام شخصیام ارسال شوند تا بتوانم سریعاً با آگهیدهنده تماس بگیرم. |
|
||||
* **مشاهده آرشیو:** به عنوان کاربر، من میخواهم آرشیو تمام آگهیهای کرالشده (پرچمشده یا عادی) را در پنل ببینم تا مطمئن شوم هیچ دادهای از دست نرفته است. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۶. Acceptance Criteria برای جریانهای اصلی (Acceptance Criteria) |
|
||||
#### ایجاد و تنظیم کرال |
|
||||
* کاربر نتواند کرال بدون عنوان، بدون پرامپت یا بدون لینک دیوار معتبر ذخیره کند. |
|
||||
* فرمت بازه زمانی اجرا باید محدود به گزینههای استاندارد (مثلاً ۵، ۱۵، ۳۰ یا ۶۰ دقیقه) باشد. |
|
||||
* پنجره زمانی مجاز اجرا باید با ساعت شروع و پایان مشخص شود (مثلاً ۸ تا ۲۲). |
|
||||
|
|
||||
#### جمعآوری و ذخیرهسازی آگهیها |
|
||||
* تمام آگهیهای استخراج شده از لینک دیوار باید با شناسه منحصربهفرد دیوار (Divar Token) ذخیره شوند تا از ذخیره تکراری جلوگیری شود. |
|
||||
* حتی اگر فرآیند هوش مصنوعی یا ارسال تلگرام با خطا مواجه شود، اصل آگهی باید در دیتابیس ثبت شده باقی بماند. |
|
||||
|
|
||||
#### پردازش هوش مصنوعی (AI Process) |
|
||||
* برای هر آگهی، فرآیند ارزیابی هوش مصنوعی دقیقاً **یکبار** انجام شود (جلوگیری از ارزیابی تکراری و اتلاف هزینه). |
|
||||
* خروجی هوش مصنوعی باید فرمت JSON ساختاریافته داشته باشد. در صورت برگشت پاسخ نامعتبر از مدل، سیستم نباید کرش کند، بلکه باید وضعیت خطا ثبت شده و پردازش آگهیهای بعدی ادامه یابد. |
|
||||
|
|
||||
#### اطلاعرسانی تلگرام |
|
||||
* ارسال پیام تلگرام فقط برای آگهیهایی رخ دهد که خروجی AI آنها `is_flagged: true` باشد. |
|
||||
* اگر آدرس کانال تلگرام برای یک کرال خالی بود، تسک ارسال پیام بدون خطا نادیده گرفته شده و صرفاً در لاگها ثبت شود. |
|
||||
* شکست در ارسال پیام تلگرام (مانند مسدود بودن ربات یا خطای شبکه) نباید کل روند کرال را متوقف یا تراکنشهای دیتابیس را Rollback کند. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۷. نیازمندیهای عملکردی با شناسه (Functional Requirements) |
|
||||
|
|
||||
| شناسه (ID) | عنوان نیازمندی | توصیف تفصیلی | |
|
||||
| :--- | :--- | :--- | |
|
||||
| **FR-01** | ایجاد و ویرایش کرال | کاربر باید بتواند نمونههای کرال (Crawl Task) را ایجاد، ویرایش، حذف و فعال/غیرفعال کند. | |
|
||||
| **FR-02** | فیلدهای تنظیم کرال | فیلدهای کرال شامل: عنوان، لینک دیوار، پرامپت اختصاصی، اینتروال زمانی، پنجره زمانی، آدرس کانال تلگرام و وضعیت است. | |
|
||||
| **FR-03** | کرال پسزمینه دورهای | سیستم باید با Celery Beat در فواصل مشخص و در پنجره زمانی تعیینشده، صفحات دیوار را کرال کند. | |
|
||||
| **FR-04** | استخراج دادههای آگهی | برای هر آگهی باید فیلدهای: شناسه دیوار (توکن)، عنوان آگهی، متن توضیحات، قیمت، دستهبندی، تصاویر و لینک آگهی استخراج شوند. | |
|
||||
| **FR-05** | یکتاسازی آگهیها | جلوگیری از پردازش مجدد آگهیهای تکراری با استفاده از شناسه دیوار (توکن یکتا) در سطح کل سیستم. | |
|
||||
| **FR-06** | ذخیره همگانی آگهیها | ذخیرهسازی تمام آگهیهای جدیدِ یافتشده در دیتابیس، بدون توجه به نتیجه پرچمگذاری هوش مصنوعی. | |
|
||||
| **FR-07** | تحلیل معنایی با LLM | ارسال محتوای هر آگهی جدید به همراه پرامپت اختصاصی کرال به LLM API جهت دریافت پاسخ ساختاریافته JSON. | |
|
||||
| **FR-08** | قالببندی خروجی LLM | دریافت فیلدهای `is_flagged` (Boolean)، `reason` (String)، `confidence` (Float/Integer) و `extracted_fields` (JSON/Dictionary) از AI. | |
|
||||
| **FR-09** | ارسال پیام به تلگرام | ارسال اطلاعات آگهیهای پرچمگذاری شده به کانال تلگرام ثبت شده در کرال با قالب زیبا و خوانا. | |
|
||||
| **FR-10** | داشبورد وب - نمایش کرالها | پنل وب برای لیست کردن کرالها به همراه آخرین زمان اجرا و وضعیت آنها. | |
|
||||
| **FR-11** | داشبورد وب - نمایش آگهیها | نمایش لیست آگهیهای کرال شده با قابلیت فیلتر بر اساس کرال، وضعیت پرچم و کلیدواژهها. | |
|
||||
| **FR-12** | اجرای دستی کرال | امکان کلیک روی دکمه «اجرای فوری» برای هر کرال جهت تست بدون انتظار برای نوبت بعدی Celery Beat. | |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۸. نیازمندیهای غیرعملکردی (Non-functional Requirements) |
|
||||
* **قابلیت اطمینان (Reliability):** در صورت قطع ارتباط با دیوار، LLM یا تلگرام، کل سیستم نباید از کار بیفتد. سیستم باید مکانیزم Retry برای تسکهای شکستخورده داشته باشد. |
|
||||
* **مدیریت خطا (Error Handling):** خطاهای ناشی از مسدود شدن IP توسط دیوار یا تغییر ساختار HTML دیوار باید بهصورت لاگهای ساختاریافته ذخیره شوند تا مدیر متوجه خرابی کرالر شود. |
|
||||
* **لاگگیری (Logging):** ثبت تمام تراکنشها، دفعات اجرای کرالها، نتایج پردازش هوش مصنوعی و وضعیت ارسال پیام تلگرام در دیتابیس یا فایل لاگ با فرمت استاندارد. |
|
||||
* **مقیاسپذیری اولیه (Scalability):** معماری سیستم باید بهگونهای باشد که با افزایش تعداد کرالها، بتوان با افزایش تعداد پروسسهای Celery Worker ظرفیت پردازش را بالا برد. |
|
||||
* **امنیت (Security):** |
|
||||
* توکنهای حساس (مانند کلید API هوش مصنوعی و توکن ربات تلگرام) باید در متغیرهای محیطی سیستم (.env) نگهداری شوند و در کدهای برنامه هاردکد نشوند. |
|
||||
* احراز هویت داشبورد در سطح MVP ساده باشد (مثلاً یک نام کاربری و رمز عبور ادمین). |
|
||||
* **کنترل نرخ مصرف (Rate Limiting):** پیادهسازی تاخیرهای رندوم (Random Delay) در زمان کرال دیوار جهت جلوگیری از بلاک شدن IP سرور. |
|
||||
* **تکرار ناپذیری (Idempotency):** پردازش یک آگهی نباید تحت هیچ شرایطی دو بار انجام شود. دیتابیس باید تضمین کند که ثبت آگهی و تسک ارزیابی آن برای یک توکن دیوار منحصربهفرد، تکرار نخواهد شد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۹. قوانین دامنه و Business Rules |
|
||||
1. **پرامپت اختصاصی:** هر کرال فقط و فقط دارای یک پرامپت تشخیصی است که توسط کاربر تنظیم میشود. |
|
||||
2. **ذخیره حداکثری:** سیستم حق ندارد آگهیهای غیرمرتبط (Flagged = False) را دور بریزد. تمام آگهیهای اسکنشده باید ذخیره شوند تا در آینده کاربر بتواند در صورت تغییر پرامپت، آگهیهای قبلی را مجدداً تحلیل کند. |
|
||||
3. **تارگت مجزای تلگرام:** هر کرال دارای یک فیلد آدرس کانال تلگرام مجزاست. پیامهای هر کرال فقط به کانال متناظر خودش ارسال میشوند. |
|
||||
4. **سکوت تلگرام:** اگر فیلد تلگرام یک کرال خالی باشد یا با کاراکتر خاصی غیرفعال شده باشد، هیچ پیام تلگرامی ارسال نمیشود و این سناریو به عنوان خطای سیستم محسوب نمیگردد. |
|
||||
5. **انحصار زمانی:** اجرای تسکهای کرال برای هر کرال باید خارج از پنجره زمانی مجاز متوقف شود (مثلاً اگر پنجره ۸ تا ۲۲ است، در ساعت ۲۳ تسکها اجرا نشوند و تا فردا صبح منتظر بمانند). |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۰. جریانهای فرعی و Edge Cases |
|
||||
* **آگهی تکراری:** اگر دیوار در کرالهای متوالی یک آگهی قدیمی را در صفحه اول جستجو نشان دهد، سیستم پس از چک کردن توکن یکتای آگهی در دیتابیس، از ذخیره مجدد و تحلیل دوباره آن خودداری میکند. |
|
||||
* **خطای API هوش مصنوعی:** در صورت قطع ارتباط با LLM یا اتمام شارژ پنل، تسک پردازش آگهی وارد وضعیت `FAILED` شده و با سیاست Exponential Backoff تا حداکثر ۳ بار مجدداً تلاش میکند. اگر همچنان خطا باقی ماند، آگهی در دیتابیس بدون پرچم ذخیره شده و خطای مربوطه لاگ میشود. |
|
||||
* **خطای تلگرام:** اگر ارسال به تلگرام به دلیل فیلترینگ یا نامعتبر بودن Channel ID شکست بخورد، این خطا در جدول لاگ اعلانات ثبت میشود ولی وضعیت کلی آگهی و کرال خراب نمیشود. |
|
||||
* **کرال غیرفعال:** اگر یک کرال توسط کاربر غیرفعال شود (`is_active: false`)، Celery Beat باید بلافاصله از زمانبندی کردن آن خودداری کند و تسکهای در صف ماندهٔ آن اجرا نشوند. |
|
||||
* **خروجی نامعتبر هوش مصنوعی:** اگر هوش مصنوعی به جای ساختار JSON مورد نظر، یک متن عمومی یا فرمت خراب برگرداند، سیستم با یک لایه Parser خطای ساختاری را گرفته، فیلد `is_flagged` را پیشفرض `false` در نظر میگیرد و متن خام خروجی را جهت بررسی مدیر لاگ میکند. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۱. موارد خارج از Scope فعلی (Out of Scope) |
|
||||
* **دور زدن پیشرفته Cloudflare/کپچای دیوار:** در فاز MVP، سیستم از کرال سادهٔ صفحات عمومی دیوار (بدون نیاز به لاگین) استفاده میکند. حل کپچاهای پیچیده تصویر یا دور زدن سپرهای امنیتی پیشرفته Cloudflare در این فاز پیادهسازی نمیشود. |
|
||||
* **پرداخت درونبرنامهای و اشتراک:** سیستم به صورت تککاربره/ادمین مدیریت میشود و پنل فروش اشتراک ندارد. |
|
||||
* **اپلیکیشن موبایل:** دسترسی فقط از طریق مرورگر وب (داشبورد React) خواهد بود. |
|
||||
* **چت تلگرام دوطرفه:** ربات تلگرام یکطرفه است و صرفاً پیام ارسال میکند و قابلیت دریافت کامند از کاربر در چت تلگرام در این فاز وجود ندارد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۲. فرضیات و ابهامات |
|
||||
* **ساختار صفحات دیوار:** فرض میشود لینکهای جستجوی دیوار اطلاعات اولیه آگهیها (توکن، عنوان، قیمت، توضیحات کوتاه) را در خروجی HTML یا API عمومی خود دارند. در صورت نیاز به جزئیات بیشتر (توضیحات کامل آگهی)، کرالر باید به صفحه اختصاصی هر آگهی (`/v/token`) درخواست بزند. |
|
||||
* **محدودیت نرخ (Rate Limit) دیوار:** فرض میشود که تعداد کرالها در حد منطقی (کمتر از ۱۰ کرال همزمان) است و با استفاده از پروکسیهای ساده یا تاخیر تصادفی، مسدودسازی IP رخ نمیدهد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۳. ریسکهای محصولی/اجرایی |
|
||||
* **ریسک تغییرات ساختاری دیوار:** سایت دیوار ممکن است در هر لحظه ساختار کلاسهای HTML یا آدرسهای API خود را تغییر دهد که باعث خرابی موقت کرالر میشود. |
|
||||
* *کاهش ریسک:* جداسازی منطق Parser دیوار در کدهای بکاند به صورتی که با کمترین تغییر کد قابل اصلاح باشد. |
|
||||
* **ریسک هزینهٔ LLM API:** ارسال همهٔ آگهیها به LLM میتواند هزینهبر باشد. |
|
||||
* *کاهش ریسک:* استفاده از مدلهای ارزانتر (مانند GPT-4o-mini یا Claude 3 Haiku) و فیلتر اولیه آگهیها بر اساس کلمات کلیدی ساده قبل از ارسال به LLM. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۴. معیارهای پذیرش MVP (MVP Acceptance Criteria) |
|
||||
* امکان ایجاد حداقل ۵ کرال فعال همزمان با بازههای زمانی متفاوت. |
|
||||
* ذخیره موفقیتآمیز آگهیهای کرال شده در PostgreSQL. |
|
||||
* تحلیل موفق آگهیها توسط LLM و ذخیره نتایج به صورت کاملاً ساختاریافته. |
|
||||
* دریافت نوتیفیکیشن تلگرام حاوی لینک آگهی و علت پرچمگذاری در کمتر از ۳ دقیقه پس از انتشار آگهی در دیوار (در زمان اجرای کرال). |
|
||||
* عدم کرش یا خرابی کل سیستم در صورت مسدود شدن تلگرام یا قطع اینترنت. |
|
||||
* اجرا شدن کل سیستم با دستور `docker compose up --build` بدون نیاز به تنظیمات دستی روی سیستم میزبان. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۵. Manual QA Checklist برای مسیر اصلی محصول |
|
||||
1. [ ] ایجاد یک کرال جدید با پرامپت مشخص (مثلاً: "فقط آگهیهای رهن کامل بدون اجاره") و تنظیم کانال تلگرام معتبر. |
|
||||
2. [ ] فشردن دکمه «اجرای فوری» در داشبورد و تایید آغاز فرآیند کرال در تسکهای Celery. |
|
||||
3. [ ] بررسی دیتابیس یا لیست آگهیها در داشبورد و اطمینان از ثبت شدن آگهیهای رهن کامل و آگهیهای ترکیبی (رهن و اجاره). |
|
||||
4. [ ] بررسی خروجی هوش مصنوعی برای هر آگهی: آگهیهای رهن کامل باید `is_flagged: true` و بقیه `is_flagged: false` شده باشند. |
|
||||
5. [ ] بررسی کانال تلگرام: پیامها فقط برای آگهیهای رهن کامل ارسال شده باشند. |
|
||||
6. [ ] غیرفعال کردن کرال از پنل و اطمینان از اینکه در بازه زمانی بعدی دیگر هیچ درخواستی به دیوار ارسال نمیشود. |
|
||||
7. [ ] قطع کردن موقت اتصال اینترنت (یا مسدود کردن API تلگرام) و ارسال یک آگهی پرچمگذاری شده جدید؛ سیستم نباید کرش کند و وضعیت خطای تلگرام باید در بخش Execution Log ثبت شود. |
|
||||
@ -1,557 +0,0 @@ |
|||||
# سند معماری سیستم (Project Architecture) |
|
||||
## سامانه کرال هوشمند آگهیهای دیوار با پرچمگذاری AI و اطلاعرسانی تلگرامی |
|
||||
|
|
||||
این سند به عنوان سند فنی مرجع، جزئیات کامل معماری، ساختار کانتینرها، مدل داده، ساختار API و فرآیندهای عملیاتی سامانه کرال هوشمند را توصیف میکند. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱. خلاصهٔ معماری (Architecture Summary) |
|
||||
معماری سیستم بر اساس الگوی **میکروسرویسهای هماهنگ با کانتینر (Containerized Microservices)** طراحی شده است. هسته اصلی پردازشی سیستم شامل یک برنامه Django (بکاند) است که REST APIهای مورد نیاز پنل وب (React) را سرویسدهی میکند. تسکهای سنگین و دورهای مانند کرال کردن دیوار، ارسال درخواست به LLM و ارسال پیام به تلگرام از طریق Celery Worker و Celery Beat در پسزمینه و به صورت توزیعشده اجرا میشوند تا کارایی و پایداری لایه وب حفظ شود. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲. استک فنی نهایی و دلیل انتخابها (Final Tech Stack & Rationale) |
|
||||
* **Backend Framework: Django + Django REST Framework (DRF)** |
|
||||
* *دلیل انتخاب:* وجود ORM قدرتمند جهت مدیریت PostgreSQL، سیستم احراز هویت داخلی آماده، سرعت بالا در توسعه API و پشتیبانی عالی از کتابخانههای مختلف مانند Celery. |
|
||||
* **Database: PostgreSQL** |
|
||||
* *دلیل انتخاب:* یک دیتابیس رابطهای امن و بسیار پایدار با پشتیبانی عالی از فیلدهای JSONB (برای ذخیره خروجی دلخواه LLM) و سرعت بالا در جستجوی ایندکسها. |
|
||||
* **Background Task Queue: Celery + Redis** |
|
||||
* *دلیل انتخاب:* Celery استاندارد طلایی پایتون برای مدیریت تسکهای پسزمینه و وظایف دورهای (Beat) است. Redis نیز به عنوان یک پیامرسان (Broker) فوقالعاده سریع با تاخیر کم عمل میکند. |
|
||||
* **Frontend Framework: React (با Vite)** |
|
||||
* *دلیل انتخاب:* کارایی بسیار بالا، ساختار کامپوننتمحور، اکوسیستم قوی و تجربه کاربری نرم (Single Page Application) در کار با داشبورد تعاملی. |
|
||||
* **AI Engine: LLM API (مانند OpenAI API یا APIهای مشابه داخلی/خارجی)** |
|
||||
* *دلیل انتخاب:* توانایی بالا در استخراج اطلاعات معنایی از متن بدون نیاز به هاست کردن مدلهای سنگین روی سرورهای محلی. |
|
||||
* **Messaging: Telegram Bot API** |
|
||||
* *دلیل انتخاب:* سادهترین، سریعترین و در دسترسترین پلتفرم برای ارسال اعلانات (Alerts) لحظهای به کانالهای اختصاصی. |
|
||||
* **Containerization: Docker + Docker Compose** |
|
||||
* *دلیل انتخاب:* تضمین یکسان بودن محیط توسعه، تست و پروداکشن و امکان راهاندازی کل استک با یک دستور منفرد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۳. دیاگرام معماری سطح بالا (High-Level Architecture Diagram) |
|
||||
|
|
||||
```mermaid |
|
||||
graph TD |
|
||||
%% Users and Frontend |
|
||||
User((کاربر)) -->|مشاهده و مدیریت| ReactDashboard[داشبورد React] |
|
||||
|
|
||||
%% API Requests |
|
||||
ReactDashboard -->|API Requests - CORS| DjangoAPI[Django REST API] |
|
||||
|
|
||||
%% Database and Broker Connections |
|
||||
DjangoAPI -->|ORM / SQL| PostgreSQL[(دیتابیس PostgreSQL)] |
|
||||
DjangoAPI -->|Trigger Tasks| RedisBroker[بروکر Redis] |
|
||||
|
|
||||
%% Celery Operations |
|
||||
CeleryBeat[Celery Beat] -->|زمانبندی تسکها| RedisBroker |
|
||||
RedisBroker -->|دلیوری تسکها| CeleryWorker[Celery Worker] |
|
||||
|
|
||||
%% Worker External Communications |
|
||||
CeleryWorker -->|ذخیره آگهی و لاگ| PostgreSQL |
|
||||
CeleryWorker -->|۱. کرال صفحات| Divar[سایت دیوار] |
|
||||
CeleryWorker -->|۲. ارسال متن آگهی| LLM[LLM API] |
|
||||
CeleryWorker -->|۳. ارسال اعلانات| TelegramBot[Telegram Bot API] |
|
||||
|
|
||||
%% External Notifications |
|
||||
TelegramBot -->|پیام تلگرام| TelegramChannel[کانال تلگرام کرال] |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۴. اجزای اصلی سیستم و مسئولیت هرکدام |
|
||||
1. **داشبورد وب (React):** نمایش لیست کرالها، فرم ایجاد/ویرایش کرال، نمایش لیست آگهیهای ثبت شده (با قابلیت فیلتر آگهیهای پرچمشده)، و لاگهای اجرا. |
|
||||
2. **سرویس وب بکاند (Django / DRF):** مدیریت دسترسیها، مدیریت فیلدهای دیتابیس، ارائه APIها و اندپوینتهای مدیریت کرال، و فرمان اجرای دستی کرالها. |
|
||||
3. **زمانبند (Celery Beat):** اجرای تسک دورهای بررسی زمانبندی کرالها و اضافه کردن تسکهای کرال جدید به صف Redis. |
|
||||
4. **پردازشگر پسزمینه (Celery Worker):** دریافت وظایف از صف و اجرای فرآیندهای کرال، فراخوانی LLM، تحلیل داده و ارسال پیام تلگرام. |
|
||||
5. **دیتابیس (PostgreSQL):** ذخیره دائم دادههای مربوط به کرالها، آگهیها، وضعیت اجرای تسکها و لاگ ارسال اعلانات. |
|
||||
6. **کارگزار پیام (Redis):** کانال ارتباطی امن و سریع بین جنگو و ورکرها و همچنین به عنوان کش ساده سیستم. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۵. معماری Backend |
|
||||
بکاند پروژه با ساختار برنامههای استاندارد جنگو پیادهسازی میشود. |
|
||||
* **جنگو (Django):** تنظیم پروژه در پوشه `backend/` انجام میشود. دو اپلیکیشن اصلی با نامهای `crawlers` (مدیریت کرالها و تاریخچه اجرا) و `ads` (مدیریت آگهیها و نتایج هوش مصنوعی و اعلانات) ساخته خواهند شد. |
|
||||
* **DRF:** کنترل دسترسیها از طریق `IsAuthenticated` (یا دسترسی عمومی ادمین پیشفرض در MVP) و تبدیل مدلها به خروجیهای استاندارد JSON با استفاده از Serializerها انجام میپذیرد. |
|
||||
* **Celery:** تنظیمات سلری در `backend/core/celery.py` قرار گرفته و به کلیدهای پیکربندی در فایل `.env` متصل است. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۶. معماری Frontend |
|
||||
فرانتاند یک پروژه React مستقل مبتنی بر Vite است. |
|
||||
* **React:** در پوشه `frontend/` قرار دارد. ساختار برنامه تکصفحهای (SPA) بوده و از کتابخانه React Router برای مسیریابی بین صفحات استفاده میشود. |
|
||||
* **ارتباط با API:** تمام درخواستها از طریق Axios یا Fetch API انجام میشوند. آدرس پایه بکاند (API Base URL) از طریق متغیر محیطی در زمان بیلد به پروژه تزریق میشود. |
|
||||
* **صفحات اصلی:** صفحه مدیریت کرالها (لیست، ایجاد، ویرایش)، صفحه مشاهده آگهیهای کرال شده با قابلیت فیلتر چندگانه، و صفحه لاگهای اجرای کرالر. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۷. معماری کانتینری (Container Architecture) |
|
||||
کانتینرهای زیر در فایل [docker-compose.yml](file:///c:/projects/divar-crawler/docker-compose.yml) تعریف میشوند: |
|
||||
|
|
||||
#### ۱. سرویس `postgres` |
|
||||
* **Build Context:** ندارد (استفاده از ایمیج رسمی `postgres:15-alpine`) |
|
||||
* **Ports:** `5432:5432` |
|
||||
* **Volumes:** `postgres_data:/var/lib/postgresql/data` |
|
||||
* **Environment Variables:** |
|
||||
* `POSTGRES_DB`: نام دیتابیس |
|
||||
* `POSTGRES_USER`: نام کاربری دیتابیس |
|
||||
* `POSTGRES_PASSWORD`: کلمه عبور دیتابیس |
|
||||
* **Healthcheck:** اجرای تست `pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}` جهت اطمینان از بالا بودن دیتابیس قبل از اجرای بکاند. |
|
||||
|
|
||||
#### ۲. سرویس `redis` |
|
||||
* **Build Context:** ندارد (استفاده از ایمیج رسمی `redis:7-alpine`) |
|
||||
* **Ports:** `6379:6379` |
|
||||
* **Command:** `redis-server --save 60 1 --loglevel warning` (فعال بودن مکانیزم ذخیره ساده برای پایداری داده در صفها) |
|
||||
* **Volumes:** `redis_data:/data` |
|
||||
|
|
||||
#### ۳. سرویس `backend` |
|
||||
* **Build Context:** `./backend` (استفاده از Dockerfile اختصاصی پایتون) |
|
||||
* **Command:** `python manage.py migrate && python manage.py runserver 0.0.0.0:8000` (در محیط توسعه) |
|
||||
* **Ports:** `8000:8000` |
|
||||
* **Environment Variables:** متغیرهای اتصال دیتابیس، ردیس، توکنهای API و تنظیمات جنگو (مانند `DEBUG` و `SECRET_KEY`). |
|
||||
* **Volumes:** `./backend:/app` (جهت لایو-لودینگ در زمان توسعه) |
|
||||
* **Depends_on:** |
|
||||
* `postgres` با شرط سلامت (service_healthy) |
|
||||
* `redis` |
|
||||
|
|
||||
#### ۴. سرویس `frontend` |
|
||||
* **Build Context:** `./frontend` (استفاده از Dockerfile اختصاصی Node.js) |
|
||||
* **Command:** `npm run dev -- --host 0.0.0.0` |
|
||||
* **Ports:** `5173:5173` |
|
||||
* **Environment Variables:** `VITE_API_URL` |
|
||||
* **Volumes:** `./frontend:/app` و محروم کردن `node_modules` |
|
||||
|
|
||||
#### ۵. سرویس `celery_worker` |
|
||||
* **Build Context:** `./backend` (مشابه با بکاند) |
|
||||
* **Command:** `celery -A core worker -l info --concurrency=2` |
|
||||
* **Environment Variables:** تمامی متغیرهای محیطی بکاند. |
|
||||
* **Volumes:** `./backend:/app` |
|
||||
* **Depends_on:** |
|
||||
* `postgres` |
|
||||
* `redis` |
|
||||
|
|
||||
#### ۶. سرویس `celery_beat` |
|
||||
* **Build Context:** `./backend` (مشابه با بکاند) |
|
||||
* **Command:** `celery -A core beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler` (استفاده از زمانبندی پویا در دیتابیس) |
|
||||
* **Environment Variables:** تمامی متغیرهای محیطی بکاند. |
|
||||
* **Volumes:** `./backend:/app` |
|
||||
* **Depends_on:** |
|
||||
* `postgres` |
|
||||
* `redis` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۸. توضیح دقیق backend service |
|
||||
* **API Endpoints:** طبق بخش ۱۶ پیادهسازی میشوند. |
|
||||
* **مسیریابی پنل وب (Bootstrap Routing):** بکاند جنگو در صورت درخواست مسیرهای غیر API (مثلاً صفحات معمولی وب) میتواند کدهای فرانتاند بیلده شده را ارائه دهد یا ریدایرکت کند، اما در ساختار کانتینری پیشنهادی، سرویس فرانتاند به عنوان یک کانتینر مجزا کار میکند و روتینگ SPA توسط خود React هندل میشود. |
|
||||
* **احراز هویت (Auth):** برای سادگی در فاز MVP، از احراز هویت مبتنی بر Token پیشفرض DRF یا JWT (توسط `djangorestframework-simplejwt`) استفاده میشود. توکن احراز هویت در Header درخواستها با فرمت `Authorization: Bearer <token>` ارسال میشود. |
|
||||
* **امنیت CORS/CSRF:** |
|
||||
* استفاده از کتابخانه `django-cors-headers` برای مدیریت CORS. در توسعه، دسترسی به دامنه فرانتاند (`http://localhost:5173`) مجاز اعلام میشود. |
|
||||
* برای اندپوینتهای API، مکانیسم CSRF بر اساس توکنهای هدر یا غیرفعالسازی موقت روی مسیرهای API مجهز به احراز هویت JWT خواهد بود. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۹. توضیح دقیق frontend service |
|
||||
* **نحوه build:** استفاده از Vite برای کامپایل کدهای React به فایلهای استاتیک HTML/JS/CSS بسیار بهینه (`npm run build`). |
|
||||
* **نحوه ارتباط با backend:** در کدهای فرانتاند، کلاینت Axios با آدرس پایه `VITE_API_URL` پیکربندی میشود. |
|
||||
* **ملاحظات توسعه (Proxy):** در فایل `vite.config.js` مسیرهای `/api/` به آدرس بکاند (`http://backend:8000/api/`) پروکسی میشوند تا از بروز مشکلات CORS در زمان توسعه لوکال جلوگیری شود. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۰. Data Model کامل (Full Data Model) |
|
||||
دیتابیس در محیط PostgreSQL طراحی شده است. از ORM جنگو برای ساخت و مدیریت مدلها استفاده میشود. |
|
||||
|
|
||||
#### مدل ۱: `CrawlTask` (جدول `crawl_tasks` در اپلیکیشن `crawlers`) |
|
||||
مدیریت رکوردهای پایش تنظیم شده توسط کاربر. |
|
||||
* `id`: `UUIDField` (کلید اصلی، یکتا) |
|
||||
* `title`: `CharField(max_length=255)` (عنوان کرال) |
|
||||
* `divar_url`: `URLField` (لینک فیلتر جستجوی دیوار) |
|
||||
* `detection_prompt`: `TextField` (پرامپت اختصاصی تشخیص هوش مصنوعی) |
|
||||
* `interval_minutes`: `IntegerField(choices=[(5, 5), (15, 15), (30, 30), (60, 60)])` (فاصلهٔ زمانی بین اجراها) |
|
||||
* `start_hour`: `TimeField` (پنجره زمانی مجاز - شروع) |
|
||||
* `end_hour`: `TimeField` (پنجره زمانی مجاز - پایان) |
|
||||
* `telegram_channel_id`: `CharField(max_length=100, blank=True, null=True)` (نام کاربری یا آیدی عددی کانال تلگرام) |
|
||||
* `is_active`: `BooleanField(default=True)` (وضعیت فعال/غیرفعال) |
|
||||
* `created_at`: `DateTimeField(auto_now_add=True)` |
|
||||
* `updated_at`: `DateTimeField(auto_now=True)` |
|
||||
* *Constraints & Indexes:* |
|
||||
* ایندکس روی `is_active` و `created_at` |
|
||||
* اعتبارسنجی فرمت لینک دیوار (باید با `https://divar.ir/s/` شروع شود) |
|
||||
|
|
||||
#### مدل ۲: `Ad` (جدول `ads` در اپلیکیشن `ads`) |
|
||||
ذخیرهسازی اطلاعات آگهیهای کرال شده از دیوار. |
|
||||
* `id`: `UUIDField` (کلید اصلی) |
|
||||
* `divar_token`: `CharField(max_length=50, unique=True)` (شناسه یکتای دیوار به عنوان توکن آگهی) |
|
||||
* `title`: `CharField(max_length=255)` (عنوان آگهی) |
|
||||
* `description`: `TextField` (توضیحات کامل متنی آگهی) |
|
||||
* `price`: `CharField(max_length=100, null=True)` (قیمت درج شده در آگهی به صورت متنی) |
|
||||
* `category`: `CharField(max_length=100, null=True)` (دستهبندی آگهی) |
|
||||
* `images`: `JSONField(default=list)` (لیست آدرس تصاویر آگهی) |
|
||||
* `url`: `URLField` (لینک مستقیم صفحه آگهی) |
|
||||
* `created_at`: `DateTimeField(auto_now_add=True)` (تاریخ اولین ثبت در سیستم ما) |
|
||||
* `published_at`: `DateTimeField(null=True)` (تاریخ ثبت آگهی در دیوار - در صورت امکان استخراج) |
|
||||
* *Constraints & Indexes:* |
|
||||
* ایندکس یکتا (Unique Index) روی فیلد `divar_token` |
|
||||
* ایندکس روی فیلد `created_at` برای مرتبسازی در پنل |
|
||||
|
|
||||
#### مدل ۳: `AdEvaluation` (جدول `ad_evaluations` در اپلیکیشن `ads`) |
|
||||
ثبت نتایج بررسی هوش مصنوعی روی هر آگهی بر اساس هر تسک کرال مشخص. |
|
||||
* `id`: `UUIDField` (کلید اصلی) |
|
||||
* `crawl_task`: `ForeignKey(CrawlTask, on_delete=CASCADE)` (رابطه با تسک کرال) |
|
||||
* `ad`: `ForeignKey(Ad, on_delete=CASCADE)` (رابطه با آگهی ارزیابی شده) |
|
||||
* `is_flagged`: `BooleanField(default=False)` (آیا با پرامپت همخوانی دارد؟) |
|
||||
* `reason`: `TextField(null=True)` (دلیل پرچمگذاری یا عدم پرچمگذاری ارائهشده توسط LLM) |
|
||||
* `confidence`: `FloatField(null=True)` (میزان اطمینان مدل بین ۰.۰ تا ۱.۰ یا ۰ تا ۱۰۰) |
|
||||
* `extracted_fields`: `JSONField(default=dict)` (اطلاعات ساختاریافته اضافی استخراج شده) |
|
||||
* `evaluated_at`: `DateTimeField(auto_now_add=True)` |
|
||||
* *Constraints & Indexes:* |
|
||||
* محدودیت یکتا بودن ترکیبی `UniqueConstraint(fields=['crawl_task', 'ad'])` جهت جلوگیری از تحلیل تکراری یک آگهی در یک کرال خاص. |
|
||||
* ایندکس روی `is_flagged`. |
|
||||
|
|
||||
#### مدل ۴: `CrawlRun` (جدول `crawl_runs` در اپلیکیشن `crawlers`) |
|
||||
لاگ تاریخچه و وضعیت اجراهای هر کرال تسک. |
|
||||
* `id`: `UUIDField` (کلید اصلی) |
|
||||
* `crawl_task`: `ForeignKey(CrawlTask, on_delete=CASCADE)` |
|
||||
* `started_at`: `DateTimeField(auto_now_add=True)` |
|
||||
* `finished_at`: `DateTimeField(null=True)` |
|
||||
* `status`: `CharField(max_length=20, choices=[('RUNNING', 'Running'), ('SUCCESS', 'Success'), ('FAILED', 'Failed')])` |
|
||||
* `ads_fetched_count`: `IntegerField(default=0)` (تعداد آگهیهای تازه یافته شده) |
|
||||
* `ads_evaluated_count`: `IntegerField(default=0)` (تعداد آگهیهای ارسال شده به AI) |
|
||||
* `ads_flagged_count`: `IntegerField(default=0)` (تعداد آگهیهای منطبق) |
|
||||
* `error_log`: `TextField(null=True, blank=True)` (در صورت شکست، علت خرابی در اینجا ثبت میشود) |
|
||||
|
|
||||
#### مدل ۵: `NotificationLog` (جدول `notification_logs` در اپلیکیشن `ads`) |
|
||||
لاگ ارسال پیام به تلگرام. |
|
||||
* `id`: `UUIDField` (کلید اصلی) |
|
||||
* `evaluation`: `ForeignKey(AdEvaluation, on_delete=CASCADE)` (مرجع ارزیابی صورت گرفته) |
|
||||
* `channel_id`: `CharField(max_length=100)` (آدرس کانال هدف) |
|
||||
* `sent_at`: `DateTimeField(auto_now_add=True)` |
|
||||
* `status`: `CharField(max_length=20, choices=[('SENT', 'Sent'), ('FAILED', 'Failed')])` |
|
||||
* `error_message`: `TextField(null=True, blank=True)` (در صورت بروز خطای API تلگرام) |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۱. Workflow دقیق عملیاتی (Detailed operational workflow) |
|
||||
|
|
||||
```mermaid |
|
||||
sequenceDiagram |
|
||||
autonumber |
|
||||
participant CB as Celery Beat |
|
||||
participant CW as Celery Worker |
|
||||
participant DB as PostgreSQL |
|
||||
participant D as Divar (API/HTML) |
|
||||
participant LLM as LLM API |
|
||||
participant TG as Telegram API |
|
||||
|
|
||||
CB->>CW: Trigger Crawl Task (Task ID) |
|
||||
CW->>DB: Check if CrawlTask is active & in allowed hours |
|
||||
DB-->>CW: CrawlTask Info |
|
||||
CW->>DB: Create CrawlRun record (Status: RUNNING) |
|
||||
CW->>D: HTTP GET Divar Filter URL |
|
||||
D-->>CW: Raw HTML / JSON Ads List |
|
||||
|
|
||||
loop For each Ad in list |
|
||||
CW->>DB: Query Ad by divar_token (Deduplication) |
|
||||
alt Ad is new |
|
||||
CW->>DB: Save new Ad (divar_token, title, details) |
|
||||
else Ad exists |
|
||||
CW->>DB: Get existing Ad |
|
||||
end |
|
||||
|
|
||||
CW->>DB: Query AdEvaluation for (CrawlTask, Ad) |
|
||||
alt Evaluation doesn't exist (New Evaluation) |
|
||||
CW->>LLM: Post Prompt + Ad Content |
|
||||
LLM-->>CW: JSON structured output (is_flagged, reason, etc) |
|
||||
CW->>DB: Save AdEvaluation (is_flagged, reason, confidence) |
|
||||
|
|
||||
alt is_flagged is TRUE |
|
||||
alt Telegram Channel is set |
|
||||
CW->>TG: Send FormatMessage (Ad URL, Reason) |
|
||||
alt Send Success |
|
||||
CW->>DB: Log NotificationLog (Status: SENT) |
|
||||
else Send Failed |
|
||||
CW->>DB: Log NotificationLog (Status: FAILED, Error) |
|
||||
end |
|
||||
end |
|
||||
end |
|
||||
else Evaluation already exists |
|
||||
Note over CW,DB: Skip evaluation to save costs |
|
||||
end |
|
||||
end |
|
||||
|
|
||||
CW->>DB: Update CrawlRun (Status: SUCCESS, finished_at) |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۲. معماری سلری (Celery Architecture) |
|
||||
سیستم زمانبندی مبتنی بر `django-celery-beat` پیادهسازی میشود تا مدیر بتواند زمان اجرای هر کرال را مستقیماً از دیتابیس یا پنل تغییر دهد. |
|
||||
|
|
||||
#### ساختار تسکها (Tasks) |
|
||||
1. `run_crawl_pipeline(crawl_task_id)`: تسک اصلی که توسط Beat فراخوانده میشود. مسئول دریافت دادههای دیوار، یکتاسازی، صدا زدن لایه پردازش و مدیریت وضعیت کل اجرای کرال است. |
|
||||
2. `evaluate_ad_with_ai(evaluation_id)`: تسک فراخوانی هوش مصنوعی. به صورت آسنکرون توسط تسک اصلی برای هر آگهی جدید لانچ میشود. (میتوان جهت کاهش مصرف ریسورس و عدم بلاک شدن صف، این کار را به صورت سری در یک تسک انجام داد یا از تسکهای فرعی با نرخ کنترلشده استفاده کرد. در فاز MVP، تسکها به صورت متوالی در تسک اصلی فراخوانی میشوند تا از Rate Limit شبکه و LLM جلوگیری شود). |
|
||||
3. `send_telegram_notification(evaluation_id)`: تسک ارسال نوتیفیکیشن تلگرام. در صورت نیاز به تلاش مجدد در صورت خطای موقت شبکه تلگرام. |
|
||||
|
|
||||
#### تنظیمات زمانبندی (Scheduler & Commands) |
|
||||
* اجرای ورکر: `celery -A core worker -l info` |
|
||||
* اجرای بیت: `celery -A core beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler` |
|
||||
* سیاست تلاش مجدد (Retry Policy): برای تسکهای خروجی (LLM و تلگرام) سیاست Retry با تاخیر فزاینده (Exponential Backoff) با ضریب `countdown=60` و حداکثر ۳ بار تکرار تنظیم میشود: |
|
||||
```python |
|
||||
@app.task(bind=True, max_retries=3, default_retry_delay=60) |
|
||||
def my_task(self, *args, **kwargs): |
|
||||
try: |
|
||||
# Code |
|
||||
except TemporaryNetworkError as exc: |
|
||||
raise self.retry(exc=exc, countdown=self.request.retries ** 2 + 60) |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۳. معماری ارتباط با هوش مصنوعی (AI Integration Architecture) |
|
||||
برای اطمینان از خروجی کاملاً ساختاریافته، سیستم از قابلیت **Structured Outputs (JSON Schema)** ارائهشده توسط OpenAI یا ابزارهای مشابه به همراه Pydantic در جنگو استفاده میکند. |
|
||||
|
|
||||
#### قالب پرامپت سیستم (System Prompt Template) |
|
||||
```text |
|
||||
You are an expert real estate and classified ads analyzer. |
|
||||
Your task is to analyze the following Persian ad from Divar according to the user's specific request. |
|
||||
You must output a valid JSON matching the schema provided. Do not include any markdown format tags like ```json in the output. |
|
||||
|
|
||||
User specific criteria: |
|
||||
{USER_DETECTION_PROMPT} |
|
||||
|
|
||||
Ad Title: {AD_TITLE} |
|
||||
Ad Description: {AD_DESCRIPTION} |
|
||||
Ad Category: {AD_CATEGORY} |
|
||||
Ad Price: {AD_PRICE} |
|
||||
``` |
|
||||
|
|
||||
#### ساختار JSON خروجی مورد انتظار (JSON Schema) |
|
||||
```json |
|
||||
{ |
|
||||
"type": "object", |
|
||||
"properties": { |
|
||||
"is_flagged": { |
|
||||
"type": "boolean", |
|
||||
"description": "True if the ad matches the user specific criteria, False otherwise." |
|
||||
}, |
|
||||
"reason": { |
|
||||
"type": "string", |
|
||||
"description": "Detailed explanation in Persian on why the ad matches or does not match." |
|
||||
}, |
|
||||
"confidence": { |
|
||||
"type": "number", |
|
||||
"minimum": 0.0, |
|
||||
"maximum": 1.0, |
|
||||
"description": "Confidence score of the evaluation." |
|
||||
}, |
|
||||
"extracted_fields": { |
|
||||
"type": "object", |
|
||||
"description": "Any key-value details extracted from the ad text (e.g., cell_number, exchange_item, discount_status)." |
|
||||
} |
|
||||
}, |
|
||||
"required": ["is_flagged", "reason", "confidence", "extracted_fields"] |
|
||||
} |
|
||||
``` |
|
||||
|
|
||||
#### مکانیزم Fallback و تایید صحت خروجی |
|
||||
اگر پاسخ دریافتی یک JSON معتبر نباشد، سیستم ابتدا تلاش میکند کاراکترهای اضافی را فیلتر کرده و متن را پارس کند. در صورت شکست نهایی، سیستم فیلد `is_flagged` را مقدار `False` قرار داده و جزئیات خطا را به همراه متن پاسخ خام در مدل `AdEvaluation` ذخیره میکند. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۴. ادغام با تلگرام (Telegram Integration) |
|
||||
ارسال پیام به تلگرام از طریق متد `sendMessage` در پروتکل HTTP ربات تلگرام صورت میگیرد. |
|
||||
|
|
||||
* **متد فراخوانی:** `POST https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage` |
|
||||
* **بدنهٔ درخواست:** |
|
||||
```json |
|
||||
{ |
|
||||
"chat_id": "{TELEGRAM_CHANNEL_ID}", |
|
||||
"text": "{FORMATTED_MESSAGE}", |
|
||||
"parse_mode": "HTML", |
|
||||
"disable_web_page_preview": false |
|
||||
} |
|
||||
``` |
|
||||
* **قالب پیام (Message Template):** |
|
||||
```text |
|
||||
🔔 <b>آگهی جدید پرچمگذاری شده!</b> |
|
||||
|
|
||||
📌 <b>عنوان آگهی:</b> {AD_TITLE} |
|
||||
💰 <b>قیمت:</b> {AD_PRICE} |
|
||||
|
|
||||
🤖 <b>علت پرچمگذاری (AI):</b> |
|
||||
{EVALUATION_REASON} |
|
||||
|
|
||||
🔗 <a href="{AD_URL}">مشاهده آگهی در دیوار</a> |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۵. طراحی API برای داشبورد (Dashboard API Design) |
|
||||
|
|
||||
تمامی مسیرها با پیشوند `/api/v1/` شروع میشوند. |
|
||||
|
|
||||
| روش (Method) | مسیر (Path) | هدف | بدنه درخواست (Request Body) | خروجی پاسخ (Response Code & JSON) | |
|
||||
| :--- | :--- | :--- | :--- | :--- | |
|
||||
| **GET** | `/crawlers/` | دریافت لیست کل کرالها | ندارد | `200 OK` - آرایهای از کرالها | |
|
||||
| **POST** | `/crawlers/` | ایجاد کرال جدید | فیلدهای `title`, `divar_url`, `detection_prompt`, `interval_minutes`, `start_hour`, `end_hour`, `telegram_channel_id`, `is_active` | `210 Created` - مشخصات کرال ساخته شده | |
|
||||
| **GET** | `/crawlers/{id}/` | جزئیات یک کرال مشخص | ندارد | `200 OK` - مشخصات کرال | |
|
||||
| **PUT** | `/crawlers/{id}/` | ویرایش کامل کرال | فیلدهای ویرایش شده کرال | `200 OK` - کرال بهروزرسانی شده | |
|
||||
| **DELETE** | `/crawlers/{id}/` | حذف فیزیکی کرال | ندارد | `204 No Content` | |
|
||||
| **POST** | `/crawlers/{id}/trigger/` | اجرای دستی کرال در لحظه | ندارد | `202 Accepted` - `{"status": "queued", "run_id": "uuid"}` | |
|
||||
| **GET** | `/crawlers/{id}/runs/` | دریافت لاگ اجراهای کرالر | ندارد | `200 OK` - لیست اجراهای اخیر | |
|
||||
| **GET** | `/ads/` | دریافت لیست آگهیها (با فیلتر) | فیلترهای Query: `?crawl_task={id}&is_flagged=true/false` | `200 OK` - لیست آگهیها و ارزیابیها با Pagination | |
|
||||
| **GET** | `/health/` | بررسی وضعیت سلامت سیستم | ندارد | `200 OK` - وضعیت اتصال به Postgres, Redis, LLM API | |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۶. صفحات و کامپوننتهای فرانتاند (Frontend Pages/Components) |
|
||||
* **صفحه لیست کرالها (Crawl List Page):** نمایش کارتهای کرال با سوییچ فعال/غیرفعالسازی، آخرین زمان اجرا، و دکمههای ویرایش، حذف و اجرای دستی. |
|
||||
* **صفحه فرم کرال (Crawl Form Page):** فرم ساده و زیبا با اعتبار سنجی (Validation) فیلدها با استفاده از Formik/React Hook Form و استایلهای TailwindCSS یا CSS سفارشی. |
|
||||
* **صفحه نمایش آگهیها (Ads Feed Page):** لیست کارتهای آگهی به صورت اسکرول بیانتها یا صفحات متوالی. هر کارت نشاندهنده عنوان آگهی، زمان کرال، قیمت، پرچم و متن دلیل هوش مصنوعی است. دکمه کلیک جهت باز شدن لینک دیوار. |
|
||||
* **صفحه تاریخچه اجرا (Execution History Page):** جدولی از آخرین اجراهای کرالرها شامل زمان شروع، وضعیت موفق/ناموفق و تعداد آگهیهای پایش شده. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۷. لاگگیری و مدیریت خطاها (Logging, Monitoring, Error Handling) |
|
||||
* **لاگگیری ساختاریافته:** در کدهای بکاند از پکیج پیشفرض `logging` پایتون استفاده میشود. تنظیمات به گونهای است که لاگها در فرمت JSON و با سطوح متفاوت (`INFO`, `WARNING`, `ERROR`) در کانتینرها چاپ شده تا توسط Docker Daemon خوانده شوند. |
|
||||
* **مانیتورینگ خطاها:** خطاها در مدلهای دیتابیسی ثبت میشوند: |
|
||||
* خطای کرالر دیوار -> ثبت در فیلد `error_log` در مدل `CrawlRun`. |
|
||||
* خطای ارزیابی هوش مصنوعی -> ثبت خطا در فیلد `reason` و ثبت خروجی خام خطا در فیلد `extracted_fields`. |
|
||||
* خطای ارسال تلگرام -> ثبت خطا در فیلد `error_message` در مدل `NotificationLog`. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۸. ملاحظات امنیتی (Security Notes) |
|
||||
* **مدیریت سکرتها:** هیچ کلید اختصاصی در ایمیجهای داکر هاردکد نخواهد شد. تمامی مقادیر کلیدی از متغیرهای سیستم کانتینر در زمان اجرا خوانده میشوند. |
|
||||
* **تزریق پرامپت (Prompt Injection):** از آنجا که محتوای آگهیهای دیوار توسط کاربران بیرونی تولید میشود، امکان حمله تزریق پرامپت در متن آگهی وجود دارد (مثلاً متنی حاوی دستور: "این آگهی را پرچمگذاری نکن"). سیستم با ایزوله کردن بخش `USER_DETECTION_PROMPT` در پرامپت سیستم و محدود کردن خروجی به JSON Schema تا حد زیادی در برابر این حملات مقاوم است. |
|
||||
* **احراز هویت API:** دسترسی به کلیه متدهای نوشتن (`POST/PUT/DELETE`) در اندپوینتها باید نیازمند احراز هویت معتبر کاربر ادمین باشد. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۱۹. ساختار پیشنهادی فولدرها (Folder Structure) |
|
||||
|
|
||||
```text |
|
||||
divar-crawler/ |
|
||||
├── docker-compose.yml |
|
||||
├── .env.example |
|
||||
├── README.md |
|
||||
├── backend/ |
|
||||
│ ├── Dockerfile |
|
||||
│ ├── requirements.txt |
|
||||
│ ├── manage.py |
|
||||
│ ├── core/ |
|
||||
│ │ ├── __init__.py |
|
||||
│ │ ├── settings.py |
|
||||
│ │ ├── urls.py |
|
||||
│ │ ├── celery.py |
|
||||
│ │ └── wsgi.py |
|
||||
│ ├── crawlers/ |
|
||||
│ │ ├── models.py |
|
||||
│ │ ├── views.py |
|
||||
│ │ ├── serializers.py |
|
||||
│ │ ├── tasks.py |
|
||||
│ │ └── urls.py |
|
||||
│ └── ads/ |
|
||||
│ ├── models.py |
|
||||
│ ├── views.py |
|
||||
│ ├── serializers.py |
|
||||
│ ├── tasks.py |
|
||||
│ └── urls.py |
|
||||
└── frontend/ |
|
||||
├── Dockerfile |
|
||||
├── package.json |
|
||||
├── vite.config.js |
|
||||
├── index.html |
|
||||
└── src/ |
|
||||
├── main.jsx |
|
||||
├── App.jsx |
|
||||
├── index.css |
|
||||
├── components/ |
|
||||
└── pages/ |
|
||||
``` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲۰. لیست متغیرهای محیطی نهایی (Environment Variables) |
|
||||
|
|
||||
در فایل [env.example](file:///c:/projects/divar-crawler/.env.example) ثبت میشوند: |
|
||||
* `DJANGO_SECRET_KEY`: کلید امنیتی جنگو |
|
||||
* `DJANGO_DEBUG`: وضعیت دیباگ (`True/False`) |
|
||||
* `ALLOWED_HOSTS`: دامنههای مجاز بکاند (مثلاً `localhost,backend,127.0.0.1`) |
|
||||
* `POSTGRES_DB`: نام دیتابیس (`divar_crawler_db`) |
|
||||
* `POSTGRES_USER`: کاربر دیتابیس |
|
||||
* `POSTGRES_PASSWORD`: پسورد دیتابیس |
|
||||
* `POSTGRES_HOST`: آدرس هاست دیتابیس (`postgres` در داکر) |
|
||||
* `POSTGRES_PORT`: پورت دیتابیس (`5432`) |
|
||||
* `REDIS_URL`: آدرس اتصال به ردیس (`redis://redis:6379/0`) |
|
||||
* `LLM_API_KEY`: کلید API هوش مصنوعی |
|
||||
* `LLM_API_URL`: آدرس پایه API هوش مصنوعی (در صورت نیاز به استفاده از پروکسی یا پرووایدرهای لوکال) |
|
||||
* `LLM_MODEL`: نام مدل مورد استفاده (مثلاً `gpt-4o-mini`) |
|
||||
* `TELEGRAM_BOT_TOKEN`: توکن ربات تلگرام |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲۱. راهنمای اجرا و استقرار محلی (Deployment / Local Run) |
|
||||
1. کپی کردن فایل نمونه متغیرهای محیطی: |
|
||||
```bash |
|
||||
cp .env.example .env |
|
||||
``` |
|
||||
2. مقداردهی مناسب به فایل `.env` (مخصوصاً توکنهای تلگرام و LLM). |
|
||||
3. اجرای کانتینرها به همراه بیلد اولیه: |
|
||||
```bash |
|
||||
docker compose up --build -d |
|
||||
``` |
|
||||
4. اجرای مایگریشنهای دیتابیس در کانتینر بکاند: |
|
||||
```bash |
|
||||
docker compose exec backend python manage.py migrate |
|
||||
``` |
|
||||
5. ایجاد کاربر مدیر سیستم (Superuser): |
|
||||
```bash |
|
||||
docker compose exec backend python manage.py createsuperuser |
|
||||
``` |
|
||||
6. سیستم هماکنون در آدرسهای زیر در دسترس است: |
|
||||
* پنل داشبورد (فرانتاند): `http://localhost:5173` |
|
||||
* وبسرویس (بکاند API): `http://localhost:8000/api/v1/` |
|
||||
* پنل مدیریت جنگو (Django Admin): `http://localhost:8000/admin/` |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲۲. ترتیب پیادهسازی (Implementation Order) |
|
||||
فرآیند ساخت و توسعه پروژه به ترتیب منطقی و بهینه زیر صورت میگیرد: |
|
||||
|
|
||||
1. **فاز ۱: راهاندازی زیرساخت داکر و دیتابیس** |
|
||||
* ایجاد فایلهای `docker-compose.yml` و پیکربندی کانتینرهای PostgreSQL و Redis. |
|
||||
* تست صحت اتصال دیتابیسها و کش لوکال. |
|
||||
2. **فاز ۲: ساخت برنامه جنگو و مدلهای داده** |
|
||||
* ایجاد پروژه بکاند، اتصال دیتابیس به ORM جنگو. |
|
||||
* پیادهسازی مدلهای `CrawlTask` و `Ad` و `AdEvaluation` در دیتابیس و ثبت مایگریشنها. |
|
||||
3. **فاز ۳: لایه کرالر دیوار و زمانبندی Celery** |
|
||||
* نوشتن کدهای استخراج داده از دیوار (پارس لینک فیلترها). |
|
||||
* راهاندازی کانتینرهای Celery Worker و Celery Beat. |
|
||||
* تست یکتاسازی آگهیها در تسکهای دورهای بر اساس توکن دیوار. |
|
||||
4. **فاز ۴: یکپارچهسازی هوش مصنوعی (LLM) و تلگرام** |
|
||||
* پیادهسازی ماژول فراخوانی LLM با خروجی ساختاریافته JSON. |
|
||||
* پیادهسازی ماژول ارسال پیام به ربات تلگرام. |
|
||||
* تست لوپ کامل پسزمینه (کرال -> تحلیل -> اطلاعرسانی). |
|
||||
5. **فاز ۵: پیادهسازی APIها (DRF)** |
|
||||
* طراحی و نوشتن Serializerها و Viewهای REST API. |
|
||||
* تست اندپوینتهای تعریف، ویرایش و اجرای دستی کرالها. |
|
||||
6. **فاز ۶: توسعه فرانتاند (React)** |
|
||||
* راهاندازی پروژه فرانتاند با Vite در کانتینر مجزا. |
|
||||
* طراحی صفحات فرم، داشبورد و فید آگهیها. |
|
||||
* اتصال فرانتاند به اندپوینتهای بکاند. |
|
||||
7. **فاز ۷: بررسی نهایی، پایداری و بهینهسازی لاگها** |
|
||||
* تست سناریوهای خطا (Edge Cases) و نهاییسازی مکانیزمهای لاگگیری در دیتابیس. |
|
||||
|
|
||||
--- |
|
||||
|
|
||||
### ۲۳. Manual QA Checklist برای کل معماری و Flow اصلی |
|
||||
1. [ ] کانتینرهای داکر بدون خطا بالا آمده باشند (`docker compose ps` وضعیت `Up` را برای هر ۶ سرویس نشان دهد). |
|
||||
2. [ ] آدرس `http://localhost:8000/api/v1/health/` پاسخ `200 OK` به همراه وضعیت سبز سرویسها را برگرداند. |
|
||||
3. [ ] ایجاد یک کرال در پنل با زمانبندی پویا؛ رکورد کرال با زمانبندی متناظر در جدول `django_celery_beat` ثبت شود. |
|
||||
4. [ ] تغییر زمان کرال از پنل باید زمانبندی فعال در Celery Beat را بلافاصله بهروزرسانی کند. |
|
||||
5. [ ] زمانبندی کرال در ساعات غیرمجاز (مثلاً ساعت ۲ بامداد برای کرالی با بازه ۸ تا ۲۲) نباید اجرا شود و باید در اولین اجرای ساعت مجاز بعد ادامه یابد. |
|
||||
6. [ ] با اجرای دستی کرال، درخواست استخراج به دیوار ارسال شود و آگهیهای جدید استخراج شده در جدول `Ad` با توکنهای یکتا درج شوند. |
|
||||
7. [ ] ارزیابیها در جدول `AdEvaluation` ثبت شوند. هر آگهی فقط یک رکورد متناظر با کرال داشته باشد. |
|
||||
8. [ ] در صورت برگشت پاسخ خراب از LLM، رکورد ارزیابی با وضعیت پرچم پیشفرض `False` ثبت شده و خطا در فیلد متناظر ذخیره گردد و از خرابی بقیه آگهیها جلوگیری شود. |
|
||||
9. [ ] ارسال پیام به تلگرام فقط برای آگهیهای پرچمشده رخ دهد و آگهیهای عادی نادیده گرفته شوند. |
|
||||
10. [ ] پنل داشبورد، لیست آگهیها را با مشخص کردن وضعیت پرچم به درستی نمایش دهد و کلیک روی آگهی، کاربر را به صفحه اصلی دیوار ریدایرکت کند. |
|
||||
Write
Preview
Loading…
Cancel
Save
Reference in new issue