ARCH_NCاستودیو معماری دیجیتال
سایت فروشگاهی

آموزش وب‌سرویس هلو (TncHoloo): همگام‌سازی امن موجودی و قیمت با سایت

همگام‌سازی سایت با هلو از راه وب‌سرویس TncHoloo یعنی سایت هر چند دقیقه کالاها را از هلو بخواند، با کد کالا جفت کند و فقط موجودی و قیمت را به‌روز کند؛ هیچ کالایی نسازد و جایی که داده مشکوک است، دست نگه دارد. این راهنما همان روشی است که در یک فروشگاه واقعی با چند ده هزار کالا روی هاست اشتراکی پیاده کردیم، با همه‌ی دام‌هایی که سر راهمان بود. اگر دنبال نمای کلی و غیرفنی هستید، اول اتصال سایت به نرم‌افزار هلو را بخوانید.

وب‌سرویس هلو چه چیزی در اختیار سایت می‌گذارد؟

وب‌سرویس TncHoloo یک API به زبان جاوا است که روی کامپیوتر یا سرور هلو اجرا می‌شود و معمولاً روی پورت ۵۰۰۰ و مسیر /TncHoloo/api در دسترس است. صفحه‌ی Swagger آن (/swagger-ui.html) فهرست درخواست‌ها را نشان می‌دهد؛ اگر این صفحه از سرور سایت باز شود، یعنی مسیر شبکه درست است.

درخواستکارنکته
POST /Loginورود و گرفتن توکنرمز به‌صورت Base64 فرستاده می‌شود
GET /Product/countتعداد کل کالاهافیلد totalCount
GET /Product/{page}/{size}یک صفحه از کالاهاشماره‌ی صفحه از ۱ شروع می‌شود

هر کالا چند فیلد مهم دارد: Code (کد کالا)، Name، Few (موجودی)، SellPrice (قیمت فروش به ریال)، IsActive و service که کالای خدماتی را مشخص می‌کند. این وب‌سرویس فیلتر تاریخ یا فهرست تغییرات ندارد؛ یعنی هر دور همگام‌سازی باید همه‌ی کالاها را بخواند.

پیش‌نیاز شبکه: آیا سرور سایت به هلو می‌رسد؟

بیشتر وقتی که در این پروژه‌ها هدر می‌رود، پیش از نوشتن حتی یک خط کد است. هاست‌های اشتراکی معمولاً اتصال خروجی به پورت‌های غیرمعمول را می‌بندند. پورت‌هایی مثل ۸۰ و ۴۴۳ باز است، ولی ۵۰۰۰ نه. از پشتیبانی هاست بخواهید اتصال خروجی TCP به آی‌پی و پورت هلو را باز کند، و بعد از ترمینال cPanel این را امتحان کنید:

curl -s -i --max-time 15 http://HOLOO_IP:5000/TncHoloo/api/swagger-ui.html | head
نتیجهمعنی
صفحه‌ی Swaggerشبکه درست است؛ برو سراغ کد
صفحه‌ی HTML مسدودسازی یا جواب خالییک فایروال در مسیر است
Connection refusedپورت بسته است یا وب‌سرویس هلو روشن نیست
Timeoutهاست اتصال خروجی را می‌بندد یا کامپیوتر هلو خاموش است

طرف هلو را هم امن کنید: پورت ۵۰۰۰ را فقط برای آی‌پی سرور سایت باز بگذارید و برای سایت یک کاربر جدا در هلو با رمز قوی و کمترین دسترسی لازم بسازید.

گام ۱: ورود و مدیریت توکن

ورود با فرم application/x-www-form-urlencoded و سه فیلد انجام می‌شود: نام پایگاه‌داده، نام کاربری و رمز. نکته‌ای که بارها باعث «رمز اشتباه است» شد: در API رمز باید Base64 رمز اصلی باشد، ولی در فرم تنظیمات پنل سایت، کاربر رمز معمولی را وارد می‌کند و تبدیل در کد انجام می‌شود. این دو را با هم قاطی نکنید. هدر درخواست ورود Authorization: 1 است.

// holoo.js — فقط روی سرور؛ رمز از تنظیمات خصوصی خوانده می‌شود، نه از کد
const BASE = process.env.HOLOO_URL; // http://HOLOO_IP:5000/TncHoloo/api
let token = null, expMs = 0;

