HPOS WooCommerce: как безопасно перенести заказы и проверить совместимость

HPOS WooCommerce (High-Performance Order Storage) хранит заказы в специализированных таблицах вместо старой модели, где заказ был записью WordPress в wp_posts, а большая часть его данных — строками в wp_postmeta. Для новых магазинов HPOS включён по умолчанию начиная с WooCommerce 8.2, но на давно работающем проекте переход требует проверки совместимости.

Риск миграции не в самой кнопке переключения. Проблемы обычно появляются в старых плагинах, custom-коде и интеграциях, которые напрямую читают или изменяют wp_posts/wp_postmeta, обходя WooCommerce CRUD API.

Что меняет HPOS

Заказы переносятся в отдельные таблицы, включая _wc_orders, _wc_order_addresses, _wc_order_operational_data и _wc_orders_meta. Это уменьшает зависимость от универсальной структуры WordPress posts/meta и даёт WooCommerce больше контроля над запросами, индексами и масштабированием заказов.

Для разработчика главный вывод простой: код, который работает через wc_get_order(), wc_get_orders() и методы объекта заказа, значительно легче переносится между хранилищами, чем прямые SQL-запросы к legacy-таблицам.

Почему нельзя включать HPOS сразу на production

В старом магазине вокруг заказов обычно есть платежи, доставка, CRM, ERP, экспорт, фискализация, email, PDF-документы, подписки, отчёты и собственные snippets. Даже если checkout создаёт заказ корректно, отдельный отчёт или cron-задача может продолжать искать его только в wp_posts.

Поэтому переход следует проводить на staging-копии, а не во время рабочего дня на боевом магазине. Если нужна помощь с окружением и изменениями, это типичная задача доработки WooCommerce.

Шаг 1. Сделайте резервную копию и staging

Перед изменением authoritative storage нужна проверенная копия базы и файлов. В staging должны быть реальные плагины, тема и custom-код, а данные заказов — достаточно свежими, чтобы тесты отражали production.

Одной резервной копии недостаточно: заранее нужно понимать, как именно вернуть магазин к прежней схеме и сколько времени займёт восстановление.

Шаг 2. Найдите всё, что работает с заказами

Составьте список компонентов, которые читают или записывают order data. В него обычно входят:

• платёжные шлюзы и webhooks;
• доставка и расчёт тарифов;
• CRM/ERP и склад;
• экспорт заказов и бухгалтерия;
• PDF invoices и документы;
• аналитика и пользовательские отчёты;
• cron/Action Scheduler задачи;
• custom snippets, REST endpoints и WP-CLI команды.

Если компонент не заявляет совместимость с HPOS, это повод проверить его код и тестовый сценарий, а не автоматически считать его сломанным.

Шаг 3. Ищите прямую работу с posts/postmeta

Самый опасный legacy-код — тот, который считает заказ обычным post и пишет meta напрямую. Например, запрос вида SELECT ... FROM wp_posts WHERE post_type='shop_order' зависит от старого хранилища и не должен быть основой новой интеграции.

Вместо этого используйте WooCommerce API:

$orders = wc_get_orders( array(
    'status' => array( 'wc-processing', 'wc-completed' ),
    'limit'  => 50,
    'orderby'=> 'date',
    'order'  => 'DESC',
) );

foreach ( $orders as $order ) {
    $total = $order->get_total();
    $email = $order->get_billing_email();
}

Такой код не привязан к конкретной физической таблице и остаётся корректнее при смене storage engine.

Шаг 4. Включите compatibility mode и дождитесь синхронизации

Для существующего магазина WooCommerce позволяет синхронизировать данные между legacy и HPOS-таблицами. Переключать authoritative storage стоит только после того, как pending synchronization завершена и магазин не показывает несовместимые расширения.

Во время миграции контролируйте очередь фоновых задач и число заказов. Если синхронизация застряла, сначала выясните причину — не пытайтесь «додавить» переключение вручную.

