ehsan-dashboards/dashboards/prds/backlog/PRD-EKP-DOBARE-SYNC.md

84 lines
5.7 KiB
Markdown
Executable file
Raw 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.

# اصلاح و توسعه یکپارچه‌سازی با باشگاه مشتریان «دوباره»
در وب‌هوک و پایپ‌لاین ارسال دیتای سفارش‌ها و کاربران به سامانه دوباره (`https://api-docs.dobare.me/redoc/`)، اصلاحات زیر در ۳ بخش **محاسبه مبالغ**، **سیستم برچسب‌گذاری (Tags)** و **بک‌فیل تاریخچه** اعمال می‌شود.
---
### ۱. اصلاح منطق محاسبه و تفکیک مبالغ سفارش
در حال حاضر فقط مبلغ پرداختی نهایی به دوباره فرستاده می‌شود که باعث تحریف گزارش‌های ارزش کل خرید (GMV) شده است. فیلدهای ارسالی باید به ۳ بخش تفکیک شوند:
- **ارزش کل خرید (Gross Amount):**
- جمع کل قیمت پایه و مصوب بلیت‌ها، قبل از اعمال هرگونه کد تخفیف.
- این مبلغ باید در فیلد اصلی مبلغ سفارش دوباره (`total_paid_amount`) فرستاده شود تا ستون «مبلغ سفارش» در پنل دوباره، رقم ناخالص واقعی را نشان دهد.
- **مبلغ پرداختی مشتری (Paid Amount):**
- رقم نهایی کسر شده از درگاه پرداخت مشتری (پس از اعمال کوپن).
- **ارزش و کد تخفیف (Discount):**
- اختلاف ارزش کل و پرداختی در فیلد `discount_amount`.
- عنوان کوپن استفاده شده در فیلد `discount_code`.
- **API هدف:**
`POST /v1/orders/`
---
### ۲. ساختار برچسب‌های سگمنتیشن (الگوی `Prefix--Value--`)
تمامی برچسب‌های رفتاری، مکانی و مشخصات بازی باید با فرمت استاندارد زیر تولید و در آرایه `member_labels_to_add` ارسال شوند:
#### الف) نگاشت نوع بازی و سطح ترس (`fear_level`)
- `1` → `Fear--scary--` (اتاق فرار ترسناک)
- `2` → `Fear--notscary--` (اتاق فرار غیرترسناک)
- `3` → `Fear--semiscary--` (اتاق فرار نیمه‌ترسناک)
- `658` → `Category--cinematars--` (سینما ترس)
- `683` → `Category--feartour--` (تور وحشت)
- `688` → `Category--angerroom--` (اتاق خشم)
- `746` → `Category--axethrowing--` (پرتاب تبر)
- `794` → `Category--cafecinema--` (کافه سینما)
- `867` → `Category--pottery--` (تجربه سفالگری)
- `1419` → `Category--karaoke--` (کارائوکه)
- `3375` → `Category--lasertag--` (لیزرتگ)
- `3438` → `Category--boardgame--` (بردگیم)
- `3487` → `Category--class--` (کلاس آموزشی)
- `3542` → `Category--travel--` (سفر گروهی)
- `3629` → `Category--tour--` (تور)
- `3803` → `Category--event--` (رویداد / جلسه)
- `house` → `Category--hauntedhouse--` (هانتد هاوس)
#### ب) اطلاعات پروفایل کاربر
- **جنسیت:** `Gender--آقا--` / `Gender--خانم--` / `Gender--نامشخص--`
- **تاریخ تولد:** ارسال در فیلد `birth_date` کاربر (فرمت `YYYY-MM-DD`).
#### ج) اطلاعات رزرو و متادیتا
- **شهر:** `City--[نام شهر]--` (مثال: `City--تهران--`)
- **منطقه / محله:** `Area--[نام محله]--` (مثال: `Area--صادقیه--`)
- **ژانر بازی:** `Genre--[عنوان ژانر]--`
- **سبک بازی:** `Style--[عنوان سبک]--`
- **مناسب برای:** `Suitable--[مخاطب]--`
- **تعداد نفرات:** `Headcount--[تعداد]--`
- **روش پرداخت:** `Payment--عادی--` / `Payment--اسنپ‌پی--` / `Payment--اعتباری--`
- **پارامترهای تحلیلی:** `CFC--[مقدار]--` و `GEN--[مقدار]--`
---
### ۳. بررسی و همگام‌سازی دیتای گذشته (Backfill)
در حال حاضر فقط حدود ۱۳ هزار شماره در دوباره موجود است که نشان‌دهنده عدم انتقال دیتای کامل است.
- **بررسی اولیه:**
- بررسی لاگ و زمان اولین تراکنش سینک شده در سیستم جهت کشف بازه مفقود.
- **اولویت اول:**
- انتقال کامل کل تاریخچه کاربران و سفارش‌های اکیپا از ابتدای فعالیت.
- **اولویت دوم (حداقلی):**
- انتقال کامل کلیه سفارش‌ها و کاربران از تاریخ `۱۴۰۴/۰۱/۰۱` تا کنون به همراه مبالغ اصلاح‌شده و تگ‌های جدید.
- **مدیریت ترافیک (Rate Limiting):**
- ارسال دسته‌ای (Batch) با محدودیت حداکثر ۵ الی ۱۰ ریکوئست در ثانیه جهت جلوگیری از خطای `429 Too Many Requests`.
---
## نکات مهم فنی
- **شناسه یکتا (`source_order_id`):** ارسال شناسه سفارش اکیپا الزامی است تا در صورت اجرای مجدد اسکریپت، سفارش تکراری ساخته نشود.
- **سقف برچسب‌ها:** حداکثر ۱۰۰ برچسب برای هر کاربر در دوباره مجاز است؛ برچسب‌های تکراری پیش از ارسال حذف شوند (`Set`).
- **تست نمونه اولیه:** قبل از اجرای بک‌فیل کلی، ۳ الی ۵ سفارش نمونه از دسته‌های مختلف (ترسناک، سینما ترس، بردگیم و خرید تخفیف‌دار) در دوباره تست و تأیید محصول گرفته شود.
---
## تخمین زمانی پیاده‌سازی
- **تیم هدف:** ۱ نفر برنامه‌نویس بک‌اند (Node.js)
- **مدت زمان تخمینی:** ۳ روز کاری (۲۴ ساعت کاری)