[ { "id": "EKP-DOBARE-SYNC", "jiraKey": "EKP-DOBARE-SYNC", "title": "اصلاح و توسعه یکپارچه‌سازی با باشگاه مشتریان «دوباره»", "category": "backend", "categoryLabel": "بک‌اند (Node.js)", "status": "backlog", "statusLabel": "در انتظار گرومینگ", "version": "v2.0.0", "versionsHistory": [ { "version": "v2.0.0", "date": "۱۴۰۵/۰۶/۲۱", "author": "Product / Sara", "note": "تدوین PRD بازنویسی مبالغ، سگمنتیشن پیشرفته با برچسب‌ها و اسکریپت بک‌فیل تاریخچه" }, { "version": "v1.0.0", "date": "۱۴۰۴/۰۳/۱۰", "author": "Tech Team", "note": "پیاده‌سازی اولیه وب‌هوک پایه برای ارسال اطلاعات اولیه سفارش‌ها" } ], "estimateDaysBE": 3.0, "estimateDaysFE": 0.0, "filePath": "backlog/PRD-EKP-DOBARE-SYNC.md", "summary": "تفکیک مبالغ ناخالص (Gross) و تخفیف‌ها جهت اصلاح GMV، تولید خودکار تگ‌های سگمنتیشن (سطح ترس، دسته‌بندی، موقعیت مکانی) و اجرای بک‌فیل کنترل‌شده تاریخچه کاربران.", "tags": [ "Dobare", "Loyalty", "Webhook", "Backfill", "Node.js", "Segmentation" ], "rawContent": "# اصلاح و توسعه یکپارچه‌سازی با باشگاه مشتریان «دوباره»\n\nدر وب‌هوک و پایپ‌لاین ارسال دیتای سفارش‌ها و کاربران به سامانه دوباره (`https://api-docs.dobare.me/redoc/`)، اصلاحات زیر در ۳ بخش **محاسبه مبالغ**، **سیستم برچسب‌گذاری (Tags)** و **بک‌فیل تاریخچه** اعمال می‌شود.\n\n---\n\n### ۱. اصلاح منطق محاسبه و تفکیک مبالغ سفارش\nدر حال حاضر فقط مبلغ پرداختی نهایی به دوباره فرستاده می‌شود که باعث تحریف گزارش‌های ارزش کل خرید (GMV) شده است. فیلدهای ارسالی باید به ۳ بخش تفکیک شوند:\n\n- **ارزش کل خرید (Gross Amount):**\n - جمع کل قیمت پایه و مصوب بلیت‌ها، قبل از اعمال هرگونه کد تخفیف.\n - این مبلغ باید در فیلد اصلی مبلغ سفارش دوباره (`total_paid_amount`) فرستاده شود تا ستون «مبلغ سفارش» در پنل دوباره، رقم ناخالص واقعی را نشان دهد.\n- **مبلغ پرداختی مشتری (Paid Amount):**\n - رقم نهایی کسر شده از درگاه پرداخت مشتری (پس از اعمال کوپن).\n- **ارزش و کد تخفیف (Discount):**\n - اختلاف ارزش کل و پرداختی در فیلد `discount_amount`.\n - عنوان کوپن استفاده شده در فیلد `discount_code`.\n- **API هدف:**\n `POST /v1/orders/`\n\n---\n\n### ۲. ساختار برچسب‌های سگمنتیشن (الگوی `Prefix--Value--`)\nتمامی برچسب‌های رفتاری، مکانی و مشخصات بازی باید با فرمت استاندارد زیر تولید و در آرایه `member_labels_to_add` ارسال شوند:\n\n#### الف) نگاشت نوع بازی و سطح ترس (`fear_level`)\n- `1` → `Fear--scary--` (اتاق فرار ترسناک)\n- `2` → `Fear--notscary--` (اتاق فرار غیرترسناک)\n- `3` → `Fear--semiscary--` (اتاق فرار نیمه‌ترسناک)\n- `658` → `Category--cinematars--` (سینما ترس)\n- `683` → `Category--feartour--` (تور وحشت)\n- `688` → `Category--angerroom--` (اتاق خشم)\n- `746` → `Category--axethrowing--` (پرتاب تبر)\n- `794` → `Category--cafecinema--` (کافه سینما)\n- `867` → `Category--pottery--` (تجربه سفالگری)\n- `1419` → `Category--karaoke--` (کارائوکه)\n- `3375` → `Category--lasertag--` (لیزرتگ)\n- `3438` → `Category--boardgame--` (بردگیم)\n- `3487` → `Category--class--` (کلاس آموزشی)\n- `3542` → `Category--travel--` (سفر گروهی)\n- `3629` → `Category--tour--` (تور)\n- `3803` → `Category--event--` (رویداد / جلسه)\n- `house` → `Category--hauntedhouse--` (هانتد هاوس)\n\n#### ب) اطلاعات پروفایل کاربر\n- **جنسیت:** `Gender--آقا--` / `Gender--خانم--` / `Gender--نامشخص--`\n- **تاریخ تولد:** ارسال در فیلد `birth_date` کاربر (فرمت `YYYY-MM-DD`).\n\n#### ج) اطلاعات رزرو و متادیتا\n- **شهر:** `City--[نام شهر]--` (مثال: `City--تهران--`)\n- **منطقه / محله:** `Area--[نام محله]--` (مثال: `Area--صادقیه--`)\n- **ژانر بازی:** `Genre--[عنوان ژانر]--`\n- **سبک بازی:** `Style--[عنوان سبک]--`\n- **مناسب برای:** `Suitable--[مخاطب]--`\n- **تعداد نفرات:** `Headcount--[تعداد]--`\n- **روش پرداخت:** `Payment--عادی--` / `Payment--اسنپ‌پی--` / `Payment--اعتباری--`\n- **پارامترهای تحلیلی:** `CFC--[مقدار]--` و `GEN--[مقدار]--`\n\n---\n\n### ۳. بررسی و همگام‌سازی دیتای گذشته (Backfill)\nدر حال حاضر فقط حدود ۱۳ هزار شماره در دوباره موجود است که نشان‌دهنده عدم انتقال دیتای کامل است.\n\n- **بررسی اولیه:**\n - بررسی لاگ و زمان اولین تراکنش سینک شده در سیستم جهت کشف بازه مفقود.\n- **اولویت اول:**\n - انتقال کامل کل تاریخچه کاربران و سفارش‌های اکیپا از ابتدای فعالیت.\n- **اولویت دوم (حداقلی):**\n - انتقال کامل کلیه سفارش‌ها و کاربران از تاریخ `۱۴۰۴/۰۱/۰۱` تا کنون به همراه مبالغ اصلاح‌شده و تگ‌های جدید.\n- **مدیریت ترافیک (Rate Limiting):**\n - ارسال دسته‌ای (Batch) با محدودیت حداکثر ۵ الی ۱۰ ریکوئست در ثانیه جهت جلوگیری از خطای `429 Too Many Requests`.\n\n---\n\n## نکات مهم فنی\n- **شناسه یکتا (`source_order_id`):** ارسال شناسه سفارش اکیپا الزامی است تا در صورت اجرای مجدد اسکریپت، سفارش تکراری ساخته نشود.\n- **سقف برچسب‌ها:** حداکثر ۱۰۰ برچسب برای هر کاربر در دوباره مجاز است؛ برچسب‌های تکراری پیش از ارسال حذف شوند (`Set`).\n- **تست نمونه اولیه:** قبل از اجرای بک‌فیل کلی، ۳ الی ۵ سفارش نمونه از دسته‌های مختلف (ترسناک، سینما ترس، بردگیم و خرید تخفیف‌دار) در دوباره تست و تأیید محصول گرفته شود.\n\n---\n\n## تخمین زمانی پیاده‌سازی\n- **تیم هدف:** ۱ نفر برنامه‌نویس بک‌اند (Node.js)\n- **مدت زمان تخمینی:** ۳ روز کاری (۲۴ ساعت کاری)\n" }, { "id": "EKP-CAPACITY-V2", "jiraKey": "EKP-CAPACITY-V2", "title": "تغییرات جدید تنظیم ظرفیت سانس‌ها (پنل سلر)", "category": "fullstack", "categoryLabel": "فول‌استک (فرانت و بک)", "status": "implemented", "statusLabel": "پیاده‌سازی شده (Live)", "version": "v1.0.0", "versionsHistory": [ { "version": "v1.0.0", "date": "۱۴۰۴/۱۱/۱۵", "author": "Product / Hamed", "note": "پیاده‌سازی موفق انتخاب سه‌حالته ظرفیت در پنل سلر و اتصال اندپوینت bulk-capacity در پروداکشن" } ], "estimateDaysBE": 1.0, "estimateDaysFE": 1.0, "filePath": "implemented/PRD-EKP-CAPACITY-V2.md", "summary": "تبدیل تنظیم ظرفیت از دوحالته به سه‌حالته در پنل سلر: همه سانس‌های آینده، سانس‌های تکرارشونده خاص، و فقط همین تاریخ با افزودن APIهای bulk-capacity.", "tags": [ "Seller Panel", "Capacity", "Bulk", "Next.js", "Node.js" ], "rawContent": "# تغییرات جدید تنظیم ظرفیت سانس‌ها\n\nدر بخش **تنظیم ظرفیت**، امکان انتخاب نحوه اعمال ظرفیت به ۳ حالت اضافه شده است.\n\n### ۱. همه سانس‌ها، از این به بعد\n- ظرفیت روی تمام سانس‌های آینده تجربه اعمال می‌شود.\n- API:\n `POST /v2/seller/sec/play-boxes/bulk-capacity`\n- بدون ارسال `sessions`\n\n### ۲. سانس‌های انتخاب‌شده، از این به بعد\n- فقط سانس‌های انتخاب‌شده اعمال می‌شوند.\n- تغییر به‌صورت تکرارشونده روی تمام سانس‌های آینده با همان روز هفته و ساعت اعمال می‌شود.\n- API:\n `POST /v2/seller/sec/play-boxes/bulk-capacity`\n- همراه با `sessions` شامل `week_day` و `start_time`\n\n### ۳. فقط سانس‌های همین تاریخ\n- ظرفیت فقط برای سانس‌های انتخاب‌شده در تاریخ فعلی اعمال می‌شود.\n- روی تاریخ‌های آینده تأثیری ندارد.\n- API قبلی:\n `POST /v2/seller/sec/play-boxes/capacity`\n\n---\n\n## تغییرات UI\n\n- بخش «ظرفیت سانس‌ها» از حالت دوحالته به **انتخاب سه‌حالته** تغییر کرده است.\n- گزینه‌های جدید:\n - «همه سانس‌ها، از این به بعد»\n - «سانس‌های انتخاب‌شده، از این به بعد»\n - «فقط سانس‌های همین تاریخ»\n- در حالت‌های **«سانس‌های انتخاب‌شده»** و **«فقط همین تاریخ»**، لیست سانس‌ها نمایش داده می‌شود تا کاربر بتواند سانس‌های موردنظر را انتخاب کند.\n- در حالت **«همه سانس‌ها»**، نیازی به انتخاب سانس نیست و ظرفیت مستقیماً برای همه سانس‌های آینده اعمال می‌شود.\n- API قدیمی حذف نشده و همچنان برای اعمال ظرفیت روی **یک تاریخ مشخص** استفاده می‌شود.\n\n### نکته مهم\nتفاوت اصلی دو API جدید این است که:\n\n`bulk-capacity` بدون `sessions` → همه سانس‌های آینده\n\n`bulk-capacity` با `sessions` → سانس‌های مشخص، به‌صورت تکرارشونده در آینده\n\n`capacity` با `date` → فقط یک تاریخ مشخص\n\n---\n\n## وضعیت پیاده‌سازی\n- **وضعیت:** پیاده‌سازی شده (Deployed / Live)\n- **نسخه انتشار:** v1.0.0\n- **حوزه:** فول‌استک (پنل سلر Next.js + بک‌اند Node.js)\n- **تخمین اولیه:** ۲ روز کاری\n" }, { "id": "EKD-531", "jiraKey": "EKD-531", "title": "اتصال محصولات اکیپا به موتور جستجوی اسنپ‌پی (SnappPay Search Feed)", "category": "backend", "categoryLabel": "بک‌اند (Node.js)", "status": "backlog", "statusLabel": "در انتظار گرومینگ", "version": "v1.1.0", "versionsHistory": [ { "version": "v1.1.0", "date": "۱۴۰۵/۰۶/۲۶", "notes": "افزودن بخش خلاصه نیازمندی محصول، تفکیک دسته‌بندی‌ها و تنظیم فرمت اجرایی فنی" }, { "version": "v1.0.0", "date": "۱۴۰۵/۰۶/۲۶", "notes": "پیش‌نویس اولیه معماری فید اسنپ‌پی" } ], "estimateDays": 2.0, "createdAt": "2026-09-16", "deployedAt": null, "filePath": "backlog/PRD-EKD-531-SNAPPPAY-SEARCH.md", "htmlPath": null, "summary": "طراحی اندپوینت خوراک JSON محصولات (Searchwise Feed) برای خزشگر سرچ اسنپ‌پی شامل استاندارد نام‌گذاری، نگاشت دسته‌بندی و وایت‌لیست IPها.", "rawContent": "# سند نیازمندی‌های محصول (PRD): اتصال به موتور جستجوی اسنپ‌پی (SnappPay Search)\n\n- **شناسه تسک جیرا:** `EKD-531`\n- **حوزه پیاده‌سازی:** بک‌اند (Node.js)\n- **نسخه سند:** `v1.1.0`\n- **مرجع مستندات اسنپ‌پی:** `https://academy.snapppay.ir/2026/05/10/search/`\n\n---\n\n## ۱. خلاصه نیازمندی و هدف محصول (Product Requirement Summary)\n\n### هدف بیزینسی:\nنمایش و فروش اقساطی/اعتباری تمام محصولات و تجربیات فعال وب‌سایت اکیپا در بخش جستجو، دسته‌بندی‌ها و کمپین‌های مارکت‌پلیس اسنپ‌پی جهت جذب ترافیک جدید و افزایش نرخ تبدیل.\n\n### دامنه محصولات ارسالی (Scope):\nتمامی دسته‌بندی‌های فعال روی سایت اکیپا باید به‌صورت خودکار در این سرویس پوشش داده شوند:\n1. **اتاق‌های فرار (با تفکیک دقیق تم و ترس):**\n - اتاق فرار ترسناک\n - اتاق فرار نیمه‌ترسناک\n - اتاق فرار غیرترسناک / معمایی\n2. **سینما ترس:** سانس‌ها و عناوین سینما ترس فعال.\n3. **تجربه‌ها و تفریحات تعاملی:** اتاق خشم، پرتاب تبر، کارائوکه، لیزرتگ، کافه بردگیم و هانتد هاوس.\n4. **رویدادها و ایونت‌ها:** بازی‌های مافیا، دورهمی‌ها و رویدادهای زمان‌دار.\n5. **کلاس‌ها و کارگاه‌های آموزشی:** کارگاه‌های سفالگری، کلاس‌های آموزشی و ورکشاپ‌ها.\n\n### خروجی مورد انتظار از تیم فنی:\nپیاده‌سازی یک اندپوینت استاندارد JSON Product Feed (روش خوراک داده مبتنی بر API - طبق استاندارد Searchwise اسنپ‌پی) تا ربات‌های اسنپ‌پی بتوانند در دوره‌های منظم بدون دخالت دستی، کاتالوگ محصولات را با اطلاعات به‌روز (موجودی، قیمت و تصاویر) دریافت و ایندکس کنند.\n\n---\n\n## ۲. مشخصات فنی وب‌سرویس (Technical Specification)\n\nبه دلیل اختصاصی بودن پلتفرم اکیپا (Node.js / دیتابیس PostgreSQL) و معماری مدرن فرانت‌ند، از میان روش‌های اعلامی اسنپ‌پی، **روش شماره ۳ (خوراک محصول مبتنی بر API)** پیاده‌سازی می‌شود.\n\n- **مسیر اندپوینت پیشنهادی (Endpoint):** `POST /api/v1/product/feed` \n *(یک روت جایگزین روی `/wp-json/v1/product/feed` نیز فوروارد شود تا در صورت تنظیمات پیش‌فرض بات اسنپ‌پی، بدون کانفیگ دستی ست شود)*\n- **متد:** `POST`\n- **هدرهای الزامی (Headers):**\n - `Content-Type: application/json`\n - `x-api-key: [توکن اختصاصی دریافت‌شده از اکانت‌منیجر اسنپ‌پی]`\n\n### پارامترهای ورودی بدنه درخواست (Request Body)\nبات اسنپ‌پی درخواست‌های استعلام را در ساختار JSON زیر ارسال می‌کند:\n| فیلد | نوع داده | الزامی؟ | پیش‌فرض | عملکرد لاجیک |\n|---|---|---|---|---|\n| `page` | integer | خیر | `1` | شماره صفحه در پاسخ‌های چندصفحه‌ای |\n| `limit` | integer | خیر | `10` | تعداد آیتم در هر صفحه (سقف مجاز: تا ۱۰۰ آیتم) |\n| `products` | string | خیر | - | رشته‌ای از شناسه‌های یکتا کاما-جدا (مثال: `\"102,405\"`) جهت به‌روزرسانی سریع چند محصول خاص |\n| `slugs` | string | خیر | - | رشته‌ای از اسلاگ‌های URL محصولات جهت استعلام موردی |\n| `include_content` | boolean | خیر | `false` | ارسال یا عدم ارسال متن کامل سناریو در توضیحات |\n\n### ساختار استاندارد پاسخ خروجی (Response Schema)\n```json\n{\n \"products\": [\n {\n \"id\": 1042,\n \"slug\": \"escape-room-rooz-dahom\",\n \"title\": \"اتاق فرار روز دهم مجموعه اسکیپ روم تهران\",\n \"sale_price\": 2800000,\n \"regular_price\": 3200000,\n \"availability\": \"instock\",\n \"category\": [\n \"اتاق فرار\",\n \"ترسناک\"\n ],\n \"image_link\": [\n \"https://ekeepa.ir/uploads/games/rooz-dahom-main.jpg\",\n \"https://ekeepa.ir/uploads/games/rooz-dahom-gallery-1.jpg\"\n ],\n \"link\": \"https://ekeepa.ir/game/escape-room-rooz-dahom\",\n \"short_description\": \"اتاق فرار ترسناک و دلهره‌آور روز دهم در محله صادقیه تهران.\",\n \"description\": {\n \"ژانر\": \"ترسناک، دلهره‌آور\",\n \"سطح سختی\": \"سخت (۸ از ۱۰)\",\n \"تعداد نفرات\": \"۴ تا ۸ نفر\",\n \"مدت زمان\": \"۹۰ دقیقه\",\n \"شهر\": \"تهران\",\n \"منطقه\": \"صادقیه\"\n },\n \"cost_shipping\": 0,\n \"time_delivery\": 0,\n \"brand\": \"مجموعه اسکیپ روم دات آی آر\"\n }\n ],\n \"plugin_version\": \"1.0.2\"\n}\n```\n\n---\n\n## ۳. قواعد بیزینس‌لاجیک و نگاشت داده‌ها (Business Logic)\n\n### ۱. فرمول استاندارد عنوان‌گذاری (`title`)\nطبق الزامات سئوی داخلی اسنپ‌پی، عناوین باید هویت، ماهیت و مکان محصول را صریحاً معرفی کنند:\n- **اتاق‌های فرار:** `اتاق فرار [نام بازی] [نام مجموعه] [شهر]` \n *مثال:* `اتاق فرار احضار مجموعه انیگما تهران`\n- **سینما ترس:** `سینما ترس [نام سالن/فیلم] [نام مجموعه] [شهر]` \n *مثال:* `سینما ترس کلبه وحشت مجموعه کافه فیلم تهران`\n- **تجربه‌ها و تفریحات:** `تجربه [نام بازی/فعالیت] [نام مجموعه] [شهر]` \n *مثال:* `تجربه اتاق خشم مجموعه اکسیژن تهران` یا `تجربه پرتاب تبر مجموعه زبل‌خان تهران`\n- **ایونت‌ها و رویدادها:** `رویداد [نام رویداد] [نام برگزارکننده/کافه] [شهر]` \n *مثال:* `رویداد بازی مافیا کافه بردگیم تهران`\n- **کلاس‌ها و کارگاه‌ها:** `کارگاه آموزشی [نام دوره] [برگزارکننده] [شهر]` \n *مثال:* `کارگاه آموزشی سفالگری آتلیه خاک تهران`\n\n### ۲. آرایه دسته‌بندی (`category`)\n- اتاق فرار ترسناک: `[\"اتاق فرار\", \"ترسناک\"]`\n- اتاق فرار نیمه‌ترسناک: `[\"اتاق فرار\", \"نیمه‌ترسناک\"]`\n- اتاق فرار غیرترسناک / معمایی: `[\"اتاق فرار\", \"غیرترسناک / معمایی\"]`\n- سینما ترس: `[\"سینما ترس\", \"تفریح و هیجان\"]`\n- سایر تجربه‌ها: `[\"تجربه‌ها و تفریحات\", \"[نوع تجربه]\"]` (مثال: `[\"تجربه‌ها و تفریحات\", \"اتاق خشم\"]`)\n- رویدادها و کارگاه‌ها: `[\"رویدادها و آموزش\", \"[عنوان دوره]\"]`\n\n### ۳. وضعیت موجودی (`availability`)\n- اگر بازی فعال است و **حداقل یک سانس رزروپذیر در بازه ۳۰ روز آینده** دارد: `\"instock\"`.\n- اگر بازی در پنل غیرفعال شده یا هیچ سانس بازی در ۳۰ روز آینده ندارد: `\"outofstock\"`.\n\n### ۴. قوانین قیمت‌گذاری و سفارش\n- واحد مبالغ: مطابق با واحد ریالی/تومانی قرارداد درگاه پرداخت اسنپ‌پی اکیپا.\n- `regular_price`: مبلغ پایه و مصوب بلیت قبل از تخفیف.\n- `sale_price`: قیمت نهایی قابل‌پرداخت پس از کسر تخفیف اختصاصی بازی (در صورت عدم وجود تخفیف = `regular_price`).\n- `cost_shipping`: عدد `0` ثابت (خدمات حضوری/دیجیتال فاقد ارسال فیزیکی).\n- `time_delivery`: عدد `0` ثابت (صدور آنی بلیت).\n- `brand`: نام مجموعه / سالن برگزارکننده بازی.\n\n---\n\n## ۴. الزامات امنیتی و زیرساخت شبکه (Security & Infra)\n\n1. **اعتبارسنجی هدر `x-api-key`:**\n - توکن امنیتی اسنپ‌پی در فایل تنظیمات (`.env`) تعریف شود. در صورت عدم تطابق هدر با کلید، خطای `401 Unauthorized` برگردانده شود.\n2. **وایت‌لیست آدرس‌های IP ربات اسنپ‌پی:**\n - ۴ آی‌پی زیر که متعلق به ربات‌های خزش اسنپ‌پی هستند، باید در فایروال سرور / WAF کلودفلر وایت‌لیست شوند تا به دلیل ریت‌لیمیت مسدود نشوند:\n - `185.206.93.115`\n - `185.206.94.25`\n - `37.152.176.176`\n - `188.121.106.231`\n\n---\n\n## ۵. چک‌لیست پذیرش فنی (Acceptance Criteria)\n- [ ] پاسخ‌دهی استاندارد اندپوینت روی پارامترهای `limit` و `page` با سرعت پاسخ زیر ۳۰۰ میلی‌ثانیه.\n- [ ] بازگرداندن داده‌های معتبر برای فیلتر شناسه‌های موردی (`products=\"12,34\"`).\n- [ ] اعتبارسنجی خودکار وضعیت `\"outofstock\"` در صورت اتمام یا عدم وجود سانس باز.\n- [ ] آدرس‌دهی کامل و معتبر تصاویر در `image_link` با پروتکل HTTPS.\n- [ ] پوشش ۱۰۰٪ انواع محصولات: اتاق فرار (۳ سطح ترس)، سینما ترس، تجربه‌ها، رویدادها و کلاس‌ها.\n\n---\n\n## ۶. تخمین زمانی و ظرفیت اجرایی\n- **تیم هدف:** ۱ نفر برنامه‌نویس بک‌اند (Node.js)\n- **مدت زمان تخمینی:** ۱.۵ تا ۲ روز کاری (۱۲ تا ۱۶ ساعت کاری)\n", "tags": [ "Backend", "Ekeepa" ], "estimateDaysBE": 2.0, "estimateDaysFE": 0.0 } ]