📚 راهنمای سیستم

خلاصه سریع README

نسخه کامل در Workflows/AI_Lead_Hunting_Agent/README.md موجود است. مراحل کلیدی:

۱) توکن ادمین را در پنل وارد کنید. پایه API: https://leadsys.duckdns.org/leadhunter-api/auth
۲) Discovery با Smart Mode: پارامترهای smart_rerank، smart_snippet، smart_snippet_topk.
۳) Agent Evaluate (تکی/گروهی) Stage1/2 با پرامپت‌های پیش‌فرض campaign_company_profile_v1 و campaign_lead_eval_v1.
۴) Enqueue فقط برای لیدهای Ideal دارای ایمیل؛ subject/body پیش‌فرض قابل override.
۵) SDR Enrich (اسکرپ لینک + Stage1/2) با گزینه enqueue_if_ideal.
۶) Email Verify Batch با use_risk_guard (LLM قبل از provider) و آستانه‌های Hot/Warm؛ dry_run برای پیش‌نمایش.

شروع سریع

خوش آمدید! برای استفاده از سیستم، تنها ۳ قدم فاصله دارید:

ثبت‌نام: یک حساب کاربری بسازید تا API Key دریافت کنید.
جستجو (Discovery): در تب Discovery، مشتریان هدف خود را (مثلاً "Marketing in Dubai") جستجو کنید.
ارسال: یک کمپین بسازید تا پیام شما به صورت خودکار برای آن‌ها ارسال شود.

نکته: برای دسترسی به پنل مدیریت، روی دکمه شناور پایین صفحه کلیک کنید.

ماژول Discovery (کشف لید)

این ماژول اکنون به‌صورت مستقیم از FastAPI اجرا می‌شود (بدون وابستگی به n8n) و از چند منبع موازی تغذیه می‌کند:

LinkedIn Scraper: استخراج پروفایل‌های حرفه‌ای بر اساس شغل/مکان (Apify).
Google Places: برای بیزنس‌های محلی (آدرس، تلفن، ایمیل احتمالی).
وب‌جستجو (Searxng / Bing Agent): جمع‌آوری نتایج وب و سایت‌های مرتبط (کلیدها در `users.api_keys` ذخیره می‌شود؛ Gemini برای تولید کوئری اختیاری است).
Website Crawler جدید: اگر فیلد url را بدهید، HTML صفحه را خوانده و ایمیل/تلفن/سوشال/آدرس را استخراج می‌کند.

چطور استفاده کنم؟ (UI)

کوئری مستقیم: عبارت مثل «Marketing agencies in Dubai» را وارد کنید.
کوئری از پروفایل: تیک «استفاده از پروفایل» را بزنید؛ پروفایل شما از صفحه «پروفایل کسب‌وکار» خوانده می‌شود و با Gemini (یا fallback) ۳ تا ۱۰ کوئری می‌سازد.
نتایج ادغام‌شده شامل: ایمیل، تلفن، آدرس، شبکه‌های اجتماعی، و داده‌های وب خواهد بود.

چطور استفاده کنم؟ (API)

                POST http://leadsys.duckdns.org/leadhunter-api/auth/discovery/search

                Headers: Authorization: Bearer <token>

                {

                  "search_query": "Marketing Agencies in Dubai",

                  "limit": 5

                }

                // استفاده از پروفایل:

                { "use_profile": true, "limit_queries": 3, "limit": 5 }

خروجی نهایی

emails[], phoneNumbers[], address, businessName
facebookUrl, instagramUrl, linkedInUrl
gmap_* (در صورت وجود داده Places)
همه منابع در Merge نهایی ادغام می‌شوند و به داشبورد می‌روند.

برای کوئری‌های حجیم، محدودیت هر کاربر بر اساس «plan / leads_quota» تنظیم می‌شود؛ در صورت نیاز از ادمین افزایش بگیرید.

ماژول Enrichment (غنی‌سازی)

اطلاعات خام به تنهایی ارزشمند نیستند. این ماژول آن‌ها را تایید و تکمیل می‌کند.

۱. اعتبارسنجی ایمیل (Email Verification)

بررسی می‌کند آیا ایمیل واقعا وجود دارد یا خیر (بررسی رکوردهای MX و SMTP Handshake).

۲. حذف تکراری (Deduplication)

با استفاده از ابزار قدرتمند Splink، رکوردهای تکراری را حتی اگر کمی متفاوت نوشته شده باشند پیدا می‌کند.

                Input: "Jon Doe" & "John Doe"

                Result: Duplicate Detected (Score: 0.95)

مستندات API

اگر توسعه‌دهنده هستید، می‌توانید مستقیماً به API متصل شوید. Swagger زنده: /docs — OpenAPI: /openapi.json

Base URL: https://leadsys.duckdns.org/leadhunter-api/auth

Method	Endpoint	Description
POST	/login	ورود — دریافت JWT
POST	/otp/request + /otp/verify	ورود/ثبت‌نام با OTP
POST	/discovery/search	جستجوی وب (SearXNG)
POST	/scrape/apify/maps	Google Maps via Apify
POST	/mailerfind/scrape	Instagram scrape (direct / browser)
POST	/onboarding/quick-leads	لیدهای سریع هیبریدی
POST	/verify-email	اعتبارسنجی ایمیل
POST	/enrich	غنی‌سازی لید