امتیازدهی مشتری بالقوه و مسیر

هر مکالمه یک امتیاز مشتری بالقوه در مقیاس ۰ تا ۱۰۰ دریافت می‌کند که از سیگنال‌های قابل مشاهده استخراج می‌شود: صفحاتی که بازدیدکننده مرور کرده، میزان تعامل او در چت و اینکه آیا اطلاعات تماس خود را به اشتراک گذاشته است یا خیر. این امتیاز به‌عنوان یک نشان رنگی در لیست مکالمات، لیست مشتریان، صندوق ورودی و داخل نوار کناری هر مکالمه ظاهر می‌شود — تا تیم فروش بتواند مشتریان داغ را بدون نیاز به خواندن دوباره هر رونوشت، اولویت‌بندی کند. مصرف‌کنندگان وب‌هوک نیز امتیاز را در payload lead.captured دریافت می‌کنند، بنابراین یک سیستم CRM می‌تواند به‌طور خودکار مشتریان داغ را به یک صف متفاوت هدایت کند.

نحوه محاسبه امتیاز

LeadScoringEngine چهار وزن سقف‌دار را جمع می‌کند، مجموع را در [0, 100] محدود کرده و سپس نتیجه را به سه دسته نگاشت می‌کند:

سیگنال	وزن	سقف
تعداد صفحات منحصربه‌فرد بازدید شده	+۵ به ازای هر آدرس منحصربه‌فرد	۲۵
صفحات قصد (آدرس شامل pricing, demo, contact, buy, signup, checkout, cart, purchase, order)	+۱۵ به ازای هر صفحه منطبق	۳۰
تعامل در چت (پیام‌های مبادله شده)	+۲ به ازای هر پیام	۳۰
جذب مشتری (ایمیل موجود)	+۱۵ ثابت	۱۵

آستانه‌های دسته‌بندی: داغ ≥ ۷۰ (سبز)، گرم ۴۰–۶۹ (نارنجی)، سرد ۰–۳۹ (خاکستری). یک بازدیدکننده که یک بار فرود می‌آید، دو پیام ارسال می‌کند و ناپدید می‌شود، امتیاز ۹ (سرد) دارد. یک بازدیدکننده که چهار صفحه از جمله /pricing را بازدید می‌کند، ۸ نوبت چت می‌کند و ایمیل خود را ارسال می‌کند، امتیاز ۷۵ (داغ) دارد.

چگونه به‌روز می‌ماند

محاسبه مجدد در صف قرار می‌گیرد — هرگز در مسیر اصلی SSE نیست. RecomputeLeadScoreJob از سه مکان فعال می‌شود:

• نمایش صفحه جدید — /api/v1/widget/init هر بار که ویجت در یک صفحه جدید راه‌اندازی می‌شود، یک ردیف visitor_page_views ثبت می‌کند (بارگذاری مجدد همان صفحه در عرض ۲ دقیقه حذف تکراری می‌شود)، سپس یک محاسبه مجدد را در صف قرار می‌دهد.
• نوبت جدید ذخیره شد — PersistTurnJob هر نوبت دستیار فروش + کاربر را به جدول پیام‌ها اضافه کرده و در مسیر خروج خود، یک محاسبه مجدد را در صف قرار می‌دهد.
• جذب مشتری — زمانی که بازدیدکننده فرم جذب مشتری را ارسال می‌کند، کنترل‌رنده محاسبه مجدد را به‌صورت همزمان قبل از ارسال RouteLeadJob اجرا می‌کند، بنابراین payload وب‌هوک امتیاز به‌روز را می‌بیند.

مسیر بازدیدکننده

پشت امتیاز، یک ردپای مرور به ازای هر بازدیدکننده قرار دارد. هر صفحه‌ای که ویجت روی آن نصب می‌شود، یک ردیف در visitor_page_views ثبت می‌کند:

id           bigserial
workspace_id uuid       -- محدوده فضای کاری
agent_id     uuid
visitor_id   uuid
conversation_id uuid    -- قابل تهی (زمانی تنظیم می‌شود که نمایش صفحه
                        --           در داخل یک مکالمه فعال رخ دهد)
url          varchar(500)
title        varchar(200) nullable
referrer     varchar(500) nullable
viewed_at    timestamptz
created_at   timestamptz

صفحه جزئیات مکالمه (/app/conversations/{id}) ۵۰ نمایش صفحه آخر را به‌صورت زمانی در نوار کناری راست نمایش می‌دهد — صفحاتی که در طول مکالمه بازدید شده‌اند، یک حاشیه سبز دریافت می‌کنند تا اپراتور بتواند مرور در حین چت را از بازدیدهای قبلی تشخیص دهد.

payload وب‌هوک

رویداد lead.captured اکنون با سه فیلد اضافی ارائه می‌شود:

{
  "event": "lead.captured",
  "lead": { "id": "01h…", "email": "buyer@example.com", … },
  "agent_id": "01h…",
  "score": 75,
  "score_bucket": "high",
  "trajectory": [
    {
      "url": "https://example.com/pricing",
      "title": "Pricing — Plans",
      "referrer": "https://google.com",
      "viewed_at": "2026-05-18T10:14:02+00:00"
    },
    …
  ]
}

مسیر به ۱۰ نمایش اخیر محدود می‌شود تا payloadها کوچک بمانند. score_bucket یکی از low، medium، high است.

چرا این امتیاز؟ (آرایه دلایل)

هر محاسبه مجدد همچنین تجزیه خط‌به‌خط را در conversations.lead_score_reasons (JSON) ذخیره می‌کند. هر ردیف یک رشته قابل خواندن توسط انسان است که موتور در مسیر رسیدن به مجموع منتشر کرده است — به عنوان مثال "بازدید از ۳ صفحه منحصربه‌فرد (+۱۵)"، "بازدید از ۲ صفحه قصد (قیمت‌گذاری، دمو) (+۳۰)"، "ارسال / دریافت ۵ پیام (+۱۰)"، "اطلاعات تماس جذب شد (+۱۵)". صفحه جزئیات مکالمه لیست را در بخش امتیاز مشتری بالقوه نمایش می‌دهد تا اپراتور دقیقاً بداند کدام سیگنال‌ها فعال شده‌اند؛ خود نشان نیز همان خطوط را در راهنمای ابزار خود هنگام هاور نشان می‌دهد. زمانی که یک سیگنال ۰ کمک کند، حذف می‌شود — یک مشتری سرد با هیچ تطابق قصدی، به‌سادگی موارد کمتری را لیست می‌کند.

پر کردن مجدد مکالمات موجود

ستون امتیاز به‌طور پیش‌فرض برای هر مکالمه‌ای که قبل از ارائه این قابلیت وجود داشته است، ۰ است. برای محاسبه مجدد انبوه در برابر تاریخچه، دستور زیر را اجرا کنید:

php artisan pitchbar:recompute-lead-scores

پرچم‌های مفید:

• --workspace={uuid} — محدود به یک فضای کاری
• --agent={uuid} — محدود به یک دستیار فروش (لغو --workspace)
• --queue — یک RecomputeLeadScoreJob به ازای هر مکالمه به‌جای اجرای درون‌خطی ارسال می‌کند. برای فضاهای کاری بسیار بزرگ (میلیون‌ها مکالمه) که پردازشگر تحلیل‌ها باید کار را در پس‌زمینه انجام دهد، از این استفاده کنید.
• --chunk=500 — اندازه دسته ردیف برای تکرارکننده chunkById (پیش‌فرض ۵۰۰). در میزبان‌های با محدودیت حافظه به ۱۰۰ کاهش دهید.

دستور idempotent است: اجرای مجدد آن فقط امتیاز + دلایل را با جدیدترین مقادیر بازنویسی می‌کند. مکالمات محیط آزمایشی همیشه رد می‌شوند.

مکالمات با امتیاز صفر

یک مکالمه کاملاً جدید بدون نمایش صفحه، بدون پیام و بدون اطلاعات تماس جذب‌شده، امتیاز ۰ دارد و در دسته سرد قرار می‌گیرد. رابط کاربری نشان را زمانی که امتیاز ۰ است، به‌طور کامل مخفی می‌کند — از نمایش ردیف‌هایی از نشان‌های خاکستری "سرد · ۰" در هر بارگذاری گذری ویجت که هرگز نوبتی را فعال نمی‌کند، جلوگیری می‌کند. مکالمات فقط پس از فعال شدن اولین سیگنال امتیازدهی (معمولاً یک نمایش صفحه از طریق /init در یک آدرس صفحه غیرخالی) شروع به نشان دادن نشان می‌کنند.

فیلتر کردن صندوق ورودی / لیست مشتریان

هر دو صفحه /app/inbox و /app/agents/{id}/leads هر دستیار فروش، یک کلید فقط داغ را در نوار ابزار نمایش می‌دهند — زمانی که روشن باشد، لیست به مشتریانی محدود می‌شود که مکالمه زیربنایی آنها امتیاز ≥ ۷۰ داشته باشد. این کلید قابل نشانه‌گذاری است: آدرس ?hot=1 را دریافت کرده و در بازخوانی باقی می‌ماند.

تنظیم

وزن‌ها در app/Services/Scoring/LeadScoringEngine.php قرار دارند. یک سیگنال جدید با نوشتن یک متد خصوصی scoreFoo() که ['score' => int, 'reasons' => string[]] را برمی‌گرداند و اضافه کردن آن به آرایه بخش‌های compute() اضافه کنید. مجموع سقف‌ها را معقول نگه دارید — مجموع به‌هرحال به ۱۰۰ محدود می‌شود، اما وزن بیش از حد یک سیگنال، مرزهای دسته‌بندی را بی‌معنی می‌کند.

برای گسترش لیست کلمات کلیدی قصد، LeadScoringEngine::INTENT_KEYWORDS را ویرایش کنید. تطابق زیررشته‌ای بدون در نظر گرفتن حروف بزرگ و کوچک فقط در برابر آدرس — افزودن یک کلمه کلیدی، مکالمات تاریخی را تا زمانی که محاسبه مجدد بعدی فعال شود (یعنی نمایش صفحه، پیام یا جذب مشتری بعدی در آن مکالمه) دوباره امتیازدهی نمی‌کند. از php artisan pitchbar:recompute-lead-scores برای اعمال یک محاسبه مجدد انبوه در برابر ردیف‌های موجود استفاده کنید.

موتور تاریخچه نمایش صفحه را به ۲۰۰ ردیف اخیر به ازای هر بازدیدکننده محدود می‌کند (LeadScoringEngine::MAX_PAGE_VIEWS). فراتر از آن، وزن‌ها به‌هرحال اشباع می‌شوند و سقف، کوئری را برای بازدیدکنندگان طولانی‌مدت و بازگشتی ارزان نگه می‌دارد.