# سند نیازمندی‌های محصول (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) ```json { "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) - **مدت زمان تخمینی:** ۱.۵ تا ۲ روز کاری (۱۲ تا ۱۶ ساعت کاری)