async function login() {
  const body = new URLSearchParams({
    dbname: process.env.HOLOO_DB,
    username: process.env.HOLOO_USER,
    userpass: Buffer.from(process.env.HOLOO_PASS, 'utf8').toString('base64'),
  });
  const r = await fetch(BASE + '/Login', {
    method: 'POST', headers: { Authorization: '1' }, body,
    signal: AbortSignal.timeout(15000),
  });
  const j = await r.json();
  if (!j.Login || !j.Login.Token) throw new Error('ورود به هلو ناموفق بود');
  token = j.Login.Token;
  // توکن JWT است؛ زمان انقضا را از خودش بخوان (پیش‌فرض حدود ۳۰ دقیقه)
  const payload = JSON.parse(Buffer.from(token.split('.')[1], 'base64url'));
  expMs = payload.exp * 1000;
}

درخواست‌های بعدی توکن را در هدر Authorization می‌فرستند. قالب دقیق هدر را در Swagger نسخه‌ی خودتان چک کنید. اگر جواب ۴۰۱ یا ۴۰۳ آمد، فقط یک بار دوباره وارد شوید و درخواست را تکرار کنید؛ حلقه‌ی بی‌پایان ورود نسازید.

گام ۲: خواندن همه‌ی کالاها، صفحه‌به‌صفحه

async function get(path) {
  if (!token || Date.now() > expMs - 60000) await login();
  const call = () => fetch(BASE + path, {
    headers: { Authorization: token }, signal: AbortSignal.timeout(30000),
  });
  let r = await call();
  if (r.status === 401 || r.status === 403) { await login(); r = await call(); }
  const text = await r.text();
  try { return JSON.parse(text); }
  catch { throw new Error('پاسخ نامعتبر از هلو: ' + text.slice(0, 160)); }
}

async function readAllProducts(size = 500) {
  const { totalCount } = await get('/Product/count');
  const items = [];
  for (let page = 1; items.length < totalCount; page++) {
    const body = await get(`/Product/${page}/${size}`);
    const list = body.product || body.Product || body.products;
    if (!Array.isArray(list)) throw new Error('هلو فهرست کالا را در قالب ناشناخته برگرداند');
    if (list.length === 0) break;
    items.push(...list);
  }
  return items;
}
  • صفحه از ۱ شروع می‌شود. درخواست صفحه‌ی صفر در بعضی نسخه‌ها جواب نمی‌دهد و تا تمام شدن زمان معطل می‌ماند.
  • کلید فهرست ممکن است فرق کند. product، Product یا products؛ هر سه را بپذیرید.
  • متن خطای خود هلو را نگه دارید. ۱۶۰ کاراکتر اول جواب برای عیب‌یابی طلاست.
  • زمان را حساب کنید. در فروشگاه ما با چند ده هزار کالا، هر دور خواندن کامل حدود چهار دقیقه طول کشید.

گام ۳: تبدیل داده‌ی هلو به داده‌ی سایت

const toSite = h => ({
  code: String(h.Code ?? '').trim(),
  stock: Math.max(0, Math.floor(Number(h.Few) || 0)), // موجودی اعشاری رو به پایین
  priceToman: Math.round(Number(h.SellPrice) / 10),    // هلو ریال می‌دهد
  active: h.IsActive !== false,
  isService: Boolean(h.service),                       // کالای خدماتی کنار گذاشته می‌شود
});

قانون‌های جفت کردن کالا را سخت‌گیرانه بنویسید. هر چیزی که مطمئن نیستید، رد و گزارش شود، نه به‌روزرسانی:

حالتکار درست
کالای سایت کد هلو دارد و یک کالای هلو با همان کد هستبه‌روزرسانی موجودی و قیمت
کد خالی یا صفررد و گزارش
یک کد روی چند کالای سایترد و گزارش
چند کالای هلو با یک کدرد و گزارش
کالای هلو که در سایت نیستهیچ؛ همگام‌سازی کالا نمی‌سازد
کالایی که قیمتش در سایت دستی تعیین شدهفقط موجودی به‌روز شود، قیمت نه

یک نکته‌ی ظریف: سفارش‌هایی که در سایت پرداخت شده‌اند ولی هنوز در هلو ثبت نشده‌اند را از موجودی هلو کم کنید. وگرنه موجودی بعد از هر همگام‌سازی دوباره بالا می‌پرد و کالای فروخته‌شده باز فروشی می‌شود.

گام ۴: قفل‌های ایمنی؛ همگام‌سازی که خراب نمی‌کند

