Автоматическая миграция legacy ACF Flexible Content в нативные блоки Gutenberg

<?php
declare(strict_types=1);

/**
* Author: Artur Yusupov (Fullstack Agentic Lab)
* Package: @agentic-lab/acf-migration
* Module: AcfToGutenbergMigrationCommand
* Standard: WordPress 6.8+ / PHP 8.4 / WP-CLI v2
*/

namespace AgenticLab\Migration;

use WP_CLI;
use WP_Post;
use Throwable;

final class AcfToGutenbergMigrationCommand
{
  private string $apiKey;
  private string $apiEndpoint = 'https://api.openai.com/v1/chat/completions';

  public function __construct()
  {
      $this->apiKey = (string) (getenv('OPENAI_API_KEY') ?: '');
  }

  /**
   * Пакетная конвертация ACF Flexible Content в блоки Gutenberg.
   *
   * ## OPTIONS
   *
   * [--post-type=<type>]
   * : Тип записи для миграции. По умолчанию 'post'.
   *
   * [--batch=<number>]
   * : Количество постов в одной пачке. По умолчанию 50.
   *
   * ## EXAMPLES
   *
   *     wp agentic migrate-acf --post-type=post --batch=25
   *
   * @when after_wp_load
   */
  public function __invoke(array $args, array $assocArgs): void
  {
      if ($this->apiKey === '') {
          WP_CLI::error('Переменная окружения OPENAI_API_KEY не задана.');
      }

      $postType = (string) ($assocArgs['post-type'] ?? 'post');
      $batchSize = (int) ($assocArgs['batch'] ?? 50);

      WP_CLI::log("Запуск миграции для типа записей '{$postType}' с размером батча {$batchSize}...");

      $totalMigrated = 0;
      $totalErrors   = 0;

      while (true) {
          $posts = get_posts([
              'post_type'      => $postType,
              'posts_per_page' => $batchSize,
              'post_status'    => 'any',
              'meta_query'     => [
                  [
                      'key'     => '_agentic_migration_status',
                      'compare' => 'NOT EXISTS',
                  ],
              ],
          ]);

          if (empty($posts)) {
              WP_CLI::success("Все записи типа '{$postType}' успешно обработаны. Всего мигрировано: {$totalMigrated}. Ошибок: {$totalErrors}.");
              break;
          }

          foreach ($posts as $post) {
              if (!$post instanceof WP_Post) {
                  continue;
              }

              $status = $this->migrateSinglePost($post);
              if ($status) {
                  $totalMigrated++;
              } else {
                  $totalErrors++;
              }
          }

          // Очистка памяти для предотвращения утечек в долгих процессах WP-CLI
          $this->flushMemoryCache();
      }
  }

  private function migrateSinglePost(WP_Post $post): bool
  {
      // 1. Извлечение гибкого контента ACF
      $flexibleContent = get_field('page_flexible_content', $post->ID);

      if (empty($flexibleContent) || !is_array($flexibleContent)) {
          update_post_meta($post->ID, '_agentic_migration_status', 'skipped_no_acf');
          WP_CLI::log("Пост #{$post->ID}: ACF-контент отсутствует. Пропущен.");
          return true;
      }

      // 2. Обогащение контекста (Hydration): заменяем ID вложений на объекты с URL и Alt
      $enrichedData = $this->hydrateAcfData($flexibleContent);

      // 3. Генерация Gutenberg-разметки через LLM
      try {
          $gutenbergHtml = $this->transformWithLlm($enrichedData);

          // 4. Серверная верификация блоков
          if (!has_blocks($gutenbergHtml)) {
              throw new \RuntimeException('LLM вернула ответ без зарегистрированных Gutenberg-комментариев.');
          }

          $parsed = parse_blocks($gutenbergHtml);
          if (empty($parsed)) {
              throw new \RuntimeException('Сгенерированный HTML не прошел парсинг ядра parse_blocks().');
          }

          // 5. Сохранение резервной копии старого контента в метаданные и обновление поста
          update_post_meta($post->ID, '_legacy_acf_backup', $flexibleContent);

          $updateResult = wp_update_post([
              'ID'           => $post->ID,
              'post_content' => $gutenbergHtml,
          ], true);

          if (is_wp_error($updateResult)) {
              throw new \RuntimeException($updateResult->get_error_message());
          }

          update_post_meta($post->ID, '_agentic_migration_status', 'completed');
          WP_CLI::success("Пост #{$post->ID} успешно мигрирован в блоки Gutenberg.");
          return true;
      } catch (Throwable $e) {
          update_post_meta($post->ID, '_agentic_migration_status', 'failed');
          update_post_meta($post->ID, '_agentic_migration_error', $e->getMessage());
          WP_CLI::warning("Сбой миграции поста #{$post->ID}: " . $e->getMessage());
          return false;
      }
  }

