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

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