Migrar desde WooCommerce Product Add-Ons

POM Tweaks puede copiar un catálogo existente de la extensión oficial WooCommerce Product Add-Ons a POM Product Add-Ons. La migración conserva la configuración de origen, convierte las etiquetas de opciones repetidas en Opciones reutilizables compartidas, verifica cada registro importado antes de activar el ajuste y puede restaurar los datos de POM que existían antes de la migración.

Esta guía está dirigida a administradores de tienda con acceso a WP-CLI. Planifica el cambio definitivo de la tienda durante una ventana de mantenimiento para que los clientes no vean nunca dos sistemas de complementos ni una configuración sin probar.

Antes de empezar

• Haz una copia de seguridad de la base de datos del sitio seleccionado, de los ajustes de POM Tweaks, de las subidas existentes de Product Add-Ons y del almacenamiento de archivos privados configurado desde un único punto de recuperación coherente.
• Mantén activos WooCommerce y POM Tweaks.
• Mantén instalada la extensión oficial hasta que la migración y la verificación de la tienda hayan finalizado. Sus datos se pueden migrar tanto si la extensión está activa como inactiva.
• Termina las ediciones pendientes en la extensión oficial antes de empezar.
• Ejecuta cada comando para exactamente un sitio. En multisitio, usa --url=<site-url> o un --blog_id=<id> explícito; el comando nunca recorre la red.
• Ejecuta WP-CLI en el entorno PHP del sitio con un usuario del sistema de archivos que pueda leer los ajustes existentes de POM Tweaks y escribir el archivo de activación. El acceso concedido al servidor web no se aplica automáticamente a un comando ejecutado en el host.

Qué se copia

La migración copia:

• grupos globales publicados y en borrador, incluidos los grupos que aún no tienen campos;
• asignaciones a todos los productos o a categorías de producto exactas;
• campos de nivel de producto y de variación;
• el ajuste de producto que excluye los grupos globales;
• orden de los campos, estado obligatorio, encabezados, descripciones, marcadores de posición, restricciones, valores predeterminados y límites de tipo de archivo;
• precios fijos, basados en cantidad y basados en porcentaje;
• multiplicadores de persona y bloque de WooCommerce Bookings, incluido el multiplicador de noche heredado de Accommodation Bookings;
• etiquetas de opciones, imágenes, precios, visibilidad y selecciones predeterminadas.

Las opciones con la misma etiqueta, ignorando mayúsculas y espacios en blanco repetidos, se convierten en una única Opción reutilizable, incluso cuando aparecen en campos o grupos diferentes. Cada uso conserva su propio precio, imagen, visibilidad, orden y estado predeterminado. Después del cambio, desactivar esa Opción reutilizable desactiva u oculta cada uso vinculado según su ajuste de disponibilidad de POM.

La migración no modifica ni elimina los grupos, los campos de producto ni los datos históricos de pedidos de la extensión oficial. Un grupo de origen asignado a una categoría sigue limitado a esa categoría exacta; no se añade comportamiento de subcategorías durante la conversión.

Los archivos subidos históricos no se mueven en bloque mediante el comando de configuración. Después del cambio de la tienda, una vista autorizada del carrito o del pedido copia una subida heredada local reconocida al almacenamiento privado y registra su relación con el pedido sin volver a escribir los metadatos históricos visibles para el cliente. Conserva las subidas de origen durante la ventana de reversión. En Nginx u otro servidor que no respete los archivos de denegación de directorio, pide al host que bloquee el acceso web directo a las ubicaciones de subida heredadas antes de mostrar pedidos históricos a través de POM.

Ejecutar la comprobación previa

Desde el directorio de instalación de WordPress, ejecuta:

wp pomtweaks product-add-ons migrate --url=https://example.test --dry-run

El resultado informa del número de grupos, configuraciones de producto, campos, usos de opciones y Opciones reutilizables únicas. Una ejecución en seco no crea entradas, no actualiza productos, no cambia opciones ni activa el ajuste.

