چرا کوپن تخفیف ووکامرس کار نمی‌کند؟ راهنمای کامل عیب‌یابی و رفع خطا

چند سال پیش، در آستانه یک کمپین فروش فصلی، کارفرمای یک فروشگاه اینترنتی با لحن نگران تماس گرفت: «کد تخفیف را زدم، پیام می‌دهد این کوپن معتبر نیست، در حالی که در تنظیمات فعال است». کوپن را دوباره بررسی کردیم؛ تاریخ انقضا درست بود، محدودیت استفاده نداشت، محصول هم در سبد مشتری بود. اما اعمال نمی‌شد. مشکل جای دیگری بود: یک افزونه caching تهاجمی، نسخه‌ای از سبد خرید را که پیش از افزودن محصول ذخیره شده بود، به کاربر تحویل می‌داد. آن روز برایم روشن شد که عیب‌یابی کد تخفیف در ووکامرس نه یک کار تک‌خطی، که یک مرور سیستماتیک روی یک زنجیره اعتبارسنجی چندلایه است. این مقاله، همان مسیر بازرسی را بازسازی می‌کند.

معماری کوپن در ووکامرس از دید مهندسی

برای اینکه بتوانید «چرا این کوپن اعمال نمی‌شود» را دقیق پاسخ دهید، باید ببینید ووکامرس در لایه زیرین چه چیزی را مدل می‌کند. کوپن در ووکامرس یک موجودیت مستقل است: یک پست از نوع shop_coupon که متادیتای آن در wp_postmeta ذخیره می‌شود. هر کوپن، با کلاس WC_Coupon نمایش داده می‌شود و از طریق متدهای آن، تمام فیلدهای تنظیمات (نوع تخفیف، مقدار، محدودیت‌ها) خوانده و اعتبارسنجی می‌شوند. این معماری در نسخه‌های اخیر HPOS تغییر نکرده چون کوپن‌ها جزء سفارش‌ها نیستند و جدا از HPOS مدیریت می‌شوند.

در سمت اعمال تخفیف، کلاس دیگری به‌نام WC_Discounts وارد می‌شود. این کلاس مسئول اجرای منطق تخفیف روی اقلام سبد است: تعیین اینکه هر کوپن روی کدام آیتم‌ها اعمال شود، چقدر تخفیف بدهد و ترتیب اعمال چند کوپن چطور باشد. اگر با معماری کلی ووکامرس آشنایی ندارید، پیش از ادامه مقاله ووکامرس چیست و چگونه فروشگاه بسازیم را بخوانید تا تصویر کلی در ذهن شما شکل بگیرد. همچنین مفهوم تخفیف در تجارت الکترونیک از منظر استاندارد را می‌توانید در Coupon ویکی‌پدیا مرور کنید.

کوپن در ووکامرس یک پست ساده نیست؛ یک موجودیت با چرخه حیات اعتبارسنجی چندلایه است که هر لایه‌اش می‌تواند بی‌صدا شکست بخورد.

تفکیک سه لایه‌ای که باید بشناسید

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

• لایه تولید: کوپن در دیتابیس وجود دارد اما تنظیماتش اشتباه است — تاریخ، محدودیت یا مقدار.
• لایه اعتبارسنجی: کوپن وجود دارد و تنظیماتش درست است، اما در لحظه اعمال، شرایط سبد خرید آن را رد می‌کند.
• لایه محیط: کوپن و اعتبارسنجی هر دو سالم‌اند، اما کش، نشست، یا افزونه‌ای بیرونی، مانع از رسیدن درخواست به ووکامرس می‌شود.

جدول زیر نگاشت سریع سیمپتوم به لایه خطا را نشان می‌دهد:

زنجیره اعتبارسنجی: ترتیب دقیق بررسی‌ها

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

