Saltar a contenido

PDF-009A - WooCommerce Products Mapping API Candidate

Fecha: 2026-06-21

Estado: CANDIDATE API / DISENO / SIN LLAMAR API REAL / WOOCOMMERCE NO TOCADO / SYNC NO-GO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Destino funcional: La Directa WooCommerce

Owner: Gabi / Carlos Canu

1. Contexto

SOURCE-002 Productos quedo cargado y conciliado en PostgreSQL productivo dedicado con PDF-008I-G como rehearsal controlado VERDE.

Conteos oficiales vigentes:

Control Conteo
RAW 314
CORE 314
catalog 314
inventory current 314
inventory daily 314
economic 314
mart alerts 100
stock > 0 212
stock = 0 100
con precio/costo 312
sin precio/costo 2
marcas unicas 49
SKUs unicos 314

WooCommerce API todavia no fue tocada. La Directa no fue modificada. Sync, scheduler, cron y pipelines siguen NO-GO.

2. Objetivo

Preparar el mapping y diseno de integracion futura de productos desde PostgreSQL productivo dedicado hacia WooCommerce La Directa, sin ejecutar requests reales, sin leer secretos y sin modificar WooCommerce.

3. Alcance

Incluido:

  • mapping PostgreSQL -> WooCommerce;
  • reglas candidate de SKU, nombre, descripcion, precio, stock, categorias, marcas, peso, pack, unidad minima e imagenes;
  • estrategia create/update futura por sku;
  • idempotencia y relacion futura con wc_product_id;
  • dry-run plan, logs seguros, rollback logico, rate limits, paginacion y manejo de errores.

Excluido:

  • llamar WooCommerce API;
  • crear, actualizar o borrar productos en WooCommerce;
  • leer o imprimir secrets;
  • ejecutar SQL write;
  • activar sync, scheduler, cron o pipelines;
  • modificar La Directa;
  • usar staging o sandbox;
  • crear dumps, backups, snapshots, CSV o JSONL.

4. Documentacion Woo/La Directa Relevada

Documentos relevantes encontrados:

Documento Lectura
PDF-008A-SOURCE-002-PRODUCTS-WOOCOMMERCE-READY-CANDIDATE.md Mapping previo conceptual a catalogo WooCommerce-ready; no disena API candidate completa.
SOURCE-002B-WOOCOMMERCE-IMAGENES.md Fuente complementaria real de imagenes por SKU; consulta /wp-json/wc/v3/products historicamente para imagen destacada.
SOURCE-002-SGC-PRODUCTOS.md Autoridad de maestro de productos; tenant_id + SKU canonico; 81 campos.
SOURCE-002-FUTURE-LAYER-MAPPING.md Separacion conceptual de producto, stock, economia, logistica y politica comercial.
SOURCE-002-ECONOMIC-LAYER.md Decision de listas normalizadas y semantica de costo/precio.
docs/tenants/ladirecta/README.md y TENANT.md Tenant ladirecta en foundation, con integraciones futuras sin secretos.
WOOCOMMERCE-OBSERVABILITY-STRATEGY-INTAKE.md Separacion OpenClaw/La Directa; no consultar DB WooCommerce desde OpenClaw; productor seguro futuro requerido para metricas internas.
docs/tenants/ladirecta/api/README.md Placeholder; no hay API propia creada para el tenant.

Decisiones vigentes:

  • SOURCE-002 es fuente comercial para producto, precio, stock, marca, proveedor y logistica.
  • WooCommerce puede ser fuente complementaria de imagenes, no fuente primaria de precio, stock o costo.
  • La clave funcional de cruce es sku.
  • Categorias y marcas no tienen regla final WooCommerce aprobada.
  • wc_product_id sigue UNKNOWN y debe ser campo futuro de relacion.

Gaps:

  • no existe mapping API final aprobado;
  • no existe script previo de sync API de productos para La Directa;
  • no hay reglas finales de categorias/marcas;
  • no hay regla final de publish/draft para sin precio, sin stock o sin imagen;
  • no hay credenciales validadas en este gate;
  • no hay URL/base endpoint autorizada para ejecutar.

5. Modelo SOURCE-002 Disponible

Tablas productivas disponibles:

  • business_observer.catalog_source_002_products;
  • business_observer.core_source_002_products;
  • business_observer.inventory_source_002_current;
  • business_observer.inventory_source_002_daily_snapshot;
  • business_observer.economic_source_002_products;
  • business_observer.mart_source_002_stock_alerts.

Columnas relevantes de catalog:

  • sku, name, description, regular_price, sale_price;
  • stock_quantity, manage_stock;
  • brand, weight_kg, volume_m3;
  • units_per_pack, min_units, sale_pack_quantity;
  • category_raw, subcategory_raw, woo_category_candidate;
  • woo_status_candidate, supplier_code, supplier_name;
  • quality_status, quality_notes, source_row_hash, sync_batch_id.

Validacion usada: documentacion oficial PDF-008G, PDF-008H y PDF-008I-G. No se ejecuto consulta SQL en este gate porque la evidencia documental vigente cubre los conteos requeridos.