Para una importación apta, la ejecución en seco también comprueba el acceso a los ajustes de activación antes de cambiar ningún registro. Un error de acceso identifica el archivo configurado, su ruta resuelta existente en el sistema de archivos y el ID de usuario efectivo de CLI cuando está disponible. Los enlaces simbólicos y los montajes compartidos pueden exponer el mismo almacenamiento bajo rutas diferentes; usa el árbol de ajustes configurado del framework en lugar de crear una segunda copia en otra ubicación. Una comprobación previa correcta no impide que los permisos o la disponibilidad del almacenamiento cambien durante la importación.

La comprobación previa se detiene antes de cualquier escritura cuando detecta alguna de estas condiciones:

• Un tipo de campo de origen personalizado no tiene equivalente en POM Product Add-Ons. Sustituye o elimina ese campo en la extensión oficial y vuelve a ejecutar la comprobación previa.
• Un producto de origen ya tiene una definición local, exclusión de grupo, exclusión global o sobrescritura de traducción propiedad de POM. Revisa esos ID de producto antes de decidir qué versión debe prevalecer.

Si los datos oficiales deben sustituir las definiciones locales de POM existentes, repite la migración real con --overwrite-existing. POM Tweaks almacena los valores de POM anteriores para que la limpieza pueda restaurarlos.

Migrar un sitio

Después de una comprobación previa limpia, ejecuta:

wp pomtweaks product-add-ons migrate --url=https://example.test

Para un ID de blog de multisitio explícito, usa:

wp pomtweaks product-add-ons migrate --blog_id=13

El comando importa los registros, vuelve a leer cada registro de POM publicado y lo compara con el origen oficial actual. Activa Product Add-Ons en Settings → POM Tweaks → E-Commerce → Products solo después de que las definiciones, los ámbitos, las exclusiones de producto, las Opciones reutilizables, los ID de compatibilidad y la propiedad del sistema coincidan. Volver a ejecutar una migración completada verifica de nuevo la importación conservada. Usa --force solo cuando se hayan añadido registros de origen o hayan recibido ediciones que no sean de identidad, como un cambio de precio o de descripción, y los registros de POM ya importados deban actualizarse; esto sustituye las ediciones realizadas directamente en esos registros de POM importados.

Ejecuta la compuerta de cambio de solo lectura después de la migración:

wp pomtweaks product-add-ons verify --url=https://example.test

El comando sale correctamente solo cuando todos los registros oficiales aptos siguen coincidiendo con sus registros de POM publicados y el ajuste Product Add-Ons está activado para este sitio. Hay un informe JSON disponible con --format=json. Una discrepancia, un estado de migración ausente, un registro importado obsoleto o un ajuste desactivado devuelven un estado de salida distinto de cero, de modo que el comando puede detener de forma segura un script de despliegue antes de que se desactive la extensión oficial.

Si se eliminaron grupos o campos de origen después de una migración completada, usa la limpieza seguida de una migración nueva en lugar de --force. Esa secuencia también elimina los registros importados que ya no tienen una contraparte de origen.

Revisar antes del cambio de la tienda

Mientras la extensión oficial siga activa, los controladores de tienda y de precios de POM permanecen inactivos para evitar campos y cargos duplicados. Aun así, puedes revisar los registros de administración importados.

1. Abre Products → Product Add-Ons.
2. Compara cada grupo global importado con su grupo de origen oficial.
3. Abre Reusable Choices y confirma que las etiquetas repetidas se vincularon intencionadamente.
4. Revisa las etiquetas que se parecen pero representan conceptos diferentes. Duplica o sustituye una opción cuando esos usos deban seguir siendo independientes.
5. Comprueba el panel Product Add-Ons en productos simples y variables representativos.
6. Confirma el estado del grupo, el ámbito de categoría, el orden de los campos, los valores predeterminados, los precios, las imágenes, las restricciones y los tipos de archivo.

