Переход 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 напрямую для быстрого исправления одного заказа.
• Не очищайте журналы до завершения диагностики.
• Запланируйте повторную проверку после обновления платежных и складских интеграций.