UnoPayv1.0.0
  1. خانه
  2. لاگ و مشاهده‌پذیری

مفاهیم پایه

لاگ و مشاهده‌پذیری

لاگر آرگومان دوم سازنده است و کاملاً اختیاری. UnoPay هرگز خودش console را صدا نمی‌زند.

logger.ts ts 
import pino from 'pino';
import { UnoPay, ZarinpalAdapter } from 'unopay';

const log = pino({ name: 'payments' });

const unopay = new UnoPay(
  { zarinpal: new ZarinpalAdapter({ merchantId: process.env.ZARINPAL_MERCHANT_ID! }) },
  {
    // Pino takes (msg, obj); PaymentLogger hands you (event, context)
    info: (event, ctx) => log.info(ctx ?? {}, event),
    error: (event, ctx) => log.error(ctx ?? {}, event),
    warn: (event, ctx) => log.warn(ctx ?? {}, event),
    debug: (event, ctx) => log.debug(ctx ?? {}, event),
  },
);
قبل از رسیدن به مقصد لاگ پاک‌سازی کنید

payment_started و provider_request_sent هر دو کل PaymentRequest را دریافت می‌کنند، یعنی metadata.mobile و هر چیز دیگری که آنجا گذاشته‌اید عیناً وارد لاگ شما می‌شود. Pino، Winston و آبجکت ساده همه کار می‌کنند — این مسئله سیاست است، نه تایپ.

پنج رویداد چرخه حیات

از کلاینت منتشر می‌شوند، نه از آداپتورها، پس در همه درگاه‌ها یکسان‌اند. از lib/data/sdk_api.ts رندر می‌شود.

رویدادسطحزمان وقوعزمینه
payment_startedinfoدر createPayment، پس از resolve شدن کلید درگاه و پیش از انتظار آداپتور.{ provider, request } — کل PaymentRequest شامل metadata.
provider_request_sentinfoدر createPayment، بلافاصله پس از payment_started و پیش از اجرای آداپتور. هیچ رویداد متناظری برای پاسخ موفق وجود ندارد.{ provider, request }
payment_failederrorدر createPayment، داخل بلوک catch. مقدار پرتاب‌شده در context پیچیده می‌شود.{ provider, error }
verification_completedinfoدر verifyCallback، پس از resolve شدن آداپتور. هم برای isSuccessful درست و هم نادرست رخ می‌دهد.{ provider, result }
verification_failederrorدر verifyCallback، داخل بلوک catch. فقط خطای پرتاب‌شده این را تولید می‌کند؛ پرداخت ردشده یعنی verification_completed با isSuccessful برابر false.{ provider, error }

warn و debug در اینترفیس PaymentLogger الزامی‌اند ولی UnoPay در ۱٫۰٫۰ هیچ‌کدام را صدا نمی‌زند. باز هم فراهمشان کنید؛ نسخه بعدی شروع به استفاده می‌کند.

در موفقیت دو رویداد پشت سر هم منتشر می‌شود

هیچ رویدادی برای پاسخ موفق وجود ندارد. لاگی که payment_started و provider_request_sent را نشان می‌دهد و بعد سکوت است، همان مسیر عادی موفقیت است — نبود payment_failed همان تأیید است.

لاگر روی کانفیگ آداپتور هیچ کاری نمی‌کند

ZarinpalConfig فیلد اختیاری logger را اعلام می‌کند و ZarinpalAdapter هرگز آن را نمی‌خواند. دادنش هیچ خروجی و هیچ خطایی تولید نمی‌کند — یک بی‌اثر خاموش. رویدادهای چرخه حیات فقط از لاگری منتشر می‌شوند که به سازنده UnoPay داده‌اید.