Compatibility mode — переходный режим, а не постоянный костыль

Смысл compatibility mode — помочь безопасно пройти переход и дать расширениям время работать с синхронизированными данными. Он не должен маскировать custom-код, который продолжает писать напрямую в legacy storage.

WooCommerce в 2026 году отдельно изменил поведение синхронизации: начиная с WooCommerce 10.7 sync-on-read отключён по умолчанию. Это ещё одна причина не рассчитывать, что прямые записи в старые таблицы «как-нибудь доедут» в HPOS автоматически.

Шаг 5. Проверьте checkout и весь жизненный цикл заказа

Тест «заказ создался» недостаточен. Нужен полный сценарий:

1. создать заказ через обычный checkout;
2. провести успешную оплату;
3. проверить неоплаченную/ошибочную оплату;
4. изменить статус из админки;
5. выполнить частичный или полный refund, если он используется;
6. проверить email и PDF-документы;
7. проверить экспорт, CRM, склад и доставку;
8. найти заказ через админку и API;
9. запустить критичные cron/Action Scheduler задачи.

Шаг 6. Проверьте REST API, webhooks и интеграции

Внешняя CRM может работать через официальный WooCommerce REST API и не заметить миграцию, а может использовать самописный endpoint с прямым SQL. Поэтому каждую интеграцию нужно проверять отдельно.

Для серверной синхронизации лучше использовать поддерживаемые API и устойчивые webhooks. Архитектуру таких связок я подробно рассматриваю в услуге интеграции WordPress с CRM, REST API и webhooks.

Шаг 7. Проверьте пользовательские отчёты

Старый SQL-отчёт может выглядеть исправным, но после переключения перестать видеть новые заказы. Сравните контрольные показатели до и после миграции: число заказов за период, суммы, статусы, refunds и ключевые custom meta.

Важно сравнивать не только общий count. Ошибка может затронуть один статус или только заказы конкретного платежного метода.

Как расширению объявлять совместимость с HPOS

WooCommerce предоставляет механизм декларации совместимости. Но объявлять её можно только после реального аудита и тестов:

use Automattic\WooCommerce\Utilities\FeaturesUtil;

add_action( 'before_woocommerce_init', function () {
    if ( class_exists( FeaturesUtil::class ) ) {
        FeaturesUtil::declare_compatibility(
            'custom_order_tables',
            __FILE__,
            true
        );
    }
} );

Эта строка не делает старый код совместимым сама по себе. Она лишь сообщает WooCommerce, что разработчик проверил расширение.

Что чаще всего ломается после миграции

• прямые WP_Query по shop_order;
• SQL-запросы к wp_posts и wp_postmeta;
• ручной get_post_meta()/update_post_meta() для данных заказа;
• экспорты, построенные на legacy ID/meta схемах;
• админские колонки и фильтры, привязанные к posts screen;
• интеграции, которые обходят WooCommerce CRUD;
• старые плагины без тестов HPOS.

План переключения production

Когда staging прошёл тесты, выберите спокойное окно, сделайте свежую резервную копию, убедитесь, что синхронизация завершена, и повторите короткий smoke test после переключения. Сразу после изменения проверьте новый оплаченный заказ, админку, CRM и критичный экспорт.

Не удаляйте legacy-данные в день миграции. Сначала нужна стабильная работа и период наблюдения.

Чек-лист готовности HPOS

Когда нужен аудит разработчика

Если магазин работает много лет, содержит самописные плагины или бизнес-критичные интеграции, полезнее сначала провести аудит, чем исправлять последствия после переключения. В A.S Groups можно заказать разработку WooCommerce: проверю custom-код, точки чтения/записи заказов, совместимость интеграций и подготовлю безопасный план миграции.

Официальные источники

• WooCommerce: High-Performance Order Storage
• WooCommerce Developer: HPOS documentation
• WooCommerce Developer: HPOS sync-on-read in WooCommerce 10.7