6. Mapping PostgreSQL -> WooCommerce

PostgreSQL WooCommerce Regla candidate Req Default Riesgo Estado
catalog.sku sku trim, preservar exacto, clave de busqueda y upsert si n/a SKU distinto en Woo rompe idempotencia READY
catalog.name name usar nombre comercial desde Articulo si n/a nombres largos o duplicados READY
catalog.description description si existe usar; si no, componer ficha con marca, pack y unidad no name enriquecido falta descripcion larga real PENDING_RULE
catalog.description short_description resumen corto desde nombre + marca + pack no name texto comercial pendiente PENDING_RULE
catalog.regular_price regular_price decimal positivo a string con 2 decimales; candidato desde PrecioListaFinal si para publicar n/a regla comercial de lista final pendiente READY
catalog.sale_price sale_price solo si sale_price > 0 y menor que regular_price no omitido vigencia oferta no existe PENDING_RULE
inventory.stock_quantity stock_quantity entero >= 0; negativos bloquean payload si 0 stock vendible puede depender de deposito READY
constante manage_stock true si true Woo puede tener reglas por producto READY
derivado de stock stock_status instock si stock_quantity > 0, si no outofstock si outofstock politica sin stock pendiente READY
category_raw, subcategory_raw categories resolver a ids Woo futuros; hoy usar solo plan de mapping no categoria default pendiente no hay ids Woo ni taxonomia final PENDING_RULE
brand atributo/tag/meta atributo visible Marca; taxonomia si plugin existe no meta/tag plugin de marcas desconocido PENDING_RULE
weight_kg weight convertir kg a string decimal si > 0 no omitido unidad Woo puede requerir kg confirmada READY
volume_m3 dimensions no mapear a largo/ancho/alto; guardar meta hasta tener dimensiones no omitido Woo requiere length/width/height separados UNKNOWN
units_per_pack meta_data.units_per_pack entero si existe no omitido semantica comercial pendiente READY
min_units meta_data.min_sale_quantity entero si existe no omitido puede requerir plugin/regla frontend READY
sale_pack_quantity meta_data.sale_pack_quantity entero si existe no omitido puede requerir validacion carrito READY
woo_status_candidate status draft por defecto; publish solo con reglas GO si draft publicar sin decision humana PENDING_RULE
constante catalog_visibility visible solo si publicable; si no hidden o draft no visible para publish regla comercial pendiente PENDING_RULE
source_row_hash meta_data.source_row_hash usar para detectar cambios si n/a no debe exponerse al cliente READY
sync_batch_id meta_data.source_sync_batch_id trazabilidad batch si n/a metadata tecnica READY
supplier_code/name meta_data solo si se aprueba exponer internamente; no publico no omitido dato comercial sensible PENDING_RULE
futuro id wc_product_id persistido futuro por SKU no lookup por SKU no existe columna actual PENDING_RULE
imagenes SOURCE-002B images usar featured image futura si cruce por SKU confirmado no sin imagen fuente complementaria no validada para La Directa PENDING_RULE

7. Reglas Funcionales Candidate

  1. Productos sin precio:

  2. decision pendiente;

  3. candidate recomendado: excluir del payload de create/update publicable o enviar como draft solo si se aprueba revision humana;

  4. nunca publicar con precio 0 salvo decision comercial explicita.

  5. Productos sin stock:

  6. decision pendiente;

  7. candidate recomendado: mantener manage_stock=true, stock_quantity=0, stock_status=outofstock;

  8. status publish vs draft queda pendiente de negocio.

  9. Productos sin imagen:

  10. decision pendiente;

  11. candidate recomendado: permitir draft o publicar sin imagen solo si la regla comercial lo acepta;

  12. placeholder no autorizado en este gate.

  13. Categorias:

  14. Category y SubCategoria quedan como raw;

  15. se requiere tabla futura category_raw/subcategory_raw -> wc_category_id;

  16. hasta entonces, categoria default o PENDING_RULE.

  17. Marcas:

  18. usar atributo WooCommerce Marca si no hay plugin de taxonomia;

  19. si existe plugin de brands, mapear a taxonomia propia;

  20. fallback: tags o meta_data.brand.

  21. Pack/unidad minima:

  22. persistir como meta_data;

  23. no forzar regla de carrito hasta gate funcional separado.

  24. Stock:

  25. manage_stock=true;

  26. stock desde inventory_source_002_current.stock_quantity;
  27. stock_status derivado por cantidad;

  28. no asumir multi-deposito.

  29. Precio:

  30. regular_price desde catalog.regular_price / PrecioListaFinal;

  31. sale_price solo si existe valor seguro y menor que regular;
  32. vigencia de oferta queda pendiente.

8. Diseño API Candidate

Endpoint esperado:

  • base: WC_BASE_URL placeholder no secreto;
  • productos: /wp-json/wc/v3/products;
  • batch futuro opcional: /wp-json/wc/v3/products/batch.

Metodo:

  • lookup read-only futuro por sku;
  • si SKU existe, candidate update;
  • si SKU no existe, candidate create;
  • si existe duplicado por SKU en WooCommerce, FATAL y requiere resolucion manual.

Idempotencia:

  • clave primaria externa: sku;
  • cache local runtime futura: sku -> wc_product_id;
  • hash de payload sin campos volatiles para comparar cambios;
  • si source_row_hash y payload hash no cambian, no generar update.

Dry-run:

  • generar plan CREATE/UPDATE/SKIP/BLOCKED;
  • no ejecutar requests;
  • no persistir CSV/JSONL;
  • logs agregados sin payload sensible completo.

Paginacion y rate limits:

  • per_page=100;
  • paginar por page hasta respuesta vacia;
  • batch candidate maximo 25 productos por request si se usa endpoint batch;
  • pausa inicial recomendada 1s entre requests;
  • backoff exponencial 2/5/10/30s ante 429 o 5xx.

Errores recuperables:

  • 429, 500, 502, 503, timeout;
  • retry acotado y luego RETRY_EXHAUSTED.

Errores fatales:

  • credenciales ausentes;
  • 401/403;
  • SKU duplicado;
  • precio invalido;
  • payload sin SKU o nombre;
  • categoria requerida sin mapping;
  • respuesta sin id luego de create.

Rollback logico:

  • no hay rollback automatico en este gate;
  • futuro rollback debe usar auditoria previa por wc_product_id, sku, payload anterior y accion ejecutada;
  • para create, rollback logico candidate seria mover a draft, no borrar;
  • para update, restaurar ultimo payload conocido si fue capturado por gate.

Logs seguros:

  • permitido: timestamp, accion, sku, resultado, codigo HTTP, duracion, hash de payload, errores resumidos;
  • prohibido: consumer keys, passwords, tokens, connection strings, payloads completos con datos sensibles.

9. Gaps y Decisiones Pendientes

  • aprobar regla de regular_price final;
  • aprobar regla de sale_price y vigencia de oferta;
  • definir politica para sin precio, sin stock y sin imagen;
  • mapear categorias/subcategorias a ids Woo;
  • confirmar si marca usa atributo, taxonomia de plugin, tag o meta;
  • definir moneda y formato final;
  • definir si supplier_* puede viajar como meta interna;
  • agregar campo futuro wc_product_id y auditoria de sync;
  • validar credenciales sin imprimir secretos en gate separado;
  • definir URL/base endpoint sin hardcodear secrets;
  • definir muestra controlada de SKUs antes de cualquier write real.

10. Criterios GO / NO-GO

GO para proximo gate solo si:

  • safe point limpio;
  • credenciales presentes validadas sin imprimir valores;
  • URL WooCommerce confirmada;
  • dry-run read-only autorizado explicitamente;
  • muestra de SKUs aprobada;
  • categorias y reglas de publicacion resueltas o marcadas como draft;
  • logs seguros revisados.

NO-GO si:

  • falta autorizacion para API;
  • se intenta create/update/delete real;
  • faltan reglas de precio o categoria para publicar;
  • aparecen secrets en consola o Git;
  • se pretende activar sync, scheduler, cron o pipelines;
  • se pretende usar sandbox o staging fuera de alcance.

11. Paquete Candidate

Artefactos creados:

  • infra/business-observer/production/woocommerce/products/PDF-009A/README.md
  • infra/business-observer/production/woocommerce/products/PDF-009A/product-payload-mapping.candidate.md
  • infra/business-observer/production/woocommerce/products/PDF-009A/product-sync-dry-run-plan.candidate.md
  • infra/business-observer/production/woocommerce/products/PDF-009A/product-sync-config.example.env
  • infra/business-observer/production/woocommerce/products/PDF-009A/product-sync-pseudocode.candidate.py

Todos son candidate. No contienen secrets y no ejecutan requests reales.

12. Confirmacion De Alcance

Durante este gate:

  • no se llamo WooCommerce API;
  • no se creo, actualizo ni borro producto WooCommerce;
  • no se modifico La Directa;
  • no se ejecuto sync;
  • no se ejecuto scheduler;
  • no se ejecuto cron;
  • no se ejecutaron pipelines;
  • no se ejecuto SQL write;
  • no se modifico PostgreSQL produccion;
  • no se modifico PostgreSQL staging;
  • no se uso sandbox;
  • no se leyeron secrets;
  • no se imprimieron consumer keys, passwords, tokens ni connection strings;
  • no se crearon dumps, backups, snapshots, CSV ni JSONL.

13. Proximo Gate Recomendado

PDF-009B WooCommerce credentials/read-only dry-run preflight

Alcance recomendado:

  • validar presencia de credenciales sin imprimir valores;
  • ejecutar solo llamadas read-only si se autoriza explicitamente;
  • buscar por SKU una muestra controlada;
  • validar paginacion/rate limit sin writes;
  • producir plan dry-run CREATE/UPDATE/SKIP/BLOCKED;
  • mantener create/update/delete, sync, scheduler, cron y pipelines en NO-GO.

14. Estado Final

Estado final: VERDE DOCUMENTAL / CANDIDATE PREPARADO.

La API WooCommerce sigue NO TOCADA.