خطرناک‌ترین لحظه وقتی است که هلو داده‌ی اشتباه برمی‌گرداند، مثلاً از پایگاه‌داده‌ی یک سال دیگر یا نیمه‌کاره. همگام‌سازی باید در این حالت بسته شکست بخورد، یعنی هیچ چیز را تغییر ندهد:

function safetyCheck({ matched, priceChanges, holooCount, lastHolooCount }) {
  if (priceChanges > matched / 2)
    return 'بیش از نیمی از قیمت‌ها یک‌جا عوض شده‌اند';
  if (lastHolooCount && holooCount < lastHolooCount * 0.9)
    return 'تعداد کالاهای هلو بیش از ۱۰٪ کم شده است';
  return null; // ادامه بده
}
  • توقف برای ایمنی: اگر بیش از نیمی از قیمت‌ها یک‌جا عوض شد یا تعداد کالاهای هلو بیش از ۱۰٪ افت کرد، هیچ چیز اعمال نشود و پیام «برای ایمنی متوقف شد» نمایش داده شود. فقط مدیر ارشد می‌تواند اجرای دستی را اجبار کند.
  • قیمت مشکوک: تغییر بیش از سه برابر یا کمتر از یک‌سوم اعمال شود ولی برای حسابدار علامت بخورد.
  • اول همه را بخوان، بعد یک‌جا بنویس: تغییرها در یک تراکنش با مقدار قبلی مورد انتظار اعمال شوند تا اجرای نیمه‌کاره هیچ چیزی را عوض نکند.
  • نسخه‌ی پشتیبان: پیش از هر اجرایی که چیزی را تغییر می‌دهد، مقادیر قبلی ذخیره شوند (مثلاً ۲۰ نسخه‌ی آخر).
  • گزارش تغییرات: هر تغییر با مقدار قبلی، مقدار جدید و شناسه‌ی اجرا ثبت شود؛ صفحه‌ی گزارش برای حسابدار با دکمه‌ی «بررسی شد» و خروجی CSV.
  • یک قفل مشترک: اگر جز وب‌سرویس، ورود فایلی هم دارید، هر دو یک قفل داشته باشند تا هم‌زمان اجرا نشوند.

گام ۵: دام هاست اشتراکی؛ برنامه‌ای که وسط کار می‌خوابد

این دام را کمتر جایی نوشته‌اند. روی cPanel، برنامه‌های Node.js با Passenger اجرا می‌شوند و Passenger برنامه‌ای را که حدود پنج دقیقه درخواست وب نگرفته متوقف می‌کند. یک دور همگام‌سازی چهار دقیقه طول می‌کشد؛ پس در فروشگاهی که شب بازدید ندارد، تقریباً یک در میان اجراها نیمه‌کاره کشته می‌شدند. زمان‌سنج داخل برنامه هم وقتی برنامه خوابیده، اصلاً اجرا نمی‌شود.

راه‌حلی که جواب داد سه بخش دارد:

  1. Cron در cPanel: هر پنج دقیقه یک آدرس محافظت‌شده با کلید مخفی را صدا می‌زند که فقط می‌پرسد «وقت اجرا رسیده؟». همین درخواست برنامه را هم بیدار نگه می‌دارد.
  2. بیدار نگه داشتن حین اجرا: تا وقتی یک دور در جریان است، برنامه هر دقیقه آدرس سلامت عمومی خودش را صدا می‌زند.
  3. ثبت دلیل توقف: روی سیگنال SIGTERM یک پیام روشن در گزارش بنویسید. اگر بعد از راه‌اندازی دوباره، اجرایی با وضعیت «در حال اجرا» مانده بود، آن را «قطع‌شده» علامت بزنید.
*/5 * * * * curl -s "https://example.com/cron?key=SECRET_KEY" > /dev/null

فاصله‌ی پیش‌فرض یک ساعت مناسب است و کمتر از ۱۵ دقیقه را اجازه ندهید. هزینه‌ی اصلی خواندن از هلو است، نه سایت. آدرس‌هایی که پنل برای دیدن وضعیت اجرا مرتب صدا می‌زند را هم از محدودیت نرخ درخواست سایت مستثنا کنید؛ وگرنه خود پنل خطای ۴۲۹ می‌گیرد.

عیب‌یابی: هر پیام خطا چه می‌گوید؟

