10 KiB
Executable file
سند نیازمندیهای محصول (PRD): اتصال به موتور جستجوی اسنپپی (SnappPay Search)
- شناسه تسک جیرا:
EKD-531 - حوزه پیادهسازی: بکاند (Node.js)
- نسخه سند:
v1.1.0 - مرجع مستندات اسنپپی:
https://academy.snapppay.ir/2026/05/10/search/
۱. خلاصه نیازمندی و هدف محصول (Product Requirement Summary)
هدف بیزینسی:
نمایش و فروش اقساطی/اعتباری تمام محصولات و تجربیات فعال وبسایت اکیپا در بخش جستجو، دستهبندیها و کمپینهای مارکتپلیس اسنپپی جهت جذب ترافیک جدید و افزایش نرخ تبدیل.
دامنه محصولات ارسالی (Scope):
تمامی دستهبندیهای فعال روی سایت اکیپا باید بهصورت خودکار در این سرویس پوشش داده شوند:
- اتاقهای فرار (با تفکیک دقیق تم و ترس):
- اتاق فرار ترسناک
- اتاق فرار نیمهترسناک
- اتاق فرار غیرترسناک / معمایی
- سینما ترس: سانسها و عناوین سینما ترس فعال.
- تجربهها و تفریحات تعاملی: اتاق خشم، پرتاب تبر، کارائوکه، لیزرتگ، کافه بردگیم و هانتد هاوس.
- رویدادها و ایونتها: بازیهای مافیا، دورهمیها و رویدادهای زماندار.
- کلاسها و کارگاههای آموزشی: کارگاههای سفالگری، کلاسهای آموزشی و ورکشاپها.
خروجی مورد انتظار از تیم فنی:
پیادهسازی یک اندپوینت استاندارد 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/jsonx-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)
- اعتبارسنجی هدر
x-api-key:- توکن امنیتی اسنپپی در فایل تنظیمات (
.env) تعریف شود. در صورت عدم تطابق هدر با کلید، خطای401 Unauthorizedبرگردانده شود.
- توکن امنیتی اسنپپی در فایل تنظیمات (
- وایتلیست آدرسهای IP ربات اسنپپی:
- ۴ آیپی زیر که متعلق به رباتهای خزش اسنپپی هستند، باید در فایروال سرور / WAF کلودفلر وایتلیست شوند تا به دلیل ریتلیمیت مسدود نشوند:
185.206.93.115185.206.94.2537.152.176.176188.121.106.231
- ۴ آیپی زیر که متعلق به رباتهای خزش اسنپپی هستند، باید در فایروال سرور / WAF کلودفلر وایتلیست شوند تا به دلیل ریتلیمیت مسدود نشوند:
۵. چکلیست پذیرش فنی (Acceptance Criteria)
- پاسخدهی استاندارد اندپوینت روی پارامترهای
limitوpageبا سرعت پاسخ زیر ۳۰۰ میلیثانیه. - بازگرداندن دادههای معتبر برای فیلتر شناسههای موردی (
products="12,34"). - اعتبارسنجی خودکار وضعیت
"outofstock"در صورت اتمام یا عدم وجود سانس باز. - آدرسدهی کامل و معتبر تصاویر در
image_linkبا پروتکل HTTPS. - پوشش ۱۰۰٪ انواع محصولات: اتاق فرار (۳ سطح ترس)، سینما ترس، تجربهها، رویدادها و کلاسها.
۶. تخمین زمانی و ظرفیت اجرایی
- تیم هدف: ۱ نفر برنامهنویس بکاند (Node.js)
- مدت زمان تخمینی: ۱.۵ تا ۲ روز کاری (۱۲ تا ۱۶ ساعت کاری)