1. بررسی وجود کوپن: آیا کدی با این نام در دیتابیس هست؟ (حساس به حروف بزرگ و کوچک نیست، اما حساس به فاصله‌های پنهان است.)
2. بررسی وضعیت انتشار: کوپن باید در وضعیت publish باشد. اگر پیش‌نویس یا در سبد حذف باشد، اعمال نمی‌شود.
3. بررسی تاریخ شروع و انقضا: اگر تاریخ فعلی خارج از بازه باشد، پیام «منقضی» نمایش داده می‌شود.
4. بررسی حداقل مبلغ سبد: اگر جمع سبد کمتر از minimum_amount باشد، پیام «حداقل مبلغ رعایت نشده».
5. بررسی حداکثر مبلغ سبد: اگر جمع از maximum_amount بیشتر باشد، پیام «حداکثر مبلغ».
6. بررسی محدودیت استفاده کلی: usage_limit — آیا این کوپن به سقف کل مصرف رسیده؟
7. بررسی محدودیت استفاده هر کاربر: usage_limit_per_user — آیا این کاربر خاص قبلاً استفاده کرده؟
8. بررسی محدودیت ایمیل: اگر email_restrictions تنظیم شده، ایمیل کاربر باید با آن مطابقت داشته باشد.
9. بررسی محدودیت محصول و دسته: کوپن‌های محصولی باید حداقل یک محصول واجد شرایط در سبد داشته باشند.
10. بررسی محصولات حذف‌شده: اگر محصولات سبد در لیست حذف کوپن باشند، تخفیف اعمال نمی‌شود.
11. بررسی فروش ویژه: اگر گزینه exclude_sale_items فعال باشد و محصول در سبد فروش ویژه داشته باشد، آن محصول حذف می‌شود.
12. بررسی کوپن انفرادی: اگر individual_use فعال باشد و کوپن دیگری در سبد باشد، تداخل می‌سازد.

نکته مهمی که اکثر ادمین‌ها از آن بی‌خبرند: اگر یکی از این بررسی‌ها fail شود، ووکامرس پیام خطای مربوطه را نمایش می‌دهد، اما این پیام همیشه دقیق نیست. مثلاً در بعضی نسخه‌ها، خطای محدودیت ایمیل با پیام «کوپن معتبر نیست» نمایش داده می‌شود که گمراه‌کننده است. برای دیدن پیام دقیق، باید از هوک woocommerce_coupon_error استفاده کنید یا در محیط استجینگ، کد را debugging کنید.

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

محدودیت‌های استفاده؛ قاتل بی‌صدای کوپن‌ها

در پرونده‌های پشتیبانی که بررسی کرده‌ام، «محدودیت استفاده» بزرگ‌ترین سهم را در خطاهای کوپن دارد و در عین حال کم‌ترین توجه را از سمت ادمین دریافت می‌کند. سه پارامتر کلیدی در این لایه وجود دارد:

• usage_limit: سقف کل استفاده از کوپن در سراسر فروشگاه. اگر روی ۱۰۰ باشد و کوپن ۱۰۰ بار استفاده شده باشد، اعمال نمی‌شود.
• usage_limit_per_user: سقف استفاده هر کاربر. روی کوپن‌های «یک‌بار مصرف به ازای هر نفر» این گزینه تعیین‌کننده است.
• usage_count: شمارنده داخلی ووکامرس که با هر بار ثبت سفارش موفق یک واحد افزایش می‌یابد. این عدد در متای کوپن ذخیره می‌شود.

یک سناریوی فریبنده که زیاد می‌بینم: کوپن تازه ساخته شده، usage_limit روی ۱۰۰ است، usage_count صفر است، اما اعمال نمی‌شود. ریشه معمولاً در usage_limit_per_user است که روی مقدار پیش‌فرض یک باقی مانده و کاربر قبلاً با ایمیلی دیگر آن را استفاده کرده است. ووکامرس این دو را از هم تفکیک می‌کند ولی در پیام خطا، تفکیک را نشان نمی‌دهد.

سناریوی دوم که کم‌تر کسی می‌شناسد: اگر کوپن روی usage_limit_per_user تنظیم شده باشد و کاربر بعد از اعمال کوپن، سفارش را لغو کند، شمارنده ووکامرس در بعضی نسخه‌ها کاهش پیدا نمی‌کند. یعنی کاربر کوپن را یک بار استفاده کرده تلقی می‌شود، در حالی که سفارش کاملاً لغو شده. رفع این باگ قدیمی نیاز به مداخله دستی در wp_postmeta دارد یا کد سفارشی که هنگام لغو سفارش، شمارنده را کاهش دهد. اگر با این سناریو مواجه شده‌اید، مدیریت صحیح سفارش‌های لغو‌شده را در مدیریت سفارش‌ها در ووکامرس ببینید.

بررسی سریع محدودیت استفاده

برای بررسی سریع، در پیشخوان کوپن‌ها، ستون «Usage / Limit» را فعال کنید. اگر عدد سمت چپ به سقف رسیده، ریشه همان است. برای بررسی عمیق‌تر، در دیتابیس، متای _usage_count و _usage_limit را روی همان ردیف کوپن بررسی کنید.

