153 lines
10 KiB
Markdown
Executable file
153 lines
10 KiB
Markdown
Executable file
# سند نیازمندیهای محصول (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)
|
||
- **مدت زمان تخمینی:** ۱.۵ تا ۲ روز کاری (۱۲ تا ۱۶ ساعت کاری)
|