ehsan-dashboards/dashboards/tech/backlog/PRD-EKD-531-SNAPPPAY-SEARCH.md

10 KiB
Executable file
Raw Blame History

سند نیازمندی‌های محصول (PRD): اتصال به موتور جستجوی اسنپ‌پی (SnappPay Search)

  • شناسه تسک جیرا: EKD-531
  • حوزه پیاده‌سازی: بک‌اند (Node.js)
  • نسخه سند: v1.1.0
  • مرجع مستندات اسنپ‌پی: https://academy.snapppay.ir/2026/05/10/search/

۱. خلاصه نیازمندی و هدف محصول (Product Requirement Summary)

هدف بیزینسی:

نمایش و فروش اقساطی/اعتباری تمام محصولات و تجربیات فعال وب‌سایت اکیپا در بخش جستجو، دسته‌بندی‌ها و کمپین‌های مارکت‌پلیس اسنپ‌پی جهت جذب ترافیک جدید و افزایش نرخ تبدیل.

دامنه محصولات ارسالی (Scope):

تمامی دسته‌بندی‌های فعال روی سایت اکیپا باید به‌صورت خودکار در این سرویس پوشش داده شوند:

  1. اتاق‌های فرار (با تفکیک دقیق تم و ترس):
    • اتاق فرار ترسناک
    • اتاق فرار نیمه‌ترسناک
    • اتاق فرار غیرترسناک / معمایی
  2. سینما ترس: سانس‌ها و عناوین سینما ترس فعال.
  3. تجربه‌ها و تفریحات تعاملی: اتاق خشم، پرتاب تبر، کارائوکه، لیزرتگ، کافه بردگیم و هانتد هاوس.
  4. رویدادها و ایونت‌ها: بازی‌های مافیا، دورهمی‌ها و رویدادهای زمان‌دار.
  5. کلاس‌ها و کارگاه‌های آموزشی: کارگاه‌های سفالگری، کلاس‌های آموزشی و ورکشاپ‌ها.

خروجی مورد انتظار از تیم فنی:

پیاده‌سازی یک اندپوینت استاندارد JSON Product Feed (روش خوراک داده مبتنی بر API - طبق استاندارد Searchwise اسنپ‌پی) تا ربات‌های اسنپ‌پی بتوانند در دوره‌های منظم بدون دخالت دستی، کاتالوگ محصولات را با اطلاعات به‌روز (موجودی، قیمت و تصاویر) دریافت و ایندکس کنند.


۲. مشخصات فنی وب‌سرویس (Technical Specification)

به دلیل اختصاصی بودن پلتفرم اکیپا (Node.js / دیتابیس PostgreSQL) و معماری مدرن فرانت‌ند، از میان روش‌های اعلامی اسنپ‌پی، روش شماره ۳ (خوراک محصول مبتنی بر API) پیاده‌سازی می‌شود.

  • مسیر اندپوینت پیشنهادی (Endpoint): POST /api/v1/product/feed
    (یک روت جایگزین روی /wp-json/v1/product/feed نیز فوروارد شود تا در صورت تنظیمات پیش‌فرض بات اسنپ‌پی، بدون کانفیگ دستی ست شود)
  • متد: POST
  • هدرهای الزامی (Headers):
    • Content-Type: application/json
    • x-api-key: [توکن اختصاصی دریافت‌شده از اکانت‌منیجر اسنپ‌پی]

پارامترهای ورودی بدنه درخواست (Request Body)

بات اسنپ‌پی درخواست‌های استعلام را در ساختار JSON زیر ارسال می‌کند:

فیلد نوع داده الزامی؟ پیش‌فرض عملکرد لاجیک
page integer خیر 1 شماره صفحه در پاسخ‌های چندصفحه‌ای
limit integer خیر 10 تعداد آیتم در هر صفحه (سقف مجاز: تا ۱۰۰ آیتم)
products string خیر - رشته‌ای از شناسه‌های یکتا کاما-جدا (مثال: "102,405") جهت به‌روزرسانی سریع چند محصول خاص
slugs string خیر - رشته‌ای از اسلاگ‌های URL محصولات جهت استعلام موردی
include_content boolean خیر false ارسال یا عدم ارسال متن کامل سناریو در توضیحات

ساختار استاندارد پاسخ خروجی (Response Schema)

{
  "products": [
    {
      "id": 1042,
      "slug": "escape-room-rooz-dahom",
      "title": "اتاق فرار روز دهم مجموعه اسکیپ روم تهران",
      "sale_price": 2800000,
      "regular_price": 3200000,
      "availability": "instock",
      "category": [
        "اتاق فرار",
        "ترسناک"
      ],
      "image_link": [
        "https://ekeepa.ir/uploads/games/rooz-dahom-main.jpg",
        "https://ekeepa.ir/uploads/games/rooz-dahom-gallery-1.jpg"
      ],
      "link": "https://ekeepa.ir/game/escape-room-rooz-dahom",
      "short_description": "اتاق فرار ترسناک و دلهره‌آور روز دهم در محله صادقیه تهران.",
      "description": {
        "ژانر": "ترسناک، دلهره‌آور",
        "سطح سختی": "سخت (۸ از ۱۰)",
        "تعداد نفرات": "۴ تا ۸ نفر",
        "مدت زمان": "۹۰ دقیقه",
        "شهر": "تهران",
        "منطقه": "صادقیه"
      },
      "cost_shipping": 0,
      "time_delivery": 0,
      "brand": "مجموعه اسکیپ روم دات آی آر"
    }
  ],
  "plugin_version": "1.0.2"
}

