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

735 lines
32 KiB
HTML
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.

<!DOCTYPE html>
<html lang="fa" dir="rtl">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>PRD-EKP-DOBARE | سند مشخصات فنی ارتقای یکپارچه‌سازی باشگاه مشتریان دوباره</title>
<style>
@import url('https://fonts.googleapis.com/css2?family=Vazirmatn:wght@300;400;500;600;700;800&display=swap');
:root {
--primary: #802875;
--primary-light: #f5eef4;
--primary-dark: #5c1b54;
--secondary: #0284c7;
--success: #10b981;
--warning: #f59e0b;
--danger: #ef4444;
--slate-900: #0f172a;
--slate-800: #1e293b;
--slate-700: #334155;
--slate-600: #475569;
--slate-500: #64748b;
--slate-200: #e2e8f0;
--slate-100: #f1f5f9;
--slate-50: #f8fafc;
--white: #ffffff;
--font-family: 'Vazirmatn', -apple-system, BlinkMacSystemFont, sans-serif;
}
* {
box-sizing: border-box;
margin: 0;
padding: 0;
}
body {
font-family: var(--font-family);
font-variant-numeric: tabular-nums;
background-color: var(--slate-50);
color: var(--slate-800);
line-height: 1.7;
font-size: 15px;
padding: 32px 20px;
}
.container {
max-width: 1200px;
margin: 0 auto;
}
/* Header */
.header {
background: var(--white);
border-radius: 16px;
padding: 32px;
margin-bottom: 24px;
box-shadow: 0 4px 20px rgba(0,0,0,0.04);
border-right: 6px solid var(--primary);
display: flex;
justify-content: space-between;
align-items: flex-start;
flex-wrap: wrap;
gap: 20px;
}
.header-info h1 {
font-size: 24px;
font-weight: 800;
color: var(--slate-900);
margin-bottom: 8px;
}
.header-info p {
color: var(--slate-600);
font-size: 14px;
}
.meta-badges {
display: flex;
gap: 10px;
flex-wrap: wrap;
}
.badge {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 14px;
border-radius: 8px;
font-size: 13px;
font-weight: 600;
}
.badge-primary { background: var(--primary-light); color: var(--primary); }
.badge-warning { background: #fef3c7; color: #b45309; }
.badge-info { background: #e0f2fe; color: #0369a1; }
.badge-success { background: #d1fae5; color: #047857; }
/* Card System */
.card {
background: var(--white);
border-radius: 16px;
padding: 28px;
margin-bottom: 24px;
box-shadow: 0 2px 12px rgba(0,0,0,0.03);
border: 1px solid var(--slate-200);
}
.card-title {
font-size: 18px;
font-weight: 700;
color: var(--slate-900);
margin-bottom: 20px;
padding-bottom: 12px;
border-bottom: 2px solid var(--slate-100);
display: flex;
align-items: center;
gap: 10px;
}
.card-title .icon {
width: 28px;
height: 28px;
border-radius: 6px;
background: var(--primary-light);
color: var(--primary);
display: flex;
align-items: center;
justify-content: center;
font-size: 15px;
font-weight: 800;
}
/* Grid Layouts */
.grid-2 {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(320px, 1fr));
gap: 20px;
}
.grid-3 {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
gap: 16px;
}
/* Perspective Box */
.perspective-box {
border: 1px solid var(--slate-200);
border-radius: 12px;
padding: 20px;
background: var(--slate-50);
}
.perspective-box h4 {
font-size: 15px;
font-weight: 700;
margin-bottom: 8px;
color: var(--slate-900);
display: flex;
align-items: center;
gap: 8px;
}
.perspective-box p {
font-size: 13.5px;
color: var(--slate-600);
}
/* Tables */
.table-container {
overflow-x: auto;
margin: 16px 0;
border-radius: 10px;
border: 1px solid var(--slate-200);
}
table {
width: 100%;
border-collapse: collapse;
text-align: right;
font-size: 13.5px;
}
th {
background: var(--slate-100);
color: var(--slate-700);
padding: 12px 16px;
font-weight: 700;
white-space: nowrap;
}
td {
padding: 12px 16px;
border-top: 1px solid var(--slate-200);
color: var(--slate-800);
}
tr:hover td {
background: var(--slate-50);
}
.code-tag {
display: inline-block;
direction: ltr;
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
background: #f3f4f6;
padding: 2px 8px;
border-radius: 6px;
color: #9333ea;
font-size: 12.5px;
font-weight: 600;
}
/* Code Snippets */
.code-block {
direction: ltr;
text-align: left;
background: #1e1e2e;
color: #cdd6f4;
padding: 20px;
border-radius: 12px;
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
font-size: 13px;
overflow-x: auto;
line-height: 1.6;
margin: 16px 0;
border: 1px solid #313244;
}
.code-block pre {
margin: 0;
}
/* Estimates Box */
.estimate-card {
background: linear-gradient(135deg, #fdf4ff 0%, #fae8ff 100%);
border: 1px solid #f0abfc;
border-radius: 14px;
padding: 24px;
margin-top: 20px;
}
.estimate-stat {
display: flex;
justify-content: space-between;
align-items: center;
padding: 10px 0;
border-bottom: 1px dashed #e879f9;
}
.estimate-stat:last-child {
border-bottom: none;
font-weight: 800;
font-size: 16px;
color: var(--primary-dark);
padding-top: 16px;
}
/* Risks Alert */
.risk-item {
display: flex;
align-items: flex-start;
gap: 12px;
padding: 14px;
border-radius: 10px;
background: #fffbeb;
border-right: 4px solid var(--warning);
margin-bottom: 12px;
font-size: 13.5px;
}
.risk-item.danger {
background: #fef2f2;
border-right-color: var(--danger);
}
ul, ol {
padding-right: 20px;
margin: 10px 0;
}
li {
margin-bottom: 6px;
}
</style>
</head>
<body>
<div class="container">
<!-- Header -->
<div class="header">
<div class="header-info">
<h1>سند مشخصات فنی محصول (PRD)</h1>
<p>ارتقای پایپ‌لاین یکپارچه‌سازی باشگاه مشتریان «دوباره» (Dobare Loyalty Club)</p>
</div>
<div class="meta-badges">
<span class="badge badge-primary">نسخه: 2.0.0</span>
<span class="badge badge-warning">وضعیت: آماده برای گرومینگ / پلنینگ</span>
<span class="badge badge-info">مخاطب: Backend Developer (Node.js)</span>
<span class="badge badge-success">پلتفرم هدف: Ekeepa Core Backend</span>
</div>
</div>
<!-- 1. Problem Statement -->
<div class="card">
<div class="card-title">
<span class="icon">۱</span>
<span>ریشه مسئله و اهداف تجاری (Problem Statement)</span>
</div>
<p>
سامانه اکیپا در حال حاضر وب‌هوک ارسال تراکنش‌ها به باشگاه مشتریان «دوباره» (<a href="https://api-docs.dobare.me/redoc/" target="_blank" style="color: var(--primary); text-decoration: none; font-weight: 600;">مستندات API دوباره</a>) را فعال دارد، اما دو باگ ساختاری اساسی و یک کمبود داده‌ای جدی عملکرد مارکتینگ و ریتنشن را مختل کرده است:
</p>
<div class="table-container" style="margin-top: 16px;">
<table>
<thead>
<tr>
<th>مشکل شناسایی‌شده</th>
<th>وضعیت فعلی</th>
<th>تأثیر بر کسب‌وکار (Impact)</th>
<th>اقدام فنی الزامی</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>تحریف مبلغ سفارش (GMV)</strong></td>
<td>مبلغ تخفیف‌خورده نهایی پرداختی مشتری (Paid Amount) به عنوان مبلغ سفارش به دوباره فرستاده می‌شود.</td>
<td>گزارش‌های GMV، متوسط سبد خرید (AOV) و RFM در دوباره کاملاً کمتر از واقعیت ثبت می‌شوند.</td>
<td>تفکیک فیلدهای ارزش کل (Gross)، مبلغ پرداختی (Paid) و مبلغ تخفیف (Discount).</td>
</tr>
<tr>
<td><strong>عدم سگمنتیشن و دسته‌بندی محصولات</strong></td>
<td>تمامی سفارش‌ها با عناوین خام یا برچسب‌های ناقص مانند <span class="code-tag">اتاق فرار</span> ثبت شده و دسته‌بندی موضوعی، سطح ترس و شهر وجود ندارد.</td>
<td>امکان ارسال پیامک و کمپین‌های سگمنت‌شده بر اساس علاقه کاربر (مثلاً فقط عاشقان ترسناک یا فقط بردگیم) غیرممکن است.</td>
<td>تولید تگ‌های ساختاریافته چندبُعدی با استاندارد <span class="code-tag">Prefix--Value--</span> و ارسال در <span class="code-tag">member_labels_to_add</span>.</td>
</tr>
<tr>
<td><strong>نقص داده‌های تاریخی (فقط ۱۳ هزار شماره)</strong></td>
<td>داده‌ها تنها از بازه زمانی نامشخص/محدود همگام شده‌اند و کل مشتریان تاریخی اکیپا منتقل نشده‌اند.</td>
<td>ریچ کمپین‌های ریتنشن به شدت افت کرده و مشتریان قدیمی نادیده گرفته شده‌اند.</td>
<td>اجرای اسکریپت بک‌فیل (Backfill Job) با مدیریت Rate-Limit (اولویت ۱: کل تاریخچه، اولویت ۲: از ۱۴۰۴/۰۱/۰۱).</td>
</tr>
</tbody>
</table>
</div>
</div>
<!-- 2. Multi-Perspective Analysis -->
<div class="card">
<div class="card-title">
<span class="icon">۲</span>
<span>تحلیل ۳۶۰ درجه تأثیرات روی زیرسیستم‌های اکیپا</span>
</div>
<div class="grid-3">
<div class="perspective-box">
<h4>🌐 فرانت سایت کاربر (Next.js)</h4>
<p><strong>تأثیر صفر در سمت کاربر.</strong> فرآیند خرید، ثبت نام و رزرو بدون هیچ تغییری کار می‌کند. وب‌هوک به صورت کاملاً غیرهمگام (Asynchronous) پس از تأیید پرداخت در بک‌اند فعال می‌شود تا هیچ تاخیری متوجه تجربه کاربر نشود.</p>
</div>
<div class="perspective-box">
<h4>🏢 پنل سلر (Next.js / React)</h4>
<p><strong>بدون تغییر UI در این فاز.</strong> سلر تغییری نمی‌بیند؛ با این حال تگ‌های مربوط به شناسه مجموعه و بازی سلر در پایلود قرار می‌گیرد تا دوباره بتواند گزارش‌های مجزا تفکیک کند.</p>
</div>
<div class="perspective-box">
<h4>⚙️ پنل ادمین (Admin Template)</h4>
<p><strong>اختیاری (فاز بعد):</strong> اضافه شدن وضعیت سینک دوباره در جزئیات سفارش، و دکمه اضطراری «ارسال مجدد به دوباره» (Retry Dobare Sync) برای رفع خطاهای موردی در صورت نیاز ادمین.</p>
</div>
</div>
</div>
<!-- 3. Detailed Technical Spec: Orders & Amounts -->
<div class="card">
<div class="card-title">
<span class="icon">۳</span>
<span>مشخصات فنی لاجیک مبالغ و ساختار سفارش (Order Payload)</span>
</div>
<p>
مطابق اسکیما اندپوینت <span class="code-tag">POST /v1/orders/</span> دوباره، پایلود هر خرید باید مقادیر تفکیک‌شده مالی را با فرمت تومان/ریال یکنواخت ارسال کند.
</p>
<div class="table-container">
<table>
<thead>
<tr>
<th>فیلد در API دوباره</th>
<th>نوع داده</th>
<th>لاجیک در دیتابیس اکیپا</th>
<th>توضیحات و رفتار الزامی</th>
</tr>
</thead>
<tbody>
<tr>
<td><span class="code-tag">source_order_id</span></td>
<td>String (Max 128)</td>
<td><span class="code-tag">orders.id</span> یا <span class="code-tag">orders.tracking_code</span></td>
<td>شناسه یکتا سفارش در اکیپا جهت جلوگیری از تکرار (Idempotency Key).</td>
</tr>
<tr>
<td><span class="code-tag">member_phone</span></td>
<td>String (Regex: 09\d{9})</td>
<td><span class="code-tag">users.phone</span></td>
<td>شماره موبایل رزروکننده با فرمت استاندارد ۱۱ رقمی ایرانی.</td>
</tr>
<tr>
<td><span class="code-tag">member_name</span></td>
<td>String</td>
<td><span class="code-tag">users.first_name || ' ' || users.last_name</span></td>
<td>نام و نام خانوادگی کاربر خریدار.</td>
</tr>
<tr>
<td><span class="code-tag">total_paid_amount</span></td>
<td>Integer</td>
<td>ارزش کل خرید (Gross Amount) یا مبلغ پرداختی خالص (Net)</td>
<td><strong>نکته مهم:</strong> در داشبورد دوباره ستون «مبلغ سفارش» همین فیلد است. باید ارزش کل خرید قبل از تخفیف فرستاده شود تا GMV درست باشد، و مقدار تخفیف در <span class="code-tag">discount_amount</span> ثبت گردد.</td>
</tr>
<tr>
<td><span class="code-tag">discount_amount</span></td>
<td>Integer</td>
<td><span class="code-tag">orders.discount_amount</span></td>
<td>مبلغ ریالی/تومانی کسر شده توسط کد تخفیف.</td>
</tr>
<tr>
<td><span class="code-tag">discount_code</span></td>
<td>String</td>
<td><span class="code-tag">orders.coupon_code</span></td>
<td>کد کوپن استفاده‌شده (در صورت وجود).</td>
</tr>
<tr>
<td><span class="code-tag">payment_method</span></td>
<td>String</td>
<td><span class="code-tag">orders.gateway_type</span></td>
<td>مقادیر استاندارد: <span class="code-tag">"direct_gateway"</span>، <span class="code-tag">"snappay"</span>، <span class="code-tag">"wallet"</span>.</td>
</tr>
<tr>
<td><span class="code-tag">products</span></td>
<td>Array of Objects</td>
<td>اقلام رزرو شده (آیتم بازی و سانس)</td>
<td>شامل نام بازی، دسته موضوعی، قیمت واحد بلیت (Fee) و تعداد نفرات (Quantity).</td>
</tr>
<tr>
<td><span class="code-tag">member_labels_to_add</span></td>
<td>Array of Strings</td>
<td>موتور تگ‌گذاری خودکار (بخش ۴)</td>
<td>آرایه برچسب‌های متناظر با کاربر و ویژگی‌های بازی خریداری‌شده.</td>
</tr>
</tbody>
</table>
</div>
<div class="code-block">
<pre>// نمونه آبجکت ارسالی به 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--"
]
}</pre>
</div>
</div>
<!-- 4. Tagging & Segmentation Engine -->
<div class="card">
<div class="card-title">
<span class="icon">۴</span>
<span>موتور تگ‌گذاری و سگمنتیشن (Tag Taxonomy Engine)</span>
</div>
<p>
با توجه به ساختار پنل برچسب‌های دوباره (الگوی <span class="code-tag">Prefix--Value--</span> که در عکس داشبورد مشاهده شد)، بک‌اند باید در هنگام ساخت سفارش، تگ‌های زیر را داینامیک استخراج کرده و در لیست برچسب‌های مشتری اضافه کند:
</p>
<h3 style="margin: 20px 0 10px; font-size: 15px; color: var(--primary);">الف) جدول نگاشت سطح ترس و دسته‌بندی بازی (fear_level mapping)</h3>
<div class="table-container">
<table>
<thead>
<tr>
<th>کد شناسه</th>
<th>کلید لاتین (Slug)</th>
<th>عنوان نمایشی در اکیپا</th>
<th>فرمت استاندارد برچسب دوباره</th>
</tr>
</thead>
<tbody>
<tr><td>1</td><td><span class="code-tag">scary</span></td><td>اتاق فرار ترسناک</td><td><span class="code-tag">Fear--scary--</span></td></tr>
<tr><td>2</td><td><span class="code-tag">notscary</span></td><td>اتاق فرار غیرترسناک</td><td><span class="code-tag">Fear--notscary--</span></td></tr>
<tr><td>3</td><td><span class="code-tag">semiscary</span></td><td>اتاق فرار نیمه‌ترسناک</td><td><span class="code-tag">Fear--semiscary--</span></td></tr>
<tr><td>658</td><td><span class="code-tag">cinematars</span></td><td>سینما ترس</td><td><span class="code-tag">Category--cinematars--</span></td></tr>
<tr><td>683</td><td><span class="code-tag">feartour</span></td><td>تور وحشت</td><td><span class="code-tag">Category--feartour--</span></td></tr>
<tr><td>688</td><td><span class="code-tag">angerroom</span></td><td>اتاق خشم</td><td><span class="code-tag">Category--angerroom--</span></td></tr>
<tr><td>746</td><td><span class="code-tag">axethrowing</span></td><td>پرتاب تبر</td><td><span class="code-tag">Category--axethrowing--</span></td></tr>
<tr><td>794</td><td><span class="code-tag">cafecinema</span></td><td>کافه سینما</td><td><span class="code-tag">Category--cafecinema--</span></td></tr>
<tr><td>867</td><td><span class="code-tag">pottery</span></td><td>تجربه سفالگری</td><td><span class="code-tag">Category--pottery--</span></td></tr>
<tr><td>1419</td><td><span class="code-tag">karaoke</span></td><td>کارائوکه</td><td><span class="code-tag">Category--karaoke--</span></td></tr>
<tr><td>3375</td><td><span class="code-tag">lasertag</span></td><td>لیزرتگ</td><td><span class="code-tag">Category--lasertag--</span></td></tr>
<tr><td>3438</td><td><span class="code-tag">boardgame</span></td><td>بردگیم</td><td><span class="code-tag">Category--boardgame--</span></td></tr>
<tr><td>3487</td><td><span class="code-tag">class</span></td><td>کلاس آموزشی</td><td><span class="code-tag">Category--class--</span></td></tr>
<tr><td>3542</td><td><span class="code-tag">travel</span></td><td>سفر گروهی</td><td><span class="code-tag">Category--travel--</span></td></tr>
<tr><td>3629</td><td><span class="code-tag">tour</span></td><td>تور</td><td><span class="code-tag">Category--tour--</span></td></tr>
<tr><td>3803</td><td><span class="code-tag">event</span></td><td>رویداد / جلسه</td><td><span class="code-tag">Category--event--</span></td></tr>
<tr><td>house</td><td><span class="code-tag">hauntedhouse</span></td><td>هانتد هاوس</td><td><span class="code-tag">Category--hauntedhouse--</span></td></tr>
</tbody>
</table>
</div>
<h3 style="margin: 24px 0 10px; font-size: 15px; color: var(--primary);">ب) ساختار برچسب‌های متادیتا، موقعیت و ویژگی‌های رفتاری</h3>
<div class="table-container">
<table>
<thead>
<tr>
<th>بُعد تحلیلی</th>
<th>منبع داده در دیتابیس</th>
<th>الگوی برچسب</th>
<th>مثال خروجی</th>
</tr>
</thead>
<tbody>
<tr>
<td>جنسیت کاربر</td>
<td><span class="code-tag">users.gender</span></td>
<td><span class="code-tag">Gender--[male|female|unknown]--</span></td>
<td><span class="code-tag">Gender--female--</span></td>
</tr>
<tr>
<td>شهر بازی</td>
<td><span class="code-tag">games.city</span></td>
<td><span class="code-tag">City--[city_name]--</span></td>
<td><span class="code-tag">City--تهران--</span>, <span class="code-tag">City--کرج--</span></td>
</tr>
<tr>
<td>منطقه / محله</td>
<td><span class="code-tag">games.area</span></td>
<td><span class="code-tag">Area--[area_name]--</span></td>
<td><span class="code-tag">Area--صادقیه--</span></td>
</tr>
<tr>
<td>ژانرهای بازی</td>
<td><span class="code-tag">games.genres</span> (آرایه)</td>
<td><span class="code-tag">Genre--[genre_title]--</span></td>
<td><span class="code-tag">Genre--روحی-جن‌گیری--</span></td>
</tr>
<tr>
<td>سبک بازی</td>
<td><span class="code-tag">games.style</span></td>
<td><span class="code-tag">Style--[style_title]--</span></td>
<td><span class="code-tag">Style--تعاملی--</span></td>
</tr>
<tr>
<td>مناسب برای</td>
<td><span class="code-tag">games.suitablefor</span></td>
<td><span class="code-tag">Suitable--[target]--</span></td>
<td><span class="code-tag">Suitable--خانوادگی--</span></td>
</tr>
<tr>
<td>تعداد نفرات سانس</td>
<td><span class="code-tag">orders.person_count</span></td>
<td><span class="code-tag">Headcount--[count]--</span></td>
<td><span class="code-tag">Headcount--6--</span></td>
</tr>
<tr>
<td>متغیرهای تحلیلی کمپین</td>
<td>پارامترهای URL: <span class="code-tag">cfc</span> و <span class="code-tag">gen</span></td>
<td><span class="code-tag">CFC--[val]--</span> و <span class="code-tag">GEN--[val]--</span></td>
<td><span class="code-tag">CFC--summer_ads--</span></td>
</tr>
<tr>
<td>روش پرداخت</td>
<td><span class="code-tag">orders.payment_method</span></td>
<td><span class="code-tag">Payment--[type]--</span></td>
<td><span class="code-tag">Payment--snappay--</span></td>
</tr>
</tbody>
</table>
</div>
</div>
<!-- 5. Historical Backfill Architecture -->
<div class="card">
<div class="card-title">
<span class="icon">۵</span>
<span>معماری و پایپ‌لاین انتقال دیتای گذشته (Backfill Pipeline)</span>
</div>
<p>
به دلیل آنکه در حال حاضر تنها حدود ۱۳ هزار کاربر در دوباره ثبت شده و تاریخچه اکیپا بسیار فراتر از این رقم است، اسکریپت بک‌فیل ایزوله باید نوشته و به صورت کنترل‌شده اجرا شود:
</p>
<div class="grid-2" style="margin-top: 16px;">
<div class="perspective-box" style="border-right: 4px solid var(--primary);">
<h4>🎯 اولویت ۱: کل تاریخچه پلتفرم (Full History)</h4>
<p>استخراج تمام کاربران یکتایی که تاکنون حداقل یک رزرو یا تراکنش موفق داشته‌اند به همراه جزئیات سفارش‌ها و برچسب‌های متناظر از روز نخست فعالیت اکیپا.</p>
</div>
<div class="perspective-box" style="border-right: 4px solid var(--secondary);">
<h4>⚡ اولویت ۲: همگام‌سازی سریع از ۱۴۰۴/۰۱/۰۱</h4>
<p>در صورتی که حجم کل تاریخچه موجب کندی شود، فاز نخست باید کلیه سفارش‌ها و کاربران از ۱۴۰۴/۰۱/۰۱ تا به امروز را فوراً سینک کند تا کمپین‌های نوروز و بهار فعال شوند.</p>
</div>
</div>
<h3 style="margin: 20px 0 10px; font-size: 15px; color: var(--primary);">قوانین نرخ ترافیک و صف اجرایی (Rate-Limiting & Queue)</h3>
<ul>
<li><strong>حداکثر نرخ ریکوئست:</strong> حداکثر ۵ تا ۱۰ ریکوئست در ثانیه با مکانیزم تأخیر (Throttling) جهت جلوگیری از بروز خطای <span class="code-tag">429 Too Many Requests</span> از سمت کلودفلر یا وب‌سرور دوباره.</li>
<li><strong>صف پردازشی (Batch Processing):</strong> واکشی سفارش‌ها در دسته‌های ۵۰۰تایی (Chunk Size: 500) با مکانیسم Keyset Pagination بر اساس <span class="code-tag">order.id</span> برای جلوگیری از پر شدن RAM سرور Node.js.</li>
<li><strong>لاگ‌گذاری خطایابی:</strong> ذخیره شناسه‌های ناموفق در یک فایل یا جدول <span class="code-tag">dobare_sync_logs</span> جهت تلاش مجدد (Auto-Retry).</li>
</ul>
<div class="code-block">
<pre>// اسکریپت نمونه بک‌فیل با کنترل 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)); // ۱ ثانیه استراحت بین بچ‌ها
}
}</pre>
</div>
</div>
<!-- 6. Technical Risks -->
<div class="card">
<div class="card-title">
<span class="icon">۶</span>
<span>ریسک‌های فنی و راهکارهای پیشگیرانه (Risk Management)</span>
</div>
<div class="risk-item danger">
<strong>⚠️ سقف تعداد برچسب‌ها در دوباره (Max Labels Limit):</strong>
طبق مستندات دوباره، حداکثر تعداد برچسب ارسالی در هر درخواست ۱۰۰ عدد است (<span class="code-tag">maxItems: 100</span>). کد نباید تگ‌های تکراری یا نال ارسال کند. فیلتر کردن آرایه با <span class="code-tag">Array.from(new Set(labels)).slice(0, 50)</span> الزامی است.
</div>
<div class="risk-item">
<strong>⚠️ اعتبارسنجی فرمت شماره تلفن (Phone Regex):</strong>
دوباره فقط فرمت معتبر ایران را می‌پذیرد: <span class="code-tag">^((0098|098|\+98|98)?(?:\+?98)*)(0?9\d{9})$</span>. شماره‌هایی که این فرمت را ندارند قبل از ارسال نرمالایز شوند (<span class="code-tag">09xxxxxxxxx</span>).
</div>
<div class="risk-item">
<strong>⚠️ عدم پشتیبانی دوباره از به‌روزرسانی معکوس مبالغ:</strong>
چنانچه سفارشی قبلاً در دوباره با مبلغ ناقص ثبت شده، ثبت مجدد آن با همان <span class="code-tag">source_order_id</span> باید بررسی شود که آیا دوباره سفارش را Update می‌کند یا ارور تکراری می‌دهد. این مورد در تست نمونه اولیه (فاز ۲) باید راستی‌آزمایی شود.
</div>
</div>
<!-- 7. Estimation -->
<div class="card">
<div class="card-title">
<span class="icon">۷</span>
<span>تخمین زمان پیاده‌سازی هوش مصنوعی (AI Effort Estimation)</span>
</div>
<p>بر اساس ساختار تیم موجود (<strong>۱ برنامه‌نویس بک‌اند Node.js</strong>):</p>
<div class="estimate-card">
<div class="estimate-stat">
<span>۱. اصلاح لاجیک محاسبه مبالغ (Gross / Paid / Discount) در وب‌هوک و ماژول دوباره</span>
<span>۰.۵ نفر-روز (۴ ساعت)</span>
</div>
<div class="estimate-stat">
<span>۲. پیاده‌سازی ماژول ساخت تگ‌های داینامیک (دسته‌بندی، سطح ترس، لوکیشن، متادیتا)</span>
<span>۱.۰ نفر-روز (۸ ساعت)</span>
</div>
<div class="estimate-stat">
<span>۳. توسعه و تست پایپ‌لاین بک‌فیل دسته‌ای (Batch Script + Rate-Limiting + Queue)</span>
<span>۱.۰ نفر-روز (۸ ساعت)</span>
</div>
<div class="estimate-stat">
<span>۴. اجرای تست‌های End-to-End در استیجینگ و راستی‌آزمایی با پنل دوباره</span>
<span>۰.۵ نفر-روز (۴ ساعت)</span>
</div>
<div class="estimate-stat">
<span>جمع کل زمان تخمینی توسعه و تحویل (Backend Developer):</span>
<span>۳.۰ نفر-روز کاری (۲۴ ساعت کاری)</span>
</div>
</div>
</div>
<!-- 8. Acceptance Checklist -->
<div class="card">
<div class="card-title">
<span class="icon">۸</span>
<span>چک‌لیست پذیرش و تحویل (Definition of Done)</span>
</div>
<ol>
<li>یک سفارش جدید در استیجینگ ثبت شود و ستون «مبلغ سفارش» در داشبورد دوباره برابر با ارزش کل خرید (ناخالص) نمایش داده شود.</li>
<li>مبلغ تخفیف به درستی در جزییات سفارش پنل دوباره ثبت گردد.</li>
<li>در پروفایل کاربر خریدار در دوباره، برچسب‌های متناظر با شهر، سطح ترس، ژانر و تعداد نفرات ایجاد و الصاق شده باشند.</li>
<li>اسکریپت بک‌فیل بدون خطا و بدون بلاک شدن توسط Rate-Limit دوباره تا انتهای بازه اجرا شود.</li>
<li>تعداد کل کاربران ثبت‌شده در دوباره از ۱۳ هزار فعلی به آمار واقعی کاربران پلتفرم ارتقا یابد.</li>
</ol>
</div>
</div>
</body>
</html>