Cambiar la tienda

1. Pon la tienda en su modo normal de mantenimiento o de publicación controlada.
2. Ejecuta el comando verify y exige un estado de salida correcto.
3. Desactiva la extensión oficial WooCommerce Product Add-Ons en el ámbito del sitio donde esté activa. No la elimines todavía. Si la extensión está activa en red, no uses un cambio por sitio: primero cambia su estrategia de activación en una ventana de mantenimiento de red planificada por separado.
4. Vuelve a ejecutar verify. Los metadatos de origen siguen estando disponibles mientras la extensión oficial está inactiva, de modo que la misma comparación de solo lectura debe seguir superándose.
5. Limpia las cachés de página y CDN que usa la tienda. Las cachés de Product Add-Ons de POM y el índice de asignaciones se invalidan con la propia migración.
6. Abre un producto simple y uno variable que contengan campos importados.
7. Prueba la validación obligatoria, los valores predeterminados, las opciones ocultas, todos los métodos de precio, los cambios de cantidad, la edición del carrito, los bloques de Carrito y Pago, y un pedido de prueba.
8. Confirma que el pedido contiene las etiquetas, los valores y el total de complementos aceptados.
9. Compara el mismo producto representativo mediante la API de Product Add-Ons v1 o v2 y la API nativa de productos de WooCommerce antes y después del cambio.
10. Envía un webhook de pedido de prueba y confirma que sus metadatos de complementos por línea y cualquier propiedad addon_price, type o table_id esperada conservan su forma anterior.
11. Reabre el tráfico normal de clientes solo después de que los totales, las respuestas de la API, los datos del webhook y los detalles del pedido coincidan con el comportamiento de origen.

Cuando Bookings forme parte de la tienda, compara también una reserva con precio por persona, una reserva con precio por bloque o por noche y un campo que combine ambos multiplicadores. Cambia la fecha de la reserva, el recurso, la duración y las personas antes de añadirla al carrito y confirma que POM y la extensión de origen producen el mismo total.

Resultado esperado

POM Product Add-Ons se convierte en el único controlador de complementos de la tienda. Los campos globales y locales del producto conservan sus asignaciones y su comportamiento de precios, las etiquetas de origen repetidas se gestionan de forma centralizada como Opciones reutilizables, y los datos de la extensión original siguen disponibles para la reversión.

Un mínimo o máximo oficial de 0 significa que ese límite está ausente. El importador y la API de escritura compatible con la oficial convierten los límites cero explícitos al límite vacío de POM. En el editor nativo, un Maximum vacío significa ilimitado; un 0 numérico es un máximo real. Incluye un importe positivo en la comprobación de la tienda para cualquier campo de precio definido por el cliente migrado.

Los enlaces add-to-cart antiguos sin firmar que contienen valores addon-<product>-<position> no son credenciales de compra directa para POM. Para enlaces en sitios web externos o propuestas, genera un enlace de compra directa firmado y sustituye la URL completa.

Revertir o limpiar la importación

Primero, previsualiza la limpieza:

wp pomtweaks product-add-ons cleanup --url=https://example.test --dry-run

Para una reversión en vivo, reactiva primero la extensión oficial cuando se requiera continuidad para el cliente y luego ejecuta:

wp pomtweaks product-add-ons cleanup --url=https://example.test --yes

La limpieza restaura los valores de producto locales de POM y el estado de activación del ajuste que existían antes de la migración. Los grupos importados y las Opciones reutilizables pasan a la papelera de WordPress, donde siguen siendo recuperables. La configuración y los pedidos históricos de la extensión oficial no cambian.

Usa la limpieza durante la ventana de reversión de la migración. Si los grupos importados o las Opciones reutilizables se han reutilizado desde entonces en nuevas configuraciones de POM, revisa esas relaciones y realiza una reversión manual selectiva en lugar de enviar a la papelera todos los registros importados.