۳. قواعد بیزینس‌لاجیک و نگاشت داده‌ها (Business Logic)

۱. فرمول استاندارد عنوان‌گذاری (title)

طبق الزامات سئوی داخلی اسنپ‌پی، عناوین باید هویت، ماهیت و مکان محصول را صریحاً معرفی کنند:

  • اتاق‌های فرار: اتاق فرار [نام بازی] [نام مجموعه] [شهر]
    مثال: اتاق فرار احضار مجموعه انیگما تهران
  • سینما ترس: سینما ترس [نام سالن/فیلم] [نام مجموعه] [شهر]
    مثال: سینما ترس کلبه وحشت مجموعه کافه فیلم تهران
  • تجربه‌ها و تفریحات: تجربه [نام بازی/فعالیت] [نام مجموعه] [شهر]
    مثال: تجربه اتاق خشم مجموعه اکسیژن تهران یا تجربه پرتاب تبر مجموعه زبل‌خان تهران
  • ایونت‌ها و رویدادها: رویداد [نام رویداد] [نام برگزارکننده/کافه] [شهر]
    مثال: رویداد بازی مافیا کافه بردگیم تهران
  • کلاس‌ها و کارگاه‌ها: کارگاه آموزشی [نام دوره] [برگزارکننده] [شهر]
    مثال: کارگاه آموزشی سفالگری آتلیه خاک تهران

۲. آرایه دسته‌بندی (category)

  • اتاق فرار ترسناک: ["اتاق فرار", "ترسناک"]
  • اتاق فرار نیمه‌ترسناک: ["اتاق فرار", "نیمه‌ترسناک"]
  • اتاق فرار غیرترسناک / معمایی: ["اتاق فرار", "غیرترسناک / معمایی"]
  • سینما ترس: ["سینما ترس", "تفریح و هیجان"]
  • سایر تجربه‌ها: ["تجربه‌ها و تفریحات", "[نوع تجربه]"] (مثال: ["تجربه‌ها و تفریحات", "اتاق خشم"])
  • رویدادها و کارگاه‌ها: ["رویدادها و آموزش", "[عنوان دوره]"]

۳. وضعیت موجودی (availability)

  • اگر بازی فعال است و حداقل یک سانس رزروپذیر در بازه ۳۰ روز آینده دارد: "instock".
  • اگر بازی در پنل غیرفعال شده یا هیچ سانس بازی در ۳۰ روز آینده ندارد: "outofstock".

۴. قوانین قیمت‌گذاری و سفارش

  • واحد مبالغ: مطابق با واحد ریالی/تومانی قرارداد درگاه پرداخت اسنپ‌پی اکیپا.
  • regular_price: مبلغ پایه و مصوب بلیت قبل از تخفیف.
  • sale_price: قیمت نهایی قابل‌پرداخت پس از کسر تخفیف اختصاصی بازی (در صورت عدم وجود تخفیف = regular_price).
  • cost_shipping: عدد 0 ثابت (خدمات حضوری/دیجیتال فاقد ارسال فیزیکی).
  • time_delivery: عدد 0 ثابت (صدور آنی بلیت).
  • brand: نام مجموعه / سالن برگزارکننده بازی.

۴. الزامات امنیتی و زیرساخت شبکه (Security & Infra)

  1. اعتبارسنجی هدر x-api-key:
    • توکن امنیتی اسنپ‌پی در فایل تنظیمات (.env) تعریف شود. در صورت عدم تطابق هدر با کلید، خطای 401 Unauthorized برگردانده شود.
  2. وایت‌لیست آدرس‌های IP ربات اسنپ‌پی:
    • ۴ آی‌پی زیر که متعلق به ربات‌های خزش اسنپ‌پی هستند، باید در فایروال سرور / WAF کلودفلر وایت‌لیست شوند تا به دلیل ریت‌لیمیت مسدود نشوند:
      • 185.206.93.115
      • 185.206.94.25
      • 37.152.176.176
      • 188.121.106.231

۵. چک‌لیست پذیرش فنی (Acceptance Criteria)

  • پاسخ‌دهی استاندارد اندپوینت روی پارامترهای limit و page با سرعت پاسخ زیر ۳۰۰ میلی‌ثانیه.
  • بازگرداندن داده‌های معتبر برای فیلتر شناسه‌های موردی (products="12,34").
  • اعتبارسنجی خودکار وضعیت "outofstock" در صورت اتمام یا عدم وجود سانس باز.
  • آدرس‌دهی کامل و معتبر تصاویر در image_link با پروتکل HTTPS.
  • پوشش ۱۰۰٪ انواع محصولات: اتاق فرار (۳ سطح ترس)، سینما ترس، تجربه‌ها، رویدادها و کلاس‌ها.

۶. تخمین زمانی و ظرفیت اجرایی

  • تیم هدف: ۱ نفر برنامه‌نویس بک‌اند (Node.js)
  • مدت زمان تخمینی: ۱.۵ تا ۲ روز کاری (۱۲ تا ۱۶ ساعت کاری)