Перехід WooCommerce на HPOS без поломки замовлень та інтеграцій

Що таке HPOS і чому він впливає на інтеграції

У класичному режимі WooCommerce замовлення представлені як записи типу shop_order, а їхні поля та метадані зберігаються переважно у wp_posts і wp_postmeta. HPOS переносить основні дані замовлень у спеціалізовані таблиці WooCommerce. Для роботи із замовленнями це не змінює стандартний інтерфейс магазину, але змінює внутрішню модель даних.

Проблеми виникають тоді, коли код не використовує API WooCommerce, а напряму читає таблиці WordPress. Наприклад, запит WP_Query із post_type => shop_order може перестати повертати очікувані результати після повного переходу на HPOS. Так само небезпечні SQL-запити до wp_postmeta, ручна зміна статусів і припущення, що ID замовлення завжди можна обробити як звичайний пост.

Сумісні розширення працюють через CRUD-класи WooCommerce, зокрема WC_Order, і не залежать від конкретного способу зберігання. Саме тому головне завдання перед міграцією — знайти прямі звернення до старої структури та перевірити сторонні інтеграції.

• Потенційно ризикові компоненти: платіжні шлюзи, CRM, ERP, служби доставки, складські системи, бухгалтерські модулі та власні імпортери.
• Особливу увагу приділіть коду, який синхронізує замовлення за розкладом або реагує на зміни статусу.
• HPOS не замінює резервне копіювання та тестування: це зміна структури зберігання, а не просто перемикач продуктивності.

Підготовка: резервна копія, staging і перелік залежностей

Не вмикайте HPOS без актуальної резервної копії бази даних і файлів сайту. Резервна копія має бути не лише створена, а й перевірена: переконайтеся, що її можна відновити на окремому середовищі. Для магазину також важливо зберегти конфігурацію платіжних сервісів, ключі вебхуків і налаштування інтеграцій.

Спочатку повторіть майбутню міграцію на staging-копії магазину. Staging має містити реалістичні дані: замовлення різних статусів, товари з варіаціями, повернення, купони, податки, гостьові покупки та замовлення з нестандартними полями.

Складіть список усіх компонентів, які можуть читати або змінювати замовлення. Перевірте документацію та журнал змін кожного плагіна, а для критичних інтеграцій — підтвердіть сумісність у розробника. Оновіть WooCommerce, тему та розширення в тестовому середовищі, але не робіть масове оновлення продакшену без окремого плану відкату.

• Зафіксуйте поточну кількість замовлень, їхні статуси та кількість замовлень за останні дні.
• Перевірте черги cron, заплановані дії та фонові завдання, що створюють або передають замовлення.
• Підготуйте вікно обслуговування з мінімальним трафіком, якщо синхронізація або перевірки можуть тривати довго.
• Заздалегідь визначте, хто перевірятиме оплату, доставку, CRM, склад і повернення після перемикання.

Як знайти несумісний код до переходу

Почніть із пошуку по власному коду, mu-плагінах, дочірній темі та кастомних розширеннях. Шукайте не лише назву shop_order, а й ознаки роботи із замовленнями через WordPress API або SQL.

Наявність такого фрагмента не завжди означає поломку: частина сумісних сценаріїв може працювати через шар сумісності. Проте кожен результат потрібно перевірити, особливо якщо код виконується під час оформлення замовлення або змінює його дані.

• WP_Query або get_posts із post_type => shop_order.
• Прямі SQL-запити до wp_posts, wp_postmeta або пошук мета-ключів замовлення через $wpdb.
• Виклики get_post_meta(), update_post_meta() та delete_post_meta() для полів замовлення.
• Перевірки на кшталт get_post_type($order_id) або робота із замовленням як із WP_Post.
• Власні звіти, експортери та імпортери, які вибирають замовлення за датою, статусом чи клієнтом через таблиці WordPress.

/* Ризиковий підхід */
$orders = get_posts([
    'post_type' => 'shop_order',
    'post_status' => 'wc-processing',
]);

/* Підхід через API WooCommerce */
$orders = wc_get_orders([
    'status' => 'processing',
    'limit' => 50,
]);

Чим замінити прямий доступ до замовлень і метаданих

Для отримання одного замовлення використовуйте wc_get_order(). Метод повертає об'єкт WC_Order і приховує від коду конкретну структуру таблиць. Для списків замовлень використовуйте wc_get_orders() або WC_Order_Query. Такі методи є рекомендованим шаром доступу WooCommerce та краще переживають зміни внутрішнього зберігання.

Поля замовлення потрібно читати через гетери, а змінювати — через сетери або методи метаданих об'єкта. Після змін викликайте save(), щоб WooCommerce коректно записав дані. Не змішуйте цей підхід із ручним оновленням wp_postmeta: це може створити розбіжності між джерелами даних.

