735 lines
32 KiB
HTML
Executable file
735 lines
32 KiB
HTML
Executable file
<!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>
|