پیاممعنیکار
Connection refused یا Timeoutپورت بسته، هلو خاموش یا هاست اتصال خروجی را می‌بنددآزمون curl بالا؛ باز کردن پورت؛ چک کامپیوتر هلو
ورود ناموفقنام کاربری، رمز یا نام پایگاه‌داده اشتباه استرمز معمولی را دوباره در پنل وارد کنید، نه Base64 آن
فهرست کالا در قالب ناشناختهجواب موفق بوده ولی فهرستی ندارد: هلو یا پایگاه‌داده در دسترس نیست، صفحه‌ی مسدودسازی، نسخه‌ی تغییرکرده، یا ورود هم‌زمان دو برنامه با یک کاربرمتن جواب هلو را بخوانید؛ مطمئن شوید فقط یک نسخه از سایت همگام‌سازی می‌کند
برای ایمنی متوقف شدتغییر خیلی بزرگ؛ شاید پایگاه‌داده‌ی اشتباههلو را بررسی کنید و بعد اجرای دستی را اجبار کنید

یک مورد واقعی: سایتی که به سرور جدید منتقل شده بود، روی سرور قبلی هم تنظیمات هلو و همگام‌سازی خودکار را داشت. دو نسخه با یک کاربر وارد هلو می‌شدند و یکدیگر را بیرون می‌انداختند. همگام‌سازی خودکار را روی هر نسخه جز سایت اصلی خاموش کنید.

پیش از روشن کردن: پیش‌نمایش و تحویل

  • اجرای پیش‌نمایش: اولین اجرا فقط بخواند و گزارش بدهد: چند کالا جفت شد، چند تا جفت نشد، چند تغییر و چند مورد مشکوک. صاحب فروشگاه تأیید کند، بعد اعمال خودکار روشن شود.
  • آزمون با هلوی جعلی: یک سرور کوچک که مثل هلو جواب می‌دهد، برای آزمودن ورود، صفحه‌بندی، قفل‌های ایمنی، کدهای تکراری، قیمت دستی، اجرای قطع‌شده و کلید Cron.
  • رمزها: رمز هلو فقط در فایل تنظیمات خصوصی سرور بماند؛ نه در کد، نه در گزارش، نه در گفتگو. بعد از تحویل پروژه رمز کاربر هلو را عوض کنید.
  • راهنمای فارسی برای نگهدارنده: جدول قانون‌ها، جای گزارش‌ها، مرحله‌ی یک‌باره‌ی Cron و جدول خطاها.

پرسش‌های رایج

وب‌سرویس هلو قیمت را به ریال می‌دهد یا تومان؟

فیلد SellPrice به ریال است. برای نمایش به تومان در سایت، بر ۱۰ تقسیم کنید و تبدیل را فقط در یک جای کد انجام دهید.

چرا اتصال به هلو از روی هاست برقرار نمی‌شود؟

معمولاً چون هاست اشتراکی اتصال خروجی به پورت ۵۰۰۰ را بسته است. با دستور curl از ترمینال cPanel آزمایش کنید و اگر صفحه‌ی Swagger باز نشد، از پشتیبانی هاست بخواهید پورت را باز کند.

هر چند وقت یک بار سایت را با هلو همگام کنیم؟

هر یک ساعت برای بیشتر فروشگاه‌ها کافی است و کمتر از ۱۵ دقیقه توصیه نمی‌شود، چون وب‌سرویس فهرست تغییرات ندارد و هر دور همه‌ی کالاها را می‌خواند.

چرا همگام‌سازی روی cPanel نیمه‌کاره می‌ماند؟

چون Passenger برنامه‌ی Node.js را بعد از چند دقیقه بی‌درخواستی متوقف می‌کند. با Cron هر پنج دقیقه و صدا زدن آدرس سلامت حین اجرا، برنامه بیدار می‌ماند.

همگام‌سازی کالای جدید هم در سایت می‌سازد؟

در روش ما نه. فقط کالاهایی که در سایت کد هلو دارند به‌روز می‌شوند. عکس و توضیح کالا در پنل سایت وارد می‌شود و ساختن خودکار کالا خطای زیادی دارد.

گام بعد

این اتصال را برای فروشگاه‌های اختصاصی با بک‌اند Node.js می‌سازیم؛ صفحه‌ی طراحی سایت فروشگاهی اختصاصی را ببینید یا در تلگرام به @ARCH_NC پیام بدهید. ترتیب کامل راه‌اندازی فروشگاه هم در چک‌لیست راه‌اندازی فروشگاه اینترنتی آمده است.

خدمت مرتبط: طراحی سایت فروشگاهی اختصاصی