اعمال خودکار کوپن: چطور ۲۰۹ خط کد جای حدود ۱۳ هزار خط را گرفت

پیش از بلک‌فرایدی و سایبرماندی (BFCM) سال گذشته، در WooCommerce.com برای اعمال تخفیف‌های پلکانی از یک افزونه شخص ثالث استفاده می‌کردیم. افزونه کارش را انجام می‌داد، اما سربار زیادی به همراه داشت.

به همین دلیل، برای BFCM امکان جایگزین کردن آن را بررسی کردیم.

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

نتیجه نهایی: +209 خط کد اضافه شد، -12,888 خط حذف شد و ساختار کد ساده‌تر شد 🙂

این افزونه چه کار می‌کند

• یک کادر انتخاب با عنوان «اعمال خودکار کوپن» به صفحه ویرایش کوپن اضافه می‌کند
• هنگام محاسبه مجدد سبد خرید، کوپن‌هایی را که با _auto_apply = yes مشخص شده‌اند دریافت می‌کند. این فهرست ۱۲ ساعت کش می‌شود که برای فروشگاه‌های پرترافیکی مثل WooCommerce.com مفید است. سپس هر کوپن را با WC_Coupon::is_valid() اعتبارسنجی می‌کند و بدون نمایش پیام به مشتری، آن را اعمال یا حذف می‌کند
• دکمه حذف کوپن را هم در سبد خرید بلوکی و هم در صفحه پرداخت کلاسیک پنهان می‌کند تا تخفیف BFCM حتماً اعمال شود
• در پیاده‌سازی اختصاصی WooCommerce.com، از اعمال کوپن‌های BFCM روی تمدید اشتراک‌ها و برخی فرایندهای منتخب دیگر جلوگیری می‌کند

// Get all auto-apply coupon codes.
$auto_apply_codes = $this->get_auto_apply_coupon_codes();

foreach ( $auto_apply_codes as $code ) {
	$coupon = new WC_Coupon( $code );

	// Skip if coupon doesn't exist or isn't marked for auto-apply.
	if ( ! $coupon->get_id() || ! $coupon->get_auto_apply() ) {
		continue;
	}

	$is_valid = $coupon->is_valid();

	// Remove if applied but no longer valid.
	if ( $this->has_discount( $code ) && ! $is_valid ) {
		$this->remove_coupon( $code );
	}

	// Apply if not applied but now valid.
	if ( ! $this->has_discount( $code ) && $is_valid ) {
		$this->apply_coupon( $code );
	}
}

تنها بخش دشوار در پیاده‌سازی اختصاصی WooCommerce.com، جلوگیری از ورود مجدد به همان فرایند بود: اعمال کوپن، woocommerce_after_calculate_totals را دوباره اجرا می‌کند؛ بنابراین از پرچم static $running استفاده می‌کنیم تا این چرخه تکرار نشود. بدون آن، برنامه وارد بازگشت بی‌نهایت می‌شد؛ رفع اشکالش هم ماجرای جالبی بود 🙂

BFCM ۲۰۲۵

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

استفاده از کوپن‌های ووکامرس مزایای دیگری هم داشت؛ مثلاً پشتیبانی از چند ارز از همان ابتدا فراهم بود. آمار هم رضایت‌بخش بود: نرخ بازپرداخت از 13.1% به 7.8% کاهش یافت و وجه نقد خالص به‌ازای هر مشتری، نسبت به سال قبل +25% افزایش پیدا کرد.

اگر می‌خواهید همین گزارش تفکیکی را برای یک فروش ویژه در آینده تهیه کنید، از کوئری زیر استفاده کنید؛ نام کوپن‌ها را متناسب با نیازتان تغییر دهید یا حذف کنید:

SELECT
    oi.order_item_name                  AS coupon_code,
    COUNT(DISTINCT oi.order_id)         AS orders_with_coupon,
    COUNT(DISTINCT o.customer_id)       AS unique_customers
FROM wp_woocommerce_order_items oi
JOIN wp_wc_orders o ON oi.order_id = o.id
WHERE oi.order_item_type = 'coupon'
  AND oi.order_item_name IN ('sale-20%', 'sale-30%', 'sale-40%')
  AND o.date_created_gmt BETWEEN '2025-11-19 14:00:00' AND '2025-12-02 23:59:59'
  AND o.status IN ('wc-completed', 'wc-processing')
GROUP BY oi.order_item_name
ORDER BY orders_with_coupon DESC;

متن‌باز

یک پول‌ریکوئست پیش‌نویس در مخزن اصلی پروژه ثبت کردم: https://github.com/woocommerce/woocommerce/pull/61958. محدودیت‌های اختصاصی WooCommerce.com در آن وجود ندارند، اما سازوکار اصلی _auto_apply ، یعنی متادیتا به‌همراه اعمال یا حذف کوپن بدون نمایش پیام هنگام محاسبه مجدد سبد خرید، به نظر می‌رسد چیزی باشد که ووکامرس بتواند به‌صورت داخلی از آن پشتیبانی کند.

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

چه مواردی هنوز باقی مانده است

چند نکته هست که هنوز جای بهبود دارند:

• متادیتای _auto_apply در wp_postmeta ذخیره می‌شود. هنگام مهاجرت کوپن‌ها به HPOS، باید این بخش را دوباره بررسی کرد (کوئری موجود در WC_Cart::get_auto_apply_coupon_codes را ببینید)
• پیاده‌سازی اختصاصی WooCommerce.com
  • کد جاوااسکریپت برای پنهان کردن دکمه‌های حذف، نام کلاس‌های مشخصی از بلوک‌ها را هدف می‌گیرد. این نام‌ها ممکن است در نسخه‌های مختلف ووکامرس تغییر کنند
  • نام کوپن‌های BFCM با استفاده از یک فیلتر، به‌صورت ثابت در کد نوشته شده‌اند. این روش فعلاً کافی است، اما اگر افزونه کاربرد عمومی‌تری پیدا کند، بهتر است این بخش بازنویسی شود

نتیجه این تجربه

کد کمتر، دردسر کمتر.

سیستم کوپن ووکامرس واقعاً توانمند است؛ کافی است اجازه بدهید کارش را انجام دهد. ما برای کاری که یک کادر انتخاب و ۲۰۰ خط PHP می‌توانست با اطمینان بیشتری انجام دهد، یک افزونه کامل داشتیم. این جایگزینی واقعاً ارزشش را داشت.

رفرنس