تاریخ انقضا، حداقل و حداکثر مبلغ

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

سه نکته که در این لایه باید بدانید:

1. تاریخ انقضا بر اساس ساعت سرور است، نه ساعت کاربر. اگر تاریخ انقضا را روی «امروز» تنظیم کرده باشید و ساعت سرور هنوز نیمه‌شب را رد نکرده باشد، کوپن تا ساعت ۰۰:۰۰ روز بعد اعمال می‌شود.
2. حداقل مبلغ به جمع سبد بعد از مالیات یا قبل از آن بستگی دارد. بسته به تنظیمات woocommerce_prices_include_tax، عددی که با آن مقایسه می‌شود متفاوت است. اگر با مالیات کار می‌کنید، ترتیب محاسبه را در مدیریت مالیات در ووکامرس ببینید.
3. حداقل مبلغ با احتساب قیمت فروش ویژه محاسبه می‌شود، نه قیمت اصلی. اگر محصولی در فروش ویژه با تخفیف ۳۰٪ باشد، ووکامرس قیمت فروش را در جمع سبد حساب می‌کند. یعنی ممکن است کاربری از نظر خودش «سبد پرقیمت» داشته باشد، اما جمع محاسبه‌شده زیر حداقل کوپن باشد.

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

محدودیت محصول و دسته‌بندی

کوپن‌ها در ووکامرس می‌توانند به محصولات یا دسته‌های خاص محدود شوند، و همین محدودیت یکی از پرخطاترین بخش‌های پیکربندی است. سه حالت ممکن است پیش بیاید:

• Product IDs: فقط محصولات مشخصی واجد شرایط هستند.
• Product Categories: فقط محصولات دسته‌های مشخصی واجد شرایط هستند.
• Exclude Products / Exclude Categories: محصولات یا دسته‌های مشخصی از تخفیف حذف می‌شوند.

سه خطای کلاسیک در این لایه:

1. محصول واریانت به‌جای والد: در محصولات متغیر، در سبد خرید، واریانت (variant) قرار می‌گیرد نه والد. اگر کوپن روی والد تنظیم شده باشد، بعضی نسخه‌های ووکامرس آن را تشخیص می‌دهند و بعضی نه. اگر شک دارید، هم والد و هم همه واریانت‌ها را در لیست قرار دهید. روش ساخت صحیح محصول متغیر در ساخت محصول متغیر در ووکامرس آمده است.
2. دسته والد و فرزند: اگر محصولی در دسته فرزند باشد و کوپن روی دسته والد تنظیم شده باشد، در بعضی تنظیمات ووکامرس رابطه ارث‌بری درست اعمال نمی‌شود. راه امن: هر دو دسته را در لیست قرار دهید.
3. محصولات موجودی‌صفر: اگر محصول در سبد است اما موجودی‌اش صفر شده، ووکامرس ممکن است آن را از اقلام واجد شرایط حذف کند. مدیریت صحیح موجودی در مدیریت موجودی محصولات در ووکامرس توضیح داده شده است.

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

کوپن‌هایی که به محصولات یا دسته‌های خاص محدود می‌شوند، بیشترین حساسیت را به ساختار کاتالوگ دارند. اگر ساختار دسته‌بندی‌تان در تغییر است، این کوپن‌ها بی‌صدا از کار می‌افتند.

محدودیت ایمیلی و مطابقت کاربر

ووکامرس به شما اجازه می‌دهد کوپن را به فهرست ایمیل‌های خاص محدود کنید — قابلیتی که برای «کد تخفیف اختصاصی» یا «کد مشتری وفادار» بسیار مفید است، اما اگر درست پیکربندی نشود، کاملاً غیرقابل‌استفاده می‌شود. سه اشتباه رایج در این لایه:

1. عدم تطابق حروف بزرگ و کوچک: در بعضی نسخه‌ها، ووکامرس ایمیل را بدون حساسیت به حروف مقایسه می‌کند؛ در بعضی نه. اگر کوپن را برای User@Example.com تنظیم کرده‌اید و کاربر user@example.com وارد کرده، ممکن است اعمال نشود. راه امن: همیشه lowercase استفاده کنید.
2. عدم تطابق کاربر مهمان: اگر کاربر مهمان باشد، ایمیل او با ایمیل ثبت‌شده حساب مقایسه می‌شود. ولی اگر در فرم پرداخت، ایمیل متفاوتی وارد کند، کوپن اعمال نمی‌شود. سناریوی کاربران مهمان و مدیریتشان در مدیریت مشتریان در ووکامرس آمده است.
3. تضاد با افزونه‌های تغییر ایمیل: بعضی افزونه‌های CRM یا عضویت، ایمیل کاربر را بعد از ورود تغییر می‌دهند یا از یک فیلد متفاوت می‌خوانند. نتیجه: کوپن هیچ‌وقت مطابقت پیدا نمی‌کند.

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