Verificar los ID de compatibilidad

Después de la migración, inspecciona los ID numéricos conservados del sitio seleccionado:

wp pomtweaks product-add-ons legacy-ids --url=https://example.test --format=json

El informe analiza los grupos de Product Add-Ons y los metadatos de definición local de producto exacta en páginas delimitadas. Informa del número de campos y grupos activos, las asignaciones conservadas, el estado de la suma de comprobación y cualquier conflicto de UUID o de ID numérico sin cambiar ninguna definición. En multisitio, ejecútalo una vez por sitio con la URL de ese sitio; nunca lee ni escribe un registro de red.

Cuando el informe solo identifique un registro derivado ausente o dañado y las identidades activas sean inequívocas, reconstrúyelo con:

wp pomtweaks product-add-ons legacy-ids --url=https://example.test --rebuild --format=json

La reconstrucción es idempotente. Conserva las reservas retiradas y nunca cambia un ID de campo o grupo activo para ocultar una colisión. Si el informe contiene una colisión activa, mantén sin cambios ambas definiciones afectadas, revisa su origen o paquete de importación y elimina o sustituye la referencia en conflicto antes de guardar de nuevo.

Solución de problemas

• No se encontraron datos de origen: confirma que el comando apunta al sitio correcto y que los grupos o campos de producto de la extensión oficial existen en ese sitio.
• Tipos de campo no admitidos: es posible que una integración de terceros haya añadido un tipo personalizado. Conviértelo a un tipo de campo oficial estándar antes de la migración.
• Conflicto de datos de POM existentes: inspecciona los ID de producto indicados. Usa --overwrite-existing solo cuando la versión de origen deba sustituir esas definiciones locales de POM.
• Los campos de POM no aparecen después de la migración: confirma que la extensión oficial está inactiva, que Product Add-Ons está activado en POM Tweaks, que el grupo está publicado y que su ámbito incluye el producto.
• No se pueden escribir los ajustes de activación: mantén activa la extensión oficial y ejecuta verify. Si todos los recuentos de origen coinciden con sus recuentos verificados y el único problema es tweak_disabled, activa Product Add-Ons en los ajustes de POM Tweaks del sitio seleccionado y vuelve a ejecutar verify. Como alternativa, restablece el acceso de CLI al mismo árbol de ajustes y repite migrate sin --force ni --overwrite-existing; una importación ya verificada se vuelve a comprobar antes de la activación. No repitas la importación ni ejecutes la limpieza únicamente para resolver el acceso al sistema de archivos.
• Una opción con el mismo nombre no debería compartirse: crea una Opción reutilizable independiente y sustituye la pertenencia de ese campo concreto antes del cambio.
• Un comando se interrumpió: vuelve a ejecutar la ejecución en seco y repite la migración. Las asignaciones de origen guardadas permiten que el comando reanude sin duplicar los registros completados.
• La verificación informa de un origen obsoleto: se eliminó un grupo oficial, una configuración de producto o una etiqueta de opción después de la importación. Ejecuta la limpieza y realiza una migración nueva para que los registros importados obsoletos se eliminen de forma segura.
• La verificación informa de una discrepancia: mantén activa la extensión oficial. Usa migrate --force para adiciones y ediciones de origen que no sean de identidad, como precios o descripciones. Usa la limpieza seguida de una migración nueva para eliminaciones y para cambios de nombre de etiquetas de opción, porque las etiquetas definen la identidad de origen de la opción reutilizable.
• Colisión de ID de compatibilidad: el entero importado solicitado ya pertenece a otro UUID en este sitio. No lo reetiquetes ni lo fuerces a vincularse; clónalo con identidades nuevas o elimina la referencia importada en conflicto y repite la comprobación previa.

Relacionado: Crear grupos y opciones reutilizables, Compatibilidad con Product Add-Ons oficial y API REST de gestión.