۷. استراتژی سینک (Weak Signal → Full Resync)

۷.۱ هدف این بخش

هدف استراتژی سینک این است که قیمت، تخفیف، موجودی و وضعیت فعال/غیرفعال بین POS و سامانه فروش آنلاین اسنپ! مارکت تا حد ممکن هم‌تراز بماند. در صنعت گروسری، اختلاف موجودی (Inventory Inaccuracy / Drift) یک واقعیت طبیعی است؛ پس هدف این است که ریسک و اثر Drift را کنترل کنیم تا:

• False Positive (کالا موجود نشان داده شود ولی نباشد) کم شود → کاهش NFC/Reject
• False Negative (کالا موجود باشد ولی ناموجود نمایش داده شود) کم شود → جلوگیری از از دست رفتن فروش
• Price Drift کم شود → کاهش اختلاف قیمت، کاهش تماس و تجربه بهتر مشتری

۷.۲ تعریف‌ها (برای پیاده‌سازی مشترک)

۷.۳ سیاست Batch و ظرفیت عملیاتی

برای درخواست‌های Bulk (price/stock/productDetails/title/active) پیشنهاد می‌شود اندازه Batch را در بازه ۱۰۰ تا ۵۰۰ تنظیم کنید. انتخاب عدد دقیق به کیفیت شبکه، توان POS، و نرخ خطا بستگی دارد.

چه چیزهایی را Batch کنید؟

• Stock updates (موجودی)
• Price updates (قیمت)
• ProductDetails updates (قیمت+تخفیف)
• Active state updates
• Title updates (اگر نیاز دارید)

۷.۴ Weak Signal: چه زمانی باید به Drift شک کنید؟

Weak Signal یک “الگوریتم داخلی POS” است، نه یک endpoint در پلتفرم. شما باید مجموعه‌ای از شاخص‌ها را مانیتور کنید و اگر هر کدام از آستانه عبور کرد، Resync را فعال کنید.

سیگنال‌های رایج و پیشنهاد آستانه

۷.۵ طراحی پیشنهادی (Developer-grade) برای سینک

۷.۵.۱ Sync Queue (الزام عملی)

پیشنهاد می‌شود تمام تغییرات در POS ابتدا وارد یک صف (Queue) شوند و ارسال به پلتفرم توسط یک Sync Worker انجام شود. این کار باعث می‌شود قطع شبکه یا restart سرویس، رویدادها را از بین نبرد.

• صف می‌تواند DB table، Kafka، RabbitMQ یا هر سازوکار پایدار باشد.
• کلید Idempotency داخلی: vendorCode + barcode + field + updated_at
• قابلیت dedup برای جلوگیری از ارسال‌های تکراری
• dead-letter برای آیتم‌های مشکل‌دار (data issue) تا اپراتور اصلاح کند

۷.۵.۲ اولویت‌بندی (Business-impact aware)

• موجودی مهم‌تر از قیمت است (اثر مستقیم روی NFC)
• SKUهای پرتراکنش یا پرفروش را با priority بالاتر Sync کنید
• در ساعات شلوغ، Batch را کمی کوچک‌تر و frequency را بالاتر کنید

۷.۶ اجرای Partial Resync (کم‌هزینه و سریع)

Partial Resync یعنی فقط SKUهایی که احتمال Drift دارند را مجدد Sync کنیم. این روش بهترین گزینه برای شرایطی است که Weak Signal خفیف است.

ورودی Partial Resync از کجا می‌آید؟

• SKUهای تغییر یافته در ۳۰–۶۰ دقیقه اخیر (از log داخلی POS)
• SKUهای fail شده در Bulk (failedItems)
• SKUهایی که اپراتور گزارش کرده (مثلاً OOS پر تکرار)

الگوی پیشنهادی اجرای Partial Resync

1) candidate_barcodes = changed_recently ∪ failed_items ∪ manual_flags
2) برای هر barcode:
   - قیمت/تخفیف را با productDetails یا price به‌روز کن
   - موجودی را با stock به‌روز کن
   - اگر کالا نباید فروش برود: active=false
3) نتیجه را لاگ کن (success/failedItems) و فقط failها را اصلاح و retry کن