مالیات، قیمت و تداخل با محاسبات

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

سه سناریوی دقیق:

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

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

کش، نشست و کوکی؛ سه گلوگاه نامرئی

این لایه همان لایه‌ای است که در ابتدای مقاله به آن اشاره کردم. بزرگ‌ترین دشمن کوپن در فروشگاه‌های پربازدید، کش تهاجمی است. ووکامرس برای اعمال کوپن، از نشست کاربر (session) و کوکی‌های مشخصی استفاده می‌کند تا بتواند کوپن اعمال‌شده را در طول فرآیند خرید حفظ کند. اگر این سه مکانیزم به هر دلیل مختل شوند، کاربر با کوپنی در سبد روبرو می‌شود که «در لحظه اعمال ناپدید می‌شود».

سه سناریوی دقیق که در پروژه‌های خودم دیده‌ام:

1. کش صفحه سبد و پرداخت: اگر صفحات /cart یا /checkout کش عمومی داشته باشند، هر کاربر نسخه‌ای می‌بیند که برای کاربر دیگر ساخته شده. نتیجه: کوپن اعمال‌شده کاربر A به کاربر B نمایش داده می‌شود یا ناپدید می‌شود. اصول کش‌گذاری در ووکامرس را در بهترین افزونه‌های کش وردپرس و تنظیمات دقیق در پیکربندی افزونه کش آمده است.
2. CDN حذف کوکی: بعضی CDNها به‌عنوان بهینه‌سازی، هدر Set-Cookie را حذف می‌کنند یا کوکی‌های ووکامرس را کش می‌کنند. نتیجه: نشست کاربر حفظ نمی‌شود و کوپن اعمال‌شده در حافظه نمی‌ماند.
3. افزونه‌های session اختصاصی: بعضی افزونه‌های caching یا session مدیریت سفارشی دارند که با نشست پیش‌فرض ووکامرس تداخل می‌کنند.

روش تشخیص قطعی: در پنجره ناشناس (Incognito) بدون افزونه، تست کنید. اگر کوپن اعمال شد، ریشه در لایه کاربر است. سپس کش را پاک کنید و در حالت عادی تست کنید. تفاوت رفتار دو حالت، لایه دقیق خطا را نشان می‌دهد.

چند کوپن همزمان و محدودیت انفرادی

ووکامرس به صورت پیش‌فرض از اعمال همزمان چند کوپن پشتیبانی می‌کند، اما این قابلیت با پارامتر individual_use کنترل می‌شود. اگر کوپن A روی individual_use = yes باشد و کاربر کوپن B را وارد کند، ووکامرس کوپن B را رد می‌کند. اگر کوپن B هم روی individual_use = yes باشد، در بعضی نسخه‌ها کوپن دوم کوپن اول را جایگزین می‌کند و کوپن اول ناپدید می‌شود.

سه نکته دقیق:

• ترتیب اعمال کوپن‌ها: ووکامرس کوپن‌ها را به ترتیب ورود کاربر اعمال می‌کند، نه بر اساس مقدار. اگر می‌خواهید کوپن تخفیف بیشتر، کوپن کم‌تخفیف‌تر را تحت‌الشعاع قرار دهد، باید در کد سفارشی این ترتیب را تغییر دهید.
• تخفیف بیشترین مقدار: اگر دو کوپن non-individual دارید، هر دو اعمال می‌شوند، اما اگر مجموع تخفیف از مقدار سبد بیشتر شود، ووکامرس تخفیف را روی صفر clamp می‌کند. این سناریو در فروش‌های بزرگ با کوپن‌های زیاد شایع است.
• تداخل با فروش ویژه: اگر روی کوپن، exclude_sale_items = yes باشد و سبد شامل اقلام فروش ویژه باشد، کوپن روی بقیه اقلام اعمال می‌شود، اما اگر همه اقلام فروش ویژه باشند، پیام «کوپن معتبر نیست» نمایش داده می‌شود.

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

