فرض کنید سفارش مشتری در ووکامرس ثبت شده، اما پیامک سفارش ارسال نشده یا اطلاعات خرید به نرم‌افزار حسابداری منتقل نشده است. در بخش Scheduled Actions چند وظیفه Failed می‌بینید و نمی‌دانید کدام‌یک به مشکل مربوط است. آیا باید تمام وظایف را حذف کنید؟ آیا کلیک روی Run مشکل را برطرف می‌کند؟ پاسخ هر دو سؤال بدون بررسی گزارش خطا منفی است. این آموزش به شما کمک می‌کند یک وظیفه مشخص را پیدا کنید، علت شکست را تشخیص دهید و فقط در صورت امن‌بودن، اجرای مجدد آن را انجام دهید.
هدف، تعمیر یک فرایند واقعی در فروشگاه است؛ نه پاکسازی دیتابیس یا توضیح کلی Cron. سه وضعیت مهم را بررسی می‌کنیم: تمام‌شدن زمان پردازش، نامعتبر بودن داده وابسته و دریافت پاسخ خطا از یک سرویس خارجی. برای هرکدام نشانه، روش بررسی، اصلاح احتمالی و معیار تأیید نتیجه را می‌بینید.
پیش از شروع چه چیزهایی لازم است؟
به دسترسی مدیریت وردپرس، صفحه وضعیت ووکامرس و در صورت نیاز PHP Error Log هاست احتیاج دارید. بهتر است سایت تست یا Staging داشته باشید؛ برای تغییراتی که ممکن است سفارش، پرداخت، موجودی یا ارسال اعلان را دوباره اجرا کنند، وجود محیط آزمایشی و نسخه پشتیبان ضروری است. اگر وظیفه به API خارجی متصل است، دسترسی به گزارش سرویس مقصد هم کمک زیادی می‌کند.
- نسخه WordPress، WooCommerce، PHP و افزونه‌ای که وظیفه را ساخته یادداشت شود.
- از دیتابیس و فایل‌های سایت نسخه پشتیبان قابل بازیابی تهیه شود.
- برای آزمایش از سفارش یا داده ساختگی استفاده شود؛ اطلاعات مشتری واقعی در تصویر و گزارش منتشر نشود.
- به‌جای دستکاری مستقیم جدول‌های Action Scheduler، از پیشخوان و APIهای رسمی استفاده شود.
Action Scheduler چیست و چه کاری در ووکامرس انجام می‌دهد؟
Action Scheduler یک سیستم صف برای اجرای عملیات پس‌زمینه در وردپرس است. ووکامرس و بعضی افزونه‌ها کارهایی مانند پردازش اعلان، ارسال Webhook، همگام‌سازی اطلاعات یا اجرای رویدادهای زمان‌بندی‌شده را به این صف می‌سپارند. هر وظیفه یا Action معمولاً Hook، زمان اجرای برنامه‌ریزی‌شده، Group، Arguments و Log دارد. Hook نام عملیاتی است که باید اجرا شود؛ Arguments داده‌هایی هستند که همان عملیات دریافت می‌کند.
WP-Cron ممکن است اجرای صف را فعال کند، اما خود Action Scheduler مسئول ثبت و پیگیری وضعیت وظایف است. بنابراین مشکلی که باعث Pending ماندن تعداد زیادی وظیفه شده، الزاماً همان علت Failed شدن یک وظیفه نیست. این تفاوت کمک می‌کند بدون تغییر غیرضروری Cron، مستقیماً سراغ خطای مربوط به افزونه بروید.
وضعیت‌های Pending، Failed و Complete چه تفاوتی دارند؟
- Pending: وظیفه در صف است و هنوز اجرای آن کامل نشده است.
- In-progress: اجرای وظیفه شروع شده و نتیجه قطعی آن هنوز ثبت نشده است.
- Failed: اجرا با خطا یا شرایط شکست مواجه شده است؛ ممکن است بخشی از اثر خارجی قبلاً انجام شده باشد.
- Complete: callback با موفقیت کامل شده است؛ برای عملیات خارجی باید نتیجه واقعی مقصد را نیز بررسی کرد.
- Canceled: اجرای وظیفه لغو شده و نباید با خطای Failed اشتباه گرفته شود.
مرحله 1: وظیفه Failed را پیدا کنید
در پیشخوان وردپرس به «ووکامرس ← وضعیت ← Scheduled Actions» بروید. در بعضی نصب‌ها همین صفحه از «ابزارها ← Scheduled Actions» نیز در دسترس است. تب Failed را باز کنید و وظیفه‌ای را انتخاب کنید که زمان آن با مشکل واقعی سایت مطابقت دارد. مثلاً اگر پیامک سفارشی با شناسه آزمایشی T-104 نرسیده، لازم نیست همه وظایف صف را بررسی کنید؛ ابتدا Hook و Argumentهای مرتبط با پیامک یا همان سفارش را پیدا کنید.
نام Hook، Group، شناسه Action، زمان اجرا و Arguments را ثبت کنید. Group معمولاً سرنخی از افزونه سازنده است، اما تنها از روی نام آن نباید درباره اثر Retry نتیجه گرفت. اگر آرگومان حاوی شماره موبایل، ایمیل یا Token است، پیش از ذخیره تصویر آن را مخفی کنید.
از کجا بفهمیم کدام افزونه وظیفه را ساخته است؟
نام Hook را در مستندات افزونه‌ها یا کد سفارشی سایت جست‌وجو کنید. سپس Group و متن Log را بررسی کنید. اگر وظیفه به سرویس پیامک، اشتراک، پرداخت یا حسابداری مربوط است، قبل از هر اقدام بفهمید callback چه اثری در آن سرویس می‌گذارد. پیدا شدن نام افزونه به معنی مشخص شدن علت شکست نیست؛ فقط دامنه بررسی را محدود می‌کند.
مرحله 2: بررسی گزارش وظایف ناموفق ووکامرس
پس از ورود به بخش «ووکامرس ← وضعیت ← عملیات برنامه‌ریزی‌شده»، تب «ناموفق» را انتخاب کنید. در این صفحه، اطلاعات هر وظیفه از جمله نام Hook، وضعیت، زمان اجرا و گزارش فعالیت آن نمایش داده می‌شود.
در نسخه‌ای از Action Scheduler که در تصویر مشاهده می‌کنید، جزئیات گزارش مستقیماً در ستون «گزارش» قرار دارند و برای مشاهده آن‌ها نیازی به بازکردن صفحه جداگانه نیست.
برای بررسی علت خطا، ابتدا نام Hook را پیدا کنید و سپس پیام‌های همان ردیف را بخوانید. برای مثال، اگر در گزارش نوشته شده باشد «هیچ فراخوانی برگشتی برای این Hook ثبت نشده است»، باید بررسی کنید کدام افزونه یا کد وظیفه را ایجاد کرده و آیا تابع مربوط به اجرای آن همچنان فعال است یا خیر.
در صورت نیاز، گزارش‌های خطای PHP و افزونه مربوط را نیز بررسی کنید. تا زمانی که علت خطا و اثر اجرای دوباره مشخص نشده است، از اجرای گروهی یا حذف وظایف خودداری کنید.
اگر Log خالی یا مبهم بود چه کنیم؟
اول مطمئن شوید شناسه Action درست انتخاب شده است. سپس خطاهای PHP، Log افزونه مسئول و وضعیت سرویس مقصد را بررسی کنید. اگر خطا بعد از یک بروزرسانی شروع شده، نسخه قبل و بعد افزونه را در محیط تست مقایسه کنید. هدف این است که از عبارت کلی «وظایف ناموفق ووکامرس» به یک علت قابل آزمایش برسید.
مرحله 3: علت وظایف ناموفق ووکامرس را تشخیص دهید
سناریوی اول: محدودیت زمان یا Timeout
تصور کنید یک افزونه باید فهرستی از سفارش‌ها را به سرویس حسابداری همگام کند. اجرای عملیات آغاز می‌شود، اما پردازش رکوردها یا پاسخ سرویس آن‌قدر طول می‌کشد که وظیفه با Timeout مواجه می‌شود. راه درست این نیست که بلافاصله همه محدودیت‌های سرور افزایش یابد. ابتدا باید زمان شروع و شکست را با PHP Time Limit و Log سرور مقایسه کرد و دید کدام بخش کند است.
اگر افزونه از پردازش دسته‌ای پشتیبانی می‌کند، کاهش اندازه Batch در Staging می‌تواند روش آزمون باشد. اگر مشکل از API کند است، زمان پاسخ یا الگوی Retry باید بررسی شود. نکته مهم اینکه در بعضی شرایط Action Scheduler پس از گذشت زمان مجاز، وظیفه را Failed علامت می‌زند، اما callback ممکن است بعداً کامل شود؛ بنابراین پیش از اجرای مجدد، اثر واقعی عملیات کنترل شود.
روش بازسازی پیشنهادی: توسعه‌دهنده روی محیط غیرعملیاتی یک Hook آزمایشی و بی‌خطر با تأخیر کنترل‌شده بسازد، زمان اجرا و خطای آن را ثبت کند، سپس با کاهش پردازش یک Action تازه را آزمایش کند. بدون این آزمایش نباید عددی به‌عنوان «زمان واقعی رفع خطا» گزارش شود.
سناریوی دوم: وابستگی یا شناسه نامعتبر
گاهی یک Action برای سفارش، کاربر یا رکوردی ایجاد شده که هنگام اجرای آن دیگر وجود ندارد یا وضعیت لازم را ندارد. برای مثال، در Arguments شناسه یک رکورد وجود دارد، اما callback افزونه بدون بررسی اعتبار آن به پردازش ادامه می‌دهد و خطا می‌گیرد. در چنین شرایطی تکرار Action با همان ورودی، مشکل را رفع نمی‌کند.
شناسه مربوط را در محیط تست بررسی کنید و ببینید آیا حذف یا تغییر وضعیت آن عمدی بوده است. اگر عملیات دیگر لازم نیست، توسعه‌دهنده می‌تواند رفتار کنترل‌شده برای داده ناموجود در نظر بگیرد. اگر شناسه به اشتباه ارسال می‌شود، باید منبع تولید Action اصلاح شود. از ساخت سفارش صوری در سایت اصلی یا تغییر مستقیم جدول‌های دیتابیس برای پنهان‌کردن خطا خودداری کنید.
روش بازسازی پیشنهادی: یک Hook آزمایشی را با شناسه رکورد ناموجود اجرا و Log آن را ثبت کنید؛ سپس همان منطق را با رکورد معتبر امتحان کنید. نتیجه باید نشان دهد چرا خطا اتفاق افتاده و کدام شرط کنترل اعتبار آن را برطرف می‌کند.
سناریوی سوم: پاسخ خطا از سرویس خارجی
اگر Action به API یک سامانه پیامک، CRM یا حسابداری وصل باشد، پاسخ ناموفق سرور مقصد می‌تواند باعث Failed شدن عملیات شود. برای نمونه، 401 معمولاً بررسی اعتبارنامه، 429 بررسی محدودیت درخواست و 503 بررسی دسترس‌پذیری سرویس را لازم می‌کند. اما کد HTTP به‌تنهایی به معنی انجام‌نشدن عملیات در مقصد نیست؛ امکان دارد درخواست پردازش شده اما پاسخ به سایت شما نرسیده باشد.
قبل از Retry، وضعیت سفارش یا درخواست را در سرویس مقصد جست‌وجو کنید. در اتصال‌های حساس، شناسه یکتا و سازوکار جلوگیری از پردازش تکراری باید وجود داشته باشد. اگر عملیات در مقصد انجام شده، ارسال مجدد ممکن است فاکتور یا اعلان تکراری بسازد.
روش بازسازی پیشنهادی: یک API ساختگی در Staging ابتدا پاسخ 503 و سپس پاسخ موفق برگرداند. در هر دو حالت، زمان و پاسخ ثبت شود و بررسی شود فقط یک رکورد نهایی در مقصد ایجاد شده است. این یک پروتکل آزمون است، نه ادعای اجرای آزمون روی سایت واقعی.
مقایسه سریع انواع خطاهای Action Scheduler
| نوع خطا | نشانه قابل مشاهده | کنترل اول | اقدام پیشنهادی | چه چیزی موفقیت را ثابت می‌کند؟ |
|---|---|---|---|---|
| Timeout | توقف بعد از زمان طولانی | زمان اجرا، PHP Log و اندازه Batch | رفع گلوگاه یا کاهش Batch در تست | Action جدید کامل شود و اثر قبلی تکرار نشود |
| داده وابسته نامعتبر | شناسه یا شیء پیدا نمی‌شود | Arguments و وجود رکورد | اصلاح ورودی یا کنترل نبود رکورد | ورودی معتبر بدون خطا پردازش شود |
| خطای API خارجی | HTTP 401/429/503 یا قطع ارتباط | پاسخ، شناسه درخواست و گزارش مقصد | رفع دسترسی یا Retry کنترل‌شده | فقط یک عملیات نهایی در مقصد ثبت شود |
مرحله 4: چگونه یک وظیفه را امن دوباره اجرا کنیم؟
بعد از تشخیص و اصلاح علت، ابتدا بررسی کنید آیا افزونه سازنده روش رسمی برای اجرای مجدد یا ایجاد Action جایگزین دارد. در صفحه مدیریت معمولاً امکان اجرای دستی وظایف Pending وجود دارد، اما وجود و رفتار دکمه Run برای Actionهای Failed ممکن است بر اساس نسخه متفاوت باشد. پس نباید فرض کنید هر مورد Failed مستقیماً با یک کلیک قابل اجرای دوباره است.
اگر راهکار افزونه اجازه Retry می‌دهد، تنها یک عملیات غیرمالی و کم‌خطر را در محیط تست انتخاب کنید. قبل از آن وضعیت فعلی سفارش یا داده مقصد را ثبت کنید. بعد از اجرا، هم Log تازه و هم اثر واقعی را بررسی کنید. Complete شدن Job به‌تنهایی اثبات نمی‌کند رکورد درست در سرویس مقصد ایجاد شده است.
آیا اجرای مجدد ممکن است سفارش را تکرار کند؟
بسته به پیاده‌سازی callback، اجرای دوباره می‌تواند عملیات مرتبط با سفارش را تکرار کند؛ مثلاً ارسال دوباره پیامک، Webhook یا فاکتور. اگر وضعیت عملیات قبلی معلوم نیست، مخصوصاً برای پرداخت، تمدید اشتراک و موجودی، اجرا را متوقف و از توسعه‌دهنده کمک بگیرید. جلوگیری از تکرار باید در منطق پردازش و در صورت لزوم با شناسه یکتای درخواست انجام شود.
WP-CLI چه کمکی می‌کند؟
در محیط توسعه، WP-CLI برای مشاهده و مدیریت صف کاربرد دارد. برای دیدن فرمان‌ها و گزینه‌های دقیق همان نسخه از دستور wp help action-scheduler یا راهنمای بسته نصب‌شده استفاده کنید. اجرای عمومی صف با wp action-scheduler run ممکن است تعداد زیادی وظیفه را پردازش کند؛ پس برای حل یک خطای مشخص، بدون شناخت فیلترها و اثر عملیات از اجرای وسیع صف در Production خودداری کنید.
مرحله 5: از تکرار خطا جلوگیری کنید
اگر پس از Retry همان Hook دوباره Failed می‌شود، مشکل اصلی حل نشده است. تعداد خطاهای جدید را برای همان Hook و Group زیر نظر بگیرید. در خطای Timeout، حجم عملیات و زیرساخت را ارزیابی کنید؛ در خطای داده وابسته، کنترل اعتبار ورودی را اصلاح کنید؛ و در خطای API، سیاست Retry، محدودیت نرخ و وضعیت پاسخ مقصد را پایش کنید.
در نسخه 4.0.0 کتابخانه Action Scheduler، پاکسازی پیش‌فرض وظایف Failed قدیمی پس از حدود 3 ماه معرفی شده است. بنابراین برای مسائل مهم، قبل از حذف یا پاکسازی خودکار، شواهد لازم را در گزارش امن ذخیره کنید. این تنظیم به نسخه واقعی کتابخانه‌ای بستگی دارد که سایت استفاده می‌کند.
برگه کنترل عیب‌یابی پیش از اقدام روی سایت اصلی
- یک Hook مشخص و مرتبط با مشکل واقعی انتخاب شده است.
- نام افزونه سازنده، نسخه‌ها و زمان شروع خطا ثبت شده‌اند.
- Log اصلی و گزارش PHP یا API در صورت نیاز بررسی شده است.
- معلوم شده آیا اثر خارجی عملیات قبلاً انجام شده یا خیر.
- نسخه پشتیبان و در صورت لزوم Staging آماده است.
- فقط یک اصلاح محدود با معیار موفقیت مشخص اجرا شده است.
- نتیجه در Action Scheduler و سامانه مقصد بررسی شده است.
- اگر داده مالی یا رکورد مشتری درگیر است، شخص متخصص قبل از Retry تأیید کرده است.
چه زمانی باید به توسعه‌دهنده ارجاع دهیم؟
وقتی خطا به Fatal Error در کد افزونه مربوط است، Action عملیات مالی انجام می‌دهد، معلوم نیست درخواست قبلی در مقصد ثبت شده یا نه، یا اجرای دوباره باعث اختلاف موجودی یا داده سفارش می‌شود، بهتر است آزمایش را متوقف کنید. برای پشتیبانی، نام Hook، Group، نسخه افزونه، زمان رخداد و Log بدون داده حساس را آماده کنید. از ارسال رمز، API Key یا اطلاعات شخصی مشتری در تیکت عمومی خودداری کنید.
اگر مشکل شما صرفاً بزرگ‌شدن دیتابیس است، راهنمای بهینه‌سازی دیتابیس وردپرس موضوع دیگری را پوشش می‌دهد؛ پاکسازی دیتابیس درمان خودکار خطای Action نیست. همچنین برای مشکلات کلی تجربه کاربری، راهنمای INP وردپرس را می‌توانید جداگانه مطالعه کنید.
جمع‌بندی
برای رفع وظایف ناموفق ووکامرس، به‌جای پاک‌کردن صف، مسیر مشخصی را دنبال کنید: پیدا کردن Action، خواندن گزارش، تشخیص علت و آزمون یک اصلاح محدود. تمرکز بر یک وظیفه قابل شناسایی باعث می‌شود هم احتمال آسیب به سفارش‌ها کمتر شود و هم بتوانید نتیجه را واقعاً ارزیابی کنید. پیش از اعمال تغییر روی فروشگاه اصلی، یکی از سناریوهای غیرمالی را در Staging اجرا و اطلاعات شروع، خطا، اصلاح و خروجی را ثبت کنید.
