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

5.7 KiB
Executable file
Raw Blame History

اصلاح و توسعه یکپارچه‌سازی با باشگاه مشتریان «دوباره»

در وب‌هوک و پایپ‌لاین ارسال دیتای سفارش‌ها و کاربران به سامانه دوباره (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)
  • مدت زمان تخمینی: ۳ روز کاری (۲۴ ساعت کاری)