  /**
   * Обогащение данных ACF URL-адресами медиафайлов.
   */
  private function hydrateAcfData(array $layouts): array
  {
      foreach ($layouts as &$layout) {
          if (!is_array($layout)) {
              continue;
          }

          foreach ($layout as $key => &$value) {
              // Если поле содержит ID вложения изображения
              if (str_contains($key, 'image') && is_numeric($value) && (int) $value > 0) {
                  $attachmentId = (int) $value;
                  $url = wp_get_attachment_image_url($attachmentId, 'full');
                  $alt = (string) get_post_meta($attachmentId, '_wp_attachment_image_alt', true);

                  $value = [
                      'id'  => $attachmentId,
                      'url' => $url ?: '',
                      'alt' => $alt,
                  ];
              }
          }
      }
      return $layouts;
  }

  /**
   * Вызов LLM с алгоритмом Exponential Backoff для обработки Rate Limits (429).
   */
  private function transformWithLlm(array $acfData): string
  {
      $jsonPayload = wp_json_encode($acfData, JSON_UNESCAPED_UNICODE);

      $systemPrompt = <<<PROMPT
Вы — ведущий инженер ядра WordPress. Преобразуйте предоставленный JSON из ACF Flexible Content в чистый сериализованный HTML блоков Gutenberg.
Правила:
1. Используйте ТОЛЬКО нативные блоки ядра: core/paragraph, core/heading, core/image, core/quote, core/columns.
2. Формируйте валидные блочные комментарии: <!-- wp:heading {"level":2} --><h2>Заголовок</h2><!-- /wp:heading -->.
3. Верните ИСКЛЮЧИТЕЛЬНО HTML-разметку блоков без Markdown-обертки кода.
PROMPT;

      $maxRetries = 3;
      $attempt = 0;

      while ($attempt < $maxRetries) {
          $attempt++;

          $response = wp_remote_post($this->apiEndpoint, [
              'timeout' => 30,
              'headers' => [
                  'Authorization' => 'Bearer ' . $this->apiKey,
                  'Content-Type'  => 'application/json',
              ],
              'body' => wp_json_encode([
                  'model'       => 'gpt-4o-mini',
                  'messages'    => [
                      ['role' => 'system', 'content' => $systemPrompt],
                      ['role' => 'user', 'content' => $jsonPayload],
                  ],
                  'temperature' => 0.1,
              ]),
          ]);

          $code = wp_remote_retrieve_response_code($response);

          if ($code === 429) {
              // Экспоненциальная задержка: 2, 4, 8 секунд
              $sleepSeconds = (int) pow(2, $attempt);
              WP_CLI::log("Rate limit (429). Ожидание {$sleepSeconds} секунд перед повтором...");
              sleep($sleepSeconds);
              continue;
          }

          if ($code !== 200 || is_wp_error($response)) {
              throw new \RuntimeException("Сбой вызова AI API: HTTP {$code}");
          }

          $body = json_decode(wp_remote_retrieve_body($response), true);
          $content = (string) ($body['choices'][0]['message']['content'] ?? '');

          // Очистка от возможных случайных markdown-оберток
          $fence = chr(96) . chr(96) . chr(96);
          $cleanContent = trim(str_replace([$fence . 'html', $fence], '', trim($content)));

          return $cleanContent;
      }

      throw new \RuntimeException('Превышено число попыток повторного вызова AI API.');
  }

  private function flushMemoryCache(): void
  {
      global $wpdb, $wp_object_cache;

      $wpdb->queries = [];
      if (is_object($wp_object_cache)) {
          $wp_object_cache->group_ops      = [];
          $wp_object_cache->stats          = [];
          $wp_object_cache->memcache_debug = [];
          $wp_object_cache->cache          = [];
          if (method_exists($wp_object_cache, '__remoteset')) {
              $wp_object_cache->__remoteset();
          }
      }
      wp_cache_flush();
  }
}

// Регистрация команды в рантайме WP-CLI
if (defined('WP_CLI') && WP_CLI) {
  WP_CLI::add_command('agentic migrate-acf', AcfToGutenbergMigrationCommand::class);
}