ارتقای پایپلاین یکپارچهسازی باشگاه مشتریان «دوباره» (Dobare Loyalty Club)
سامانه اکیپا در حال حاضر وبهوک ارسال تراکنشها به باشگاه مشتریان «دوباره» (مستندات API دوباره) را فعال دارد، اما دو باگ ساختاری اساسی و یک کمبود دادهای جدی عملکرد مارکتینگ و ریتنشن را مختل کرده است:
| مشکل شناساییشده | وضعیت فعلی | تأثیر بر کسبوکار (Impact) | اقدام فنی الزامی |
|---|---|---|---|
| تحریف مبلغ سفارش (GMV) | مبلغ تخفیفخورده نهایی پرداختی مشتری (Paid Amount) به عنوان مبلغ سفارش به دوباره فرستاده میشود. | گزارشهای GMV، متوسط سبد خرید (AOV) و RFM در دوباره کاملاً کمتر از واقعیت ثبت میشوند. | تفکیک فیلدهای ارزش کل (Gross)، مبلغ پرداختی (Paid) و مبلغ تخفیف (Discount). |
| عدم سگمنتیشن و دستهبندی محصولات | تمامی سفارشها با عناوین خام یا برچسبهای ناقص مانند اتاق فرار ثبت شده و دستهبندی موضوعی، سطح ترس و شهر وجود ندارد. | امکان ارسال پیامک و کمپینهای سگمنتشده بر اساس علاقه کاربر (مثلاً فقط عاشقان ترسناک یا فقط بردگیم) غیرممکن است. | تولید تگهای ساختاریافته چندبُعدی با استاندارد Prefix--Value-- و ارسال در member_labels_to_add. |
| نقص دادههای تاریخی (فقط ۱۳ هزار شماره) | دادهها تنها از بازه زمانی نامشخص/محدود همگام شدهاند و کل مشتریان تاریخی اکیپا منتقل نشدهاند. | ریچ کمپینهای ریتنشن به شدت افت کرده و مشتریان قدیمی نادیده گرفته شدهاند. | اجرای اسکریپت بکفیل (Backfill Job) با مدیریت Rate-Limit (اولویت ۱: کل تاریخچه، اولویت ۲: از ۱۴۰۴/۰۱/۰۱). |
تأثیر صفر در سمت کاربر. فرآیند خرید، ثبت نام و رزرو بدون هیچ تغییری کار میکند. وبهوک به صورت کاملاً غیرهمگام (Asynchronous) پس از تأیید پرداخت در بکاند فعال میشود تا هیچ تاخیری متوجه تجربه کاربر نشود.
بدون تغییر UI در این فاز. سلر تغییری نمیبیند؛ با این حال تگهای مربوط به شناسه مجموعه و بازی سلر در پایلود قرار میگیرد تا دوباره بتواند گزارشهای مجزا تفکیک کند.
اختیاری (فاز بعد): اضافه شدن وضعیت سینک دوباره در جزئیات سفارش، و دکمه اضطراری «ارسال مجدد به دوباره» (Retry Dobare Sync) برای رفع خطاهای موردی در صورت نیاز ادمین.
مطابق اسکیما اندپوینت 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--"
]
}
با توجه به ساختار پنل برچسبهای دوباره (الگوی Prefix--Value-- که در عکس داشبورد مشاهده شد)، بکاند باید در هنگام ساخت سفارش، تگهای زیر را داینامیک استخراج کرده و در لیست برچسبهای مشتری اضافه کند:
| کد شناسه | کلید لاتین (Slug) | عنوان نمایشی در اکیپا | فرمت استاندارد برچسب دوباره |
|---|---|---|---|
| 1 | scary | اتاق فرار ترسناک | Fear--scary-- |
| 2 | notscary | اتاق فرار غیرترسناک | Fear--notscary-- |
| 3 | semiscary | اتاق فرار نیمهترسناک | Fear--semiscary-- |
| 658 | cinematars | سینما ترس | Category--cinematars-- |
| 683 | feartour | تور وحشت | Category--feartour-- |
| 688 | angerroom | اتاق خشم | Category--angerroom-- |
| 746 | axethrowing | پرتاب تبر | Category--axethrowing-- |
| 794 | cafecinema | کافه سینما | Category--cafecinema-- |
| 867 | pottery | تجربه سفالگری | Category--pottery-- |
| 1419 | karaoke | کارائوکه | Category--karaoke-- |
| 3375 | lasertag | لیزرتگ | Category--lasertag-- |
| 3438 | boardgame | بردگیم | Category--boardgame-- |
| 3487 | class | کلاس آموزشی | Category--class-- |
| 3542 | travel | سفر گروهی | Category--travel-- |
| 3629 | tour | تور | Category--tour-- |
| 3803 | event | رویداد / جلسه | Category--event-- |
| house | hauntedhouse | هانتد هاوس | 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-- |
به دلیل آنکه در حال حاضر تنها حدود ۱۳ هزار کاربر در دوباره ثبت شده و تاریخچه اکیپا بسیار فراتر از این رقم است، اسکریپت بکفیل ایزوله باید نوشته و به صورت کنترلشده اجرا شود:
استخراج تمام کاربران یکتایی که تاکنون حداقل یک رزرو یا تراکنش موفق داشتهاند به همراه جزئیات سفارشها و برچسبهای متناظر از روز نخست فعالیت اکیپا.
در صورتی که حجم کل تاریخچه موجب کندی شود، فاز نخست باید کلیه سفارشها و کاربران از ۱۴۰۴/۰۱/۰۱ تا به امروز را فوراً سینک کند تا کمپینهای نوروز و بهار فعال شوند.
// اسکریپت نمونه بکفیل با کنترل 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)); // ۱ ثانیه استراحت بین بچها
}
}
بر اساس ساختار تیم موجود (۱ برنامهنویس بکاند Node.js):