Для складних сценаріїв фільтрацію слід будувати на параметрах, які підтримує API WooCommerce. Якщо потрібен нестандартний критерій, спочатку перевірте документацію та можливості актуальної версії WooCommerce, а не додавайте SQL-запит до старих таблиць.

• Один запис: $order = wc_get_order($order_id).
• Список записів: wc_get_orders() із параметрами status, customer_id, limit, date та іншими підтримуваними аргументами.
• Дані клієнта й оплати: використовуйте get_billing_email(), get_payment_method() та інші методи WC_Order.
• Мета-дані: $order->get_meta('key'), $order->update_meta_data('key', $value), після чого $order->save().
• Статус: використовуйте методи об'єкта замовлення, а не ручну зміну post_status у базі.

$order = wc_get_order($order_id);

if ($order) {
    $email = $order->get_billing_email();
    $source = $order->get_meta('_order_source');

    $order->update_meta_data('_exported_to_crm', 'yes');
    $order->save();
}

$orders = wc_get_orders([
    'status' => ['processing', 'completed'],
    'limit' => 100,
    'return' => 'objects',
]);

Увімкнення HPOS у режимі сумісності

Перше перемикання виконуйте на staging. У налаштуваннях WooCommerce виберіть режим зберігання замовлень, який передбачає HPOS, і залиште ввімкненим режим сумісності, якщо він доступний для вашої версії. Його призначення — підтримувати синхронізацію між новими таблицями та старим сховищем під час перевірки.

Після активації не вважайте міграцію завершеною. Старі замовлення мають бути синхронізовані, а процес може виконуватися фоновими завданнями. Стежте за станом синхронізації, помилками в журналі WooCommerce та чергами запланованих дій. Не видаляйте старі дані й не вимикайте сумісність, доки не переконаєтеся, що всі критичні процеси працюють.

Після завершення синхронізації порівняйте кількість замовлень, статуси, суми, податки, адреси, купони та метадані, які використовують інтеграції. Якщо є розбіжності, зупиніть подальше перемикання та з'ясуйте причину на staging.

• Перевірте, що нові тестові замовлення створюються і відображаються в адмінці.
• Перевірте відкриття старих замовлень, фільтри, пошук і масові дії.
• Не запускайте одночасно міграцію та масштабне оновлення плагінів без потреби.
• Збережіть журнали помилок і результат перевірки як основу для продакшен-плану.

Що протестувати після перемикання

Перевірка має імітувати реальні бізнес-процеси, а не обмежуватися відкриттям сторінки налаштувань. Створіть тестові замовлення різними способами й простежте весь шлях даних: від checkout до оплати, відправлення в CRM або систему складу та зміни фінального статусу.

Окремо перевірте старі замовлення. Інтеграція може коректно обробляти нові записи, але помилятися під час вибірки історичних даних, повернень або повторної синхронізації.

• Checkout для зареєстрованого та гостьового покупця.
• Успішна оплата, відхилена оплата, повторна спроба та обробка платіжного вебхука.
• Зміна статусів, email-сповіщення, зменшення залишків і передача замовлення у fulfillment.
• Повернення коштів, повне та часткове повернення, скасування й ручне редагування замовлення.
• CRM, ERP, доставка, аналітика, експорт і всі інтеграції, що запускаються cron або webhook.
• Пошук і фільтрація в адмінці, звіти та власні сторінки менеджерів.
• Замовлення з варіаціями, купонами, податками, нестандартними полями та цифровими товарами.

Типові помилки та безпечний план відкату

Найчастіша помилка — увімкнути HPOS одразу на бойовому сайті, не перевіривши код, який давно не оновлювався. Інша поширена проблема — перевірити лише checkout, але не протестувати вебхуки, повернення та фонові синхронізації. Ще одна помилка — вручну виправляти записи в базі, не розуміючи, яке сховище є актуальним.

Якщо на staging або продакшені з'явилися помилки, зафіксуйте час, конкретне замовлення, дію користувача, журнал і назви активних розширень. За можливості поверніться до попереднього режиму через офіційні налаштування WooCommerce, не видаляючи таблиці HPOS. Відновлення резервної копії може бути необхідним, якщо дані вже були змінені некоректним кодом.

Після відкату повторно перевірте оплату та створення замовлень. Не вважайте проблему вирішеною, поки не оновите або не заміните несумісне розширення і не повторите міграцію на тестовому середовищі.

• Не вимикайте синхронізацію посеред активного процесу без розуміння наслідків.
• Не редагуйте таблиці HPOS або wp_postmeta напряму для швидкого виправлення одного замовлення.
• Не очищайте журнали до завершення діагностики.
• Плануйте повторну перевірку після оновлення платіжних і складських інтеграцій.