ارز، زبان و نکات محلی

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

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

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

هوک‌های کوپن و ترتیب اجرا

اگر با کوپن‌ها از طریق کد کار می‌کنید، باید ترتیب دقیق هوک‌ها را بشناسید. سه هوک اصلی که در این لایه پرکاربردند:

1. woocommerce_coupon_is_valid: فیلتر اصلی که پیش از اعمال کوپن اجرا می‌شود. اگر مقدار false برگردانید، کوپن رد می‌شود.
2. woocommerce_coupon_error: فیلتر پیام خطا. اگر می‌خواهید پیام دقیق‌تری به کاربر بدهید، از این هوک استفاده کنید.
3. woocommerce_applied_coupon: اکشن پس از اعمال موفق کوپن. برای log کردن یا اکشن‌های جانبی مفید است.

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

پروتکل عیب‌یابی گام‌به‌گام

حالا ترتیب عملی عیب‌یابی از سریع‌ترین به دقیق‌ترین:

1. بازتولید دقیق روی استجینگ: قبل از هر چیز، خطا را در محیطی جدا از سایت زنده بازتولید کنید. روش راه‌اندازی استجینگ در بکاپ گرفتن از فروشگاه ووکامرس آمده است.
2. بررسی پیام دقیق خطا: در ووکامرس، پیام خطای کوپن نمایش داده می‌شود اما همیشه دقیق نیست. با فعال کردن WP_DEBUG_LOG، پیام دقیق را در لاگ ببینید.
3. بررسی محدودیت‌ها یکی‌یکی: یک کوپن موقت بسازید که فقط یک محدودیت داشته باشد. تست بگیرید و بعد یکی‌یکی محدودیت‌ها را اضافه کنید تا مقصر پیدا شود.
4. تست با کاربر مهمان و لاگین: رفتار کوپن در دو حالت را مقایسه کنید. اگر یکی از دو حالت شکست خورد، ریشه در لایه کاربر است.
5. پاک کردن کش: کش افزونه، آبجکت، CDN و مرورگر را کاملاً پاک کنید و تست بگیرید.
6. غیرفعال‌سازی افزونه‌های جانبی: با روش نصف‌سازی، مقصر را پیدا کنید. روش دقیق در رفع تضاد افزونه‌ها آمده است.
7. تغییر موقت قالب به Twenty Twenty: اگر خطا رفع شد، ریشه در قالب است.
8. بررسی لاگ‌ها: لاگ ووکامرس و debug.log را بررسی کنید.

اگر بخواهم مختصر بگویم: هر لایه‌ای که در ترتیب بالا از آن رد شوید و «باگ» باقی بماند، احتمالاً برمی‌گردد. عیب‌یابی بدون طی کردن کامل زنجیره، هزینه‌اش را در پروژه بعدی می‌دهد. برای دیدن خطاهای رایج و راه‌حل‌های سریع، رفع خطاهای رایج ووکامرس و عیب‌یابی خطاهای ووکامرس نقطه شروع سریعی هستند.

در کوپن ووکامرس، «کش را پاک کن و دوباره امتحان کن» یک راه‌حل واقعی است، اما اگر شش ماه بعد همان کوپن از کار بیفتد، یعنی شما ریشه را پیدا نکرده بودید؛ فقط علائم را مدیریت کرده بودید.

اشتباهات پرهزینه در تشخیص

در پرونده‌های پشتیبانی که بازبینی کرده‌ام، این پنج اشتباه بیشتر از بقیه تکرار می‌شود:

• حذف و ساختن مجدد کوپن: بعضی ادمین‌ها به‌جای عیب‌یابی، کوپن را حذف و از نو می‌سازند. نتیجه: شمارنده استفاده صفر می‌شود و مشتریانی که قبلاً استفاده کرده‌اند، می‌توانند دوباره استفاده کنند. حذف کوپن، آخرین ابزار است نه اولین.
• تغییر همزمان چند پارامتر: تاریخ، حداقل مبلغ و محدودیت را همزمان تغییر می‌دهید و بعد نمی‌دانید کدام مؤثر بوده. یک تغییر، یک تست.
• نادیده گرفتن لایه کش: کش را در پرونده جدی نگرفتن، شایع‌ترین خطای عیب‌یابی کوپن در فروشگاه‌های پربازدید است.
• اعتماد به پیام خطا: پیام «کوپن معتبر نیست» می‌تواند از هر یک از ده‌ها شرط مختلف بیاید. اعتماد به پیام بدون بررسی عمیق، وقت زیادی تلف می‌کند.
• بازنویسی هسته ووکامرس: بعضی برای «رفع سریع» مستقیم در فایل‌های ووکامرس دست می‌برند. راه درست، استفاده از هوک‌ها است.

پرسش‌های پرتکرار درباره خطای کوپن ووکامرس

چرا کوپن ووکامرس با پیام «معتبر نیست» رد می‌شود در حالی که همه تنظیمات درست است؟ این پیام عمومی، از هر یک از ده‌ها شرط اعتبارسنجی می‌تواند بیاید. با فعال کردن WP_DEBUG_LOG و بررسی لاگ، پیام دقیق خطا را ببینید. یا از هوک woocommerce_coupon_error برای دریافت پیام دقیق‌تر استفاده کنید.

چرا کوپن برای بعضی کاربران کار می‌کند و برای بعضی نه؟ این نشانه لایه محیط است: کش، نشست یا کوکی. تفاوت اصلی بین کاربرانی که کار می‌کند و کار نمی‌کند، معمولاً در وضعیت cache یا نشست است. با تست در پنجره ناشناس و کاربر لاگین، تفاوت را ببینید.

آیا محدودیت استفاده از کوپن، درست شمارش می‌شود؟ در بیشتر موارد بله، اما در سناریوهای خاص — لغو سفارش، بازگشت پرداخت ناموفق، سفارش‌های failed — شمارنده ممکن است کاهش پیدا نکند. اگر کاربر می‌گوید قبلاً استفاده نکرده اما کوپن کار نمی‌کند، متای _usage_count را در دیتابیس بررسی کنید.

چرا کوپن روی محصولات خاصی اعمال نمی‌شود؟ کوپن‌های محدود به محصول، حساسیت بالایی به ساختار کاتالوگ دارند. اگر محصولی در سبد واریانت (variant) است اما کوپن روی والد تنظیم شده، یا دسته محصول تغییر کرده، کوپن بی‌صدا از کار می‌افتد.

چرا کوپن در سبد اعمال می‌شود اما در پرداخت ناپدید می‌شود؟ ریشه معمولاً در کش صفحه پرداخت است. صفحه /checkout اگر کش عمومی داشته باشد، نشست کاربر حفظ نمی‌شود و کوپن از دست می‌رود. صفحه سبد و پرداخت باید در افزونه کش استثنا باشند.

چرا کوپن percent، تخفیف کم‌تری از انتظار می‌دهد؟ احتمالاً با مالیات کار می‌کنید یا محصول در فروش ویژه است. ووکامرس درصد تخفیف را روی قیمت فروش (نه قیمت اصلی) اعمال می‌کند و ترتیب محاسبه مالیات، مبلغ نهایی را تغییر می‌دهد.

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

از رفع خطا تا معماری قابل‌اتکا

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

1. کوپن‌ها را مستند کنید: برای هر کمپین، یک سند کوچک بسازید که تاریخ، محدودیت‌ها، محصولات واجد شرایط و مقدار را ثبت کند. این سند در روز عیب‌یابی، ارزش ساعات زیادی را دارد.
2. کوپن‌های تستی را حذف کنید: کوپن‌های تستی که در محیط زنده باقی می‌مانند، گاهی به‌دست مشتریان حدس زده می‌شوند و تبدیل به حفره امنیتی و مالی می‌شوند. کدهای تخفیف را مثل رمز عبور جدی بگیرید؛ برای درک این نگاه، امنیت فروشگاه ووکامرس را ببینید.
3. پایش عملکرد در روز کمپین: در روزهای اوج، نرخ موفقیت کوپن را پایش کنید. اگر افت کرد، احتمالاً کش یا منابع هاست اشباع شده. مسئله عملکرد را در افزایش سرعت فروشگاه ووکامرس باز کرده‌ام.

اگر در پروژه‌ای با مشکل مشابه دست‌وپنجه نرم کرده‌اید، برای من جالب است بدانم کدام لایه بیشترین وقت شما را گرفت: محدودیت محصول، محدودیت استفاده، کش یا مالیات. تجربه‌تان را در دیدگاه‌ها بنویسید؛ مخصوصاً اگر نشانه‌ای کشف کرده‌اید که در این فهرست نبوده. همین نشانه‌ها، دقیق‌ترین راهنمای نفر بعدی‌اند. 🎟️