۷.۷ اجرای Full Resync (کنترل‌شده و مرحله‌ای)

Full Resync زمانی لازم است که Drift شدید است یا Live Sync برای مدتی از کار افتاده، یا نرخ خطا/lag به سطحی رسیده که Partial Resync پاسخ نمی‌دهد.

گام‌های استاندارد Full Resync

1. لیست SKUهای فروشگاه را از POS استخراج کنید (source of truth شما)
2. Batch بندی ۱۰۰ تا ۵۰۰ تایی
3. برای هر Batch:
   • ارسال price یا productDetails (در صورت نیاز)
   • ارسال stock
   • در صورت نیاز active/title
4. ثبت نتیجه و جمع‌آوری failedItems
5. Retry فقط برای failedItems و فقط پس از اصلاح

نمونه Bulk ارسال موجودی (Batch 250)

POST https://api-proxy.snapp.express/va/v1/product/stock
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vendorCode": "VENDOR_CODE",
  "stocks": [
    { "barcode": "111", "stock": 10 },
    { "barcode": "112", "stock": 0 }
    // ... up to 250 items
  ]
}

نمونه Bulk ارسال قیمت (Batch 250)

POST https://api-proxy.snapp.express/va/v1/product/price
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vendorCode": "VENDOR_CODE",
  "prices": [
    { "barcode": "111", "price": 35000 },
    { "barcode": "112", "price": 18000 }
    // ... up to 250 items
  ]
}

۷.۸ کنترل صحت (Verification) بدون هزینه بالا

برای بررسی اینکه پلتفرم چه داده‌ای از یک SKU ثبت کرده است، می‌توانید در سناریوهای دیباگ از endpoint استعلام استفاده کنید. این مرحله باید محدود و هدفمند باشد (برای چند SKU مشکوک)، نه برای همه SKUها.

استعلام یک یا چند SKU (get-info)

POST https://api-proxy.snapp.express/va/v1/product/get-info
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "vendorCode": "VENDOR_CODE",
  "products": [
    { "barcode": "1234" },
    { "barcode": "5678" }
  ]
}

۷.۹ Runbook عملیاتی (برای تیم‌های Operations و Vendor)

اگر NFC/Reject به دلیل OOS بالا رفت…

1. بررسی کنید Live Sync موجودی فعال است (Sync Lag)
2. failedItems را از آخرین batchها استخراج کنید
3. Partial Resync روی SKUهای پرتکرار انجام دهید
4. اگر مشکل ادامه داشت: Full Resync مرحله‌ای
5. در نهایت، فرآیند داخلی فروشگاه را بازبینی کنید (ورودی بار، ضایعات، فروش خارج از POS)

اگر قیمت‌ها drift دارند…

1. بررسی کنید قیمت در POS واقعاً به‌روزرسانی شده یا فقط در UI تغییر کرده
2. price/productDetails را برای SKUهای مشکوک resend کنید
3. اگر تکرار شد: logging دقیق (barcode, pos_price, sent_price, response)

۷.۱۰ KPIهای پیشنهادی برای داشبورد (Business + Tech)

۷.۱۱ نمونه گزارش اجرای Resync (برای لاگ و Audit)

{
  "vendorCode": "VENDOR_CODE",
  "syncType": "partial",
  "trigger": "weak_signal: failed_items_spike",
  "startedAt": "2025-12-16T08:30:00Z",
  "batchSize": 250,
  "itemsPlanned": 740,
  "itemsSent": 740,
  "failedItems": 12,
  "retries": 1,
  "durationSec": 48,
  "result": "success_with_repair"
}

پیشنهاد می‌شود این گزارش حداقل ۷ تا ۳۰ روز نگهداری شود تا برای تحلیل‌های عملیاتی و رفع ریشه‌ای Drift مفید باشد.

۷.۱۲ نتیجه‌گیری

Weak Signal → Resync یک الگوی استاندارد برای کاهش ریسک در گروسری آنلاین است. Live Sync، Partial Resync و Full Resync باید در کنار هم و با کنترل بار اجرا شوند. اجرای درست این الگو باعث کاهش NFC، کاهش اختلاف‌ها و پایداری سیستم در مقیاس سازمانی می‌شود.