سند مشخصات فنی محصول (PRD)

ارتقای پایپ‌لاین یکپارچه‌سازی باشگاه مشتریان «دوباره» (Dobare Loyalty Club)

نسخه: 2.0.0 وضعیت: آماده برای گرومینگ / پلنینگ مخاطب: Backend Developer (Node.js) پلتفرم هدف: Ekeepa Core Backend
۱ ریشه مسئله و اهداف تجاری (Problem Statement)

سامانه اکیپا در حال حاضر وب‌هوک ارسال تراکنش‌ها به باشگاه مشتریان «دوباره» (مستندات API دوباره) را فعال دارد، اما دو باگ ساختاری اساسی و یک کمبود داده‌ای جدی عملکرد مارکتینگ و ریتنشن را مختل کرده است:

مشکل شناسایی‌شده وضعیت فعلی تأثیر بر کسب‌وکار (Impact) اقدام فنی الزامی
تحریف مبلغ سفارش (GMV) مبلغ تخفیف‌خورده نهایی پرداختی مشتری (Paid Amount) به عنوان مبلغ سفارش به دوباره فرستاده می‌شود. گزارش‌های GMV، متوسط سبد خرید (AOV) و RFM در دوباره کاملاً کمتر از واقعیت ثبت می‌شوند. تفکیک فیلدهای ارزش کل (Gross)، مبلغ پرداختی (Paid) و مبلغ تخفیف (Discount).
عدم سگمنتیشن و دسته‌بندی محصولات تمامی سفارش‌ها با عناوین خام یا برچسب‌های ناقص مانند اتاق فرار ثبت شده و دسته‌بندی موضوعی، سطح ترس و شهر وجود ندارد. امکان ارسال پیامک و کمپین‌های سگمنت‌شده بر اساس علاقه کاربر (مثلاً فقط عاشقان ترسناک یا فقط بردگیم) غیرممکن است. تولید تگ‌های ساختاریافته چندبُعدی با استاندارد Prefix--Value-- و ارسال در member_labels_to_add.
نقص داده‌های تاریخی (فقط ۱۳ هزار شماره) داده‌ها تنها از بازه زمانی نامشخص/محدود همگام شده‌اند و کل مشتریان تاریخی اکیپا منتقل نشده‌اند. ریچ کمپین‌های ریتنشن به شدت افت کرده و مشتریان قدیمی نادیده گرفته شده‌اند. اجرای اسکریپت بک‌فیل (Backfill Job) با مدیریت Rate-Limit (اولویت ۱: کل تاریخچه، اولویت ۲: از ۱۴۰۴/۰۱/۰۱).
۲ تحلیل ۳۶۰ درجه تأثیرات روی زیرسیستم‌های اکیپا

🌐 فرانت سایت کاربر (Next.js)

تأثیر صفر در سمت کاربر. فرآیند خرید، ثبت نام و رزرو بدون هیچ تغییری کار می‌کند. وب‌هوک به صورت کاملاً غیرهمگام (Asynchronous) پس از تأیید پرداخت در بک‌اند فعال می‌شود تا هیچ تاخیری متوجه تجربه کاربر نشود.

🏢 پنل سلر (Next.js / React)

بدون تغییر UI در این فاز. سلر تغییری نمی‌بیند؛ با این حال تگ‌های مربوط به شناسه مجموعه و بازی سلر در پایلود قرار می‌گیرد تا دوباره بتواند گزارش‌های مجزا تفکیک کند.

⚙️ پنل ادمین (Admin Template)

اختیاری (فاز بعد): اضافه شدن وضعیت سینک دوباره در جزئیات سفارش، و دکمه اضطراری «ارسال مجدد به دوباره» (Retry Dobare Sync) برای رفع خطاهای موردی در صورت نیاز ادمین.

۳ مشخصات فنی لاجیک مبالغ و ساختار سفارش (Order Payload)

مطابق اسکیما اندپوینت POST /v1/orders/ دوباره، پایلود هر خرید باید مقادیر تفکیک‌شده مالی را با فرمت تومان/ریال یکنواخت ارسال کند.

فیلد در API دوباره نوع داده لاجیک در دیتابیس اکیپا توضیحات و رفتار الزامی
source_order_id String (Max 128) orders.id یا orders.tracking_code شناسه یکتا سفارش در اکیپا جهت جلوگیری از تکرار (Idempotency Key).
member_phone String (Regex: 09\d{9}) users.phone شماره موبایل رزروکننده با فرمت استاندارد ۱۱ رقمی ایرانی.
member_name String users.first_name || ' ' || users.last_name نام و نام خانوادگی کاربر خریدار.
total_paid_amount Integer ارزش کل خرید (Gross Amount) یا مبلغ پرداختی خالص (Net) نکته مهم: در داشبورد دوباره ستون «مبلغ سفارش» همین فیلد است. باید ارزش کل خرید قبل از تخفیف فرستاده شود تا GMV درست باشد، و مقدار تخفیف در discount_amount ثبت گردد.
discount_amount Integer orders.discount_amount مبلغ ریالی/تومانی کسر شده توسط کد تخفیف.
discount_code String orders.coupon_code کد کوپن استفاده‌شده (در صورت وجود).
payment_method String orders.gateway_type مقادیر استاندارد: "direct_gateway"، "snappay"، "wallet".
products Array of Objects اقلام رزرو شده (آیتم بازی و سانس) شامل نام بازی، دسته موضوعی، قیمت واحد بلیت (Fee) و تعداد نفرات (Quantity).
member_labels_to_add Array of Strings موتور تگ‌گذاری خودکار (بخش ۴) آرایه برچسب‌های متناظر با کاربر و ویژگی‌های بازی خریداری‌شده.
// نمونه آبجکت ارسالی به POST /v1/orders/
{
  "source_order_id": "EKP-98421",
  "source": "ekeepa_main_web",
  "member_phone": "09123456789",
  "member_name": "عماد احمدی",
  "total_paid_amount": 700000,          // ارزش کل بلیت‌ها قبل تخفیف (یا مبلغ توافقی)
  "discount_amount": 100000,            // مبلغ تخفیف کسر شده
  "discount_code": "SUMMER1404",
  "payment_method": "snappay",
  "products": [
    {
      "sku": "GAME-482",
      "name": "اتاق فرار نفس گیر",
      "category": "اتاق فرار ترسناک",
      "fee": 175000,
      "quantity": 4
    }
  ],
  "member_labels_to_add": [
    "Fear--scary--",
    "Category--اتاق فرار--",
    "City--تهران--",
    "Area--سعادت آباد--",
    "Genre--جنایی--",
    "Headcount--4--",
    "Payment--snappay--"
  ]
}
۴ موتور تگ‌گذاری و سگمنتیشن (Tag Taxonomy Engine)

با توجه به ساختار پنل برچسب‌های دوباره (الگوی Prefix--Value-- که در عکس داشبورد مشاهده شد)، بک‌اند باید در هنگام ساخت سفارش، تگ‌های زیر را داینامیک استخراج کرده و در لیست برچسب‌های مشتری اضافه کند:

الف) جدول نگاشت سطح ترس و دسته‌بندی بازی (fear_level mapping)

کد شناسه کلید لاتین (Slug) عنوان نمایشی در اکیپا فرمت استاندارد برچسب دوباره
1scaryاتاق فرار ترسناکFear--scary--
2notscaryاتاق فرار غیرترسناکFear--notscary--
3semiscaryاتاق فرار نیمه‌ترسناکFear--semiscary--
658cinematarsسینما ترسCategory--cinematars--
683feartourتور وحشتCategory--feartour--
688angerroomاتاق خشمCategory--angerroom--
746axethrowingپرتاب تبرCategory--axethrowing--
794cafecinemaکافه سینماCategory--cafecinema--
867potteryتجربه سفالگریCategory--pottery--
1419karaokeکارائوکهCategory--karaoke--
3375lasertagلیزرتگCategory--lasertag--
3438boardgameبردگیمCategory--boardgame--
3487classکلاس آموزشیCategory--class--
3542travelسفر گروهیCategory--travel--
3629tourتورCategory--tour--
3803eventرویداد / جلسهCategory--event--
househauntedhouseهانتد هاوسCategory--hauntedhouse--

ب) ساختار برچسب‌های متادیتا، موقعیت و ویژگی‌های رفتاری

بُعد تحلیلی منبع داده در دیتابیس الگوی برچسب مثال خروجی
جنسیت کاربر users.gender Gender--[male|female|unknown]-- Gender--female--
شهر بازی games.city City--[city_name]-- City--تهران--, City--کرج--
منطقه / محله games.area Area--[area_name]-- Area--صادقیه--
ژانرهای بازی games.genres (آرایه) Genre--[genre_title]-- Genre--روحی-جن‌گیری--
سبک بازی games.style Style--[style_title]-- Style--تعاملی--
مناسب برای games.suitablefor Suitable--[target]-- Suitable--خانوادگی--
تعداد نفرات سانس orders.person_count Headcount--[count]-- Headcount--6--
متغیرهای تحلیلی کمپین پارامترهای URL: cfc و gen CFC--[val]-- و GEN--[val]-- CFC--summer_ads--
روش پرداخت orders.payment_method Payment--[type]-- Payment--snappay--
۵ معماری و پایپ‌لاین انتقال دیتای گذشته (Backfill Pipeline)

به دلیل آنکه در حال حاضر تنها حدود ۱۳ هزار کاربر در دوباره ثبت شده و تاریخچه اکیپا بسیار فراتر از این رقم است، اسکریپت بک‌فیل ایزوله باید نوشته و به صورت کنترل‌شده اجرا شود:

🎯 اولویت ۱: کل تاریخچه پلتفرم (Full History)

استخراج تمام کاربران یکتایی که تاکنون حداقل یک رزرو یا تراکنش موفق داشته‌اند به همراه جزئیات سفارش‌ها و برچسب‌های متناظر از روز نخست فعالیت اکیپا.

⚡ اولویت ۲: همگام‌سازی سریع از ۱۴۰۴/۰۱/۰۱

در صورتی که حجم کل تاریخچه موجب کندی شود، فاز نخست باید کلیه سفارش‌ها و کاربران از ۱۴۰۴/۰۱/۰۱ تا به امروز را فوراً سینک کند تا کمپین‌های نوروز و بهار فعال شوند.

قوانین نرخ ترافیک و صف اجرایی (Rate-Limiting & Queue)

// اسکریپت نمونه بک‌فیل با کنترل Concurrency و Rate Limit (Node.js)
const pLimit = require('p-limit');
const limit = pLimit(5); // حداکثر ۵ ریکوئست همزمان

async function runBackfill(fromDate = '2025-03-21') {
  console.log(`Starting backfill from: ${fromDate}`);
  let lastId = 0;
  let hasMore = true;

  while (hasMore) {
    const orders = await db.query(
      `SELECT o.*, u.phone, u.first_name, u.last_name, g.title as game_title, g.fear_level, g.city 
       FROM orders o 
       JOIN users u ON o.user_id = u.id 
       JOIN games g ON o.game_id = g.id 
       WHERE o.status = 'completed' AND o.created_at >= $1 AND o.id > $2 
       ORDER BY o.id ASC LIMIT 500`,
      [fromDate, lastId]
    );

    if (orders.rows.length === 0) {
      hasMore = false;
      break;
    }

    const tasks = orders.rows.map(order => limit(() => syncOrderToDobare(order)));
    await Promise.all(tasks);

    lastId = orders.rows[orders.rows.length - 1].id;
    console.log(`Processed up to order ID: ${lastId}`);
    await new Promise(r => setTimeout(r, 1000)); // ۱ ثانیه استراحت بین بچ‌ها
  }
}
۶ ریسک‌های فنی و راهکارهای پیشگیرانه (Risk Management)
⚠️ سقف تعداد برچسب‌ها در دوباره (Max Labels Limit): طبق مستندات دوباره، حداکثر تعداد برچسب ارسالی در هر درخواست ۱۰۰ عدد است (maxItems: 100). کد نباید تگ‌های تکراری یا نال ارسال کند. فیلتر کردن آرایه با Array.from(new Set(labels)).slice(0, 50) الزامی است.
⚠️ اعتبارسنجی فرمت شماره تلفن (Phone Regex): دوباره فقط فرمت معتبر ایران را می‌پذیرد: ^((0098|098|\+98|98)?(?:\+?98)*)(0?9\d{9})$. شماره‌هایی که این فرمت را ندارند قبل از ارسال نرمالایز شوند (09xxxxxxxxx).
⚠️ عدم پشتیبانی دوباره از به‌روزرسانی معکوس مبالغ: چنانچه سفارشی قبلاً در دوباره با مبلغ ناقص ثبت شده، ثبت مجدد آن با همان source_order_id باید بررسی شود که آیا دوباره سفارش را Update می‌کند یا ارور تکراری می‌دهد. این مورد در تست نمونه اولیه (فاز ۲) باید راستی‌آزمایی شود.
۷ تخمین زمان پیاده‌سازی هوش مصنوعی (AI Effort Estimation)

بر اساس ساختار تیم موجود (۱ برنامه‌نویس بک‌اند Node.js):

۱. اصلاح لاجیک محاسبه مبالغ (Gross / Paid / Discount) در وب‌هوک و ماژول دوباره ۰.۵ نفر-روز (۴ ساعت)
۲. پیاده‌سازی ماژول ساخت تگ‌های داینامیک (دسته‌بندی، سطح ترس، لوکیشن، متادیتا) ۱.۰ نفر-روز (۸ ساعت)
۳. توسعه و تست پایپ‌لاین بک‌فیل دسته‌ای (Batch Script + Rate-Limiting + Queue) ۱.۰ نفر-روز (۸ ساعت)
۴. اجرای تست‌های End-to-End در استیجینگ و راستی‌آزمایی با پنل دوباره ۰.۵ نفر-روز (۴ ساعت)
جمع کل زمان تخمینی توسعه و تحویل (Backend Developer): ۳.۰ نفر-روز کاری (۲۴ ساعت کاری)
۸ چک‌لیست پذیرش و تحویل (Definition of Done)
  1. یک سفارش جدید در استیجینگ ثبت شود و ستون «مبلغ سفارش» در داشبورد دوباره برابر با ارزش کل خرید (ناخالص) نمایش داده شود.
  2. مبلغ تخفیف به درستی در جزییات سفارش پنل دوباره ثبت گردد.
  3. در پروفایل کاربر خریدار در دوباره، برچسب‌های متناظر با شهر، سطح ترس، ژانر و تعداد نفرات ایجاد و الصاق شده باشند.
  4. اسکریپت بک‌فیل بدون خطا و بدون بلاک شدن توسط Rate-Limit دوباره تا انتهای بازه اجرا شود.
  5. تعداد کل کاربران ثبت‌شده در دوباره از ۱۳ هزار فعلی به آمار واقعی کاربران پلتفرم ارتقا یابد.