sara-dashboards/PRD_فاز_اول_بهینه_سازی_موتور_جستجو.md

88 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# PRD سند نیازمندی‌های محصول: بازطراحی موتور جستجوی اکیپا (فاز ۱ - هسته اصلی)
- **عنوان پروژه:** بهینه‌سازی الگوریتم جستجو، رتبه‌بندی، تحمل خطا و پوشش جامع نتایج
- **سند:** Product Requirement Document (PRD) - Phase 1
- **مدیر محصول (PM):** سارا محمودزاده
- **تیم فنی اجرا:** آرمین زاهدی (بک‌اند) / مرتضی صادقی (فرانت‌اند)
- **اولویت:** بسیار بالا (P0)
---
## ۱. بیان مسئله و هدف‌گذاری
در موتور جستجوی فعلی، موارد زیر باعث ریزش کاربر و کاهش نرخ تبدیل شده است:
1. عدم وجود جستجوی منعطف و بسته شدن نتایج با یک اشتباه تایپی.
2. عدم پوشش فراگیر دسته‌بندی‌ها و تگ‌ها هنگام جستجوی یک مفهوم عام (مثل «سفالگری»).
3. نادیده گرفتن شهر منتخب کاربر و نمایش نامرتب نتایج شهرهای مختلف.
4. عدم پشتیبانی از تایپ انگلیسی/فینگیلیش و واژگان مترادف.
5. حذف یا وضعیت نامشخص بازی‌های متوقف‌شده.
**هدف:** رساندن نرخ سرچ‌های بدون نتیجه (Zero-Results Rate) به نزدیک صفر و نمایش کامل‌ترین و مرتبط‌ترین نتایج ممکن به کاربر بر اساس موقعیت جغرافیایی و نیاز واقعی او.
---
## ۲. مشخصات و قواعد عملکردی (Functional Specifications)
### قاعده ۱: نمایش بازی‌های متوقف‌شده با منطق دوگانه (Paused Items Behavior)
- **حالت سرچ عمومی/دسته‌بندی:** اگر سرچ کاربر کلی باشد (مثلاً «اتاق فرار ترسناک» یا «سفالگری»)، بازی‌های متوقف‌شده حتماً در نتایج می‌آیند، اما **دقیقاً در انتهای لیست نتایج (ته نتایج)** قرار می‌گیرند تا جلوی رزرو آیتم‌های فعال را نگیرند.
- **حالت سرچ با نام دقیق:** اگر کاربر **نام کامل یا دقیق یک بازی متوقف‌شده** را سرچ کرد (مثلاً «شام آخر» یا «روانی»)، بازی باید **در صدر نتایج (رتبه اول یا بالا)** نمایش یابد، اما با نشان مشخص **«توقف موقت»**.
- **طراحی ظاهری کارت متوقف:** درج برچسب خاکستری/مشکی «توقف موقت» روی عکس و کاهش شفافیت تصویر (Opacity 70%). ورود به صفحه بازی باز است ولی دکمه رزرو غیرفعال شده و دکمه «به من اطلاع بده» نمایش می‌یابد.
### قاعده ۲: خطایابی و پذیرش غلط املایی (Fuzzy Search & Typo-Tolerance)
- موتور جستجو باید تا **۲ کاراکتر غلط املایی یا اشتباه کیبورد** را بدون اینکه نتیجه صفر بدهد اصلاح کند.
- سیستم به صورت خودکار نتایج کلمه اصلاح‌شده را نشان داده و بالای لیست متن راهنما می‌گذارد:
*«نمایش نتایج برای: [کلمه صحیح] (به جای: [کلمه تایپ‌شده کاربر])»*.
### قاعده ۳: پوشش جامع نتایج و بازگرداندن همه موارد مرتبط (Comprehensive Search)
- جستجو نباید صرفاً به فیلد عنوان محدود باشد. وقتی کلمه‌ای مثل «سفالگری» یا «وحشت» سرچ می‌شود، باید **تمام آیتم‌هایی** که:
- در نام بازی هستند،
- یا دسته‌بندی آن‌هاست،
- یا در تگ‌های بازی ثبت شده‌اند،
- یا در نام مجموعه/برگزارکننده وجود دارند،
همگی بدون جا افتادن در لیست نتایج آورده شوند.
### قاعده ۴: اولویت‌بندی بر اساس موقعیت مکانی و شهر (Geo & City Boost)
- **اگر کاربر شهری را انتخاب کرده یا با IP شناسایی شده باشد:**
- نتایج متعلق به همان شهر بالاترین اولویت وزنی را می‌گیرند (Top Ranking).
- نتایج سایر شهرها در رتبه‌های بعدی چیده می‌شوند.
- **اگر شهر انتخاب نشده باشد:** شهر پیش‌فرض با بیشترین تراکم (تهران) یا براساس محبوبیت سراسری مرتب می‌شود.
### قاعده ۵: پشتیبانی از فینگیلیش و معادل‌های انگلیسی (Finglish & Latin Support)
- پوشش نام‌های انگلیسی و اسلاگ‌ها (مثلاً سرچ `joker` نتایج «جوکر» را بیاورد).
- تبدیل و نگاشت حروف فینگیلیش پرکاربرد به فارسی در پیش‌پردازش متن (مانند `sofal` -> `سفال`، `tarsnak` -> `ترسناک`).
### قاعده ۶: نگاشت کلمات هم‌معنی و مترادف‌ها (Synonyms Mapping)
- جدول یا دیکشنری مترادف‌ها در موتور سرچ:
- «ترسناک» = «وحشت» = «دلهره‌آور» = «ترس»
- «تولد» = «سوپرایز» = «جشن»
- «بچه‌گانه» = «کودک» = «خردسال»
- «معمایی» = «کارآگاهی» = «جنایی»
- سرچ هر یک از این واژه‌ها باید نتایج کل گروه مترادف را فرابخواند.
---
## ۳. تفکیک وظایف تیم فنی (Dev Tasks)
### بک‌اند (آرمین زاهدی):
1. پیاده‌سازی Fuzzy Matching با استفاده از اکستنشن `pg_trgm` (تابع `similarity`) در دیتابیس پستگرس.
2. اعمال ضرایب وزنی جستجو:
- تطابق دقیق نام در شهر کاربر: ضریب ۱۰x
- تطابق نام در شهر دیگر: ضریب ۷x
- تطابق تگ، دسته و سینونیم‌ها در شهر کاربر: ضریب ۵x
- آیتم متوقف‌شده با تطابق دقیق نام: ضریب ۴x
- آیتم متوقف‌شده عمومی: ضریب ۰.۱x (کف نتایج).
3. ایجاد جدول یا نگاشت دیکشنری مترادف‌ها و فینگیلیش.
4. افزودن فلگ‌های `is_paused` و `city_match` در خروجی API سرچ.
### فرانت‌اند (مرتضی صادقی):
1. طراحی نشان (Badge) «توقف موقت» روی کارت‌ها و غیرفعال‌سازی جریان رزرو مستقیم.
2. نمایش بنر اطلاع‌رسانی تصحیح غلط املایی بالای صفحه سرچ.
3. تفکیک بصری یا درج پیام شفاف برای اقلام انتهای لیست که متوقف هستند.
---
## ۴. معیارهای پذیرش (Acceptance Criteria)
- سرچ کلمه با ۱ یا ۲ حرف غلط املایی هرگز صفحه سفید نمی‌دهد و مرتبط‌ترین موارد را می‌آورد.
- سرچ «سفالگری» کلیه کارگاه‌ها و آیتم‌های مربوطه را بدون نقص لیست می‌کند.
- اگر اسم کامل بازی متوقف‌شده سرچ شود در بالای نتایج با بج «توقف موقت» می‌آید؛ در غیر این صورت به ته لیست می‌رود.
- اولویت نمایش بازی‌های شهر انتخابی کاربر رعایت می‌شود.
- سرچ واژه‌هایی مثل `joker` یا «وحشت» به درستی بازی‌های «جوکر» و ژانر «ترسناک» را پیدا می‌کند.