Saltar a contenido

PDF-009E - WooCommerce Product Rules Pre-Write Candidate

Fecha: 2026-06-22

Estado: PUBLICADO EN origin/main / DESPLEGADO EN KNOWLEDGE PORTAL / HTTP PUBLICO 200 / DISENO DOCUMENTAL / DRY-RUN RULES / SIN API NUEVA / SIN WRITES

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Destino funcional: La Directa WooCommerce

Owner: Gabi / Carlos Canu

A. SAFE POINT inicial

Control Resultado
git status -sb ## main...origin/main limpio al cierre post-deploy.
git rev-parse HEAD 00dcc8b30998e3a4cf88fe8da983199ed0202b63
git rev-parse origin/main 00dcc8b30998e3a4cf88fe8da983199ed0202b63
git log -3 --oneline 00dcc8b docs: add pdf-009e woocommerce pre-write rules; f400ca2 docs: align pdf-009c pdf-009d post-deploy state; 2bc2434 docs: add pdf-009d woocommerce lifecycle stock policy
git diff --check inicial PASS

El repo quedo alineado con origin/main al cierre post-deploy.

El VPS quedo alineado a 00dcc8b30998e3a4cf88fe8da983199ed0202b63 y el Knowledge Portal desplegado, con HTTP local VPS 200 y HTTP publico 200.

B. Estado documental leido

Documentos leidos:

  • docs/governance/PROJECT-CONSTITUTION.md
  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/tenants/alpuntodeventa/business-observer/blueprints/PRODUCT-BLUEPRINT.md
  • docs/tenants/alpuntodeventa/business-observer/BUSINESS-OBSERVER-DATA-CONTRACT-001.md
  • docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-002-PRODUCTOS-PRODUCTS-AUTHORITY.sql
  • docs/tenants/alpuntodeventa/business-observer/SOURCE-002-FUTURE-LAYER-MAPPING.md
  • docs/tenants/alpuntodeventa/business-observer/production/PDF-009B-1-WOOCOMMERCE-PRODUCT-API-EXTENSION-DESIGN.md
  • docs/tenants/alpuntodeventa/business-observer/production/PDF-009B-WOOCOMMERCE-READ-ONLY-PREFLIGHT.md
  • docs/tenants/alpuntodeventa/business-observer/production/PDF-009C-SOURCE-002-WOOCOMMERCE-COMPARISON-DRY-RUN.md
  • docs/tenants/alpuntodeventa/business-observer/production/PDF-009D-WOOCOMMERCE-PRODUCT-LIFECYCLE-STOCK-SYNC-POLICY.md

Confirmacion documental:

  • PDF-009B valido API WooCommerce read-only.
  • PDF-009C comparo muestra SOURCE-002 contra WooCommerce sin writes.
  • PDF-009D separo Stock Sync frecuente de Product Catalog Sync controlado y dejo DE BAJA, sin stock, sin precio, sin imagen, categorias, marca, precio ecommerce/oferta y wc_product_id como reglas pendientes.
  • La autoridad vigente SOURCE-002 filtra Estado = 'ACTIVO'; por lo tanto, la regla DE BAJA queda definida para un futuro origen/capa que exponga ese estado, no como dato observable en el SELECT vigente.

C. Principios preservados

  • WooCommerce native first.
  • PostgreSQL/OpenClaw es la fuente fuerte para producto, stock, economia, proveedor, trazabilidad y analitica.
  • WooCommerce no se convierte en ERP.
  • WooCommerce no debe almacenar datos sensibles.
  • Costos, proveedor, descuentos de compra, margenes, listas multiples, calidad interna, historiales economicos y auditoria sensible quedan PostgreSQL only.
  • meta_data privada debe ser minima, puntual y no sensible.
  • Filtros visibles no deben depender de meta_data pesada.
  • El stock frecuente debe usar payload minimo y no tocar catalogo.

D. Reglas READY

Dominio Regla candidate Estado
Categoria Category se mapea a product_cat nivel padre cuando exista mapping aprobado a ID o slug WooCommerce. READY_CONCEPT / PENDING_MAPPING
Subcategoria SubCategoria se mapea como hija de Category en product_cat cuando exista mapping aprobado. Si falta subcategoria, usar solo categoria padre. READY_CONCEPT / PENDING_MAPPING
Creacion de categorias No crear categorias automaticamente en un write de producto salvo autorizacion explicita del gate. READY
Marca Usar atributo visible Marca como primera opcion. No crear taxonomia navegable custom en este gate. READY
Marca futura Reabrir taxonomia navegable solo si negocio necesita SEO, landing pages o navegacion avanzada por marca que el atributo Woo no cubra. READY
Estado ACTIVO ACTIVO habilita elegibilidad, pero no implica publish automatico. Debe pasar precio, categoria, stock e imagen segun reglas. READY
Estado DE BAJA No borrar. Desactivar en WooCommerce. READY
DE BAJA accion Usar status=draft como candidate principal. catalog_visibility=hidden solo no alcanza porque puede dejar accesos directos o compra segun configuracion. READY
Producto sin stock Crear o mantener como draft en catalog sync si el resto esta completo; stock_quantity=0, stock_status=outofstock, manage_stock=true. No publicar hasta regla comercial posterior. READY
Producto sin precio BLOCKED. No crear ni actualizar como vendible si el precio ecommerce base es nulo, cero, negativo o no parseable. READY
Producto sin imagen Crear o mantener como draft si precio/categoria/stock estan OK. No publicar sin imagen real o placeholder aprobado. READY
Precio ecommerce base Usar PrecioListaFinal como regular_price candidate. PostgreSQL conserva precision fuente; Woo recibe string decimal de precio final ecommerce. READY
Oferta No enviar sale_price por defecto. Solo aplicar PrecioOfertaFinal si hay aprobacion comercial y el valor es positivo y menor que regular_price. READY_WITH_GUARD
wc_product_id futuro Guardar la relacion tenant_id + sku -> wc_product_id en PostgreSQL/OpenClaw o tabla de control de sync, no como verdad publica Woo. READY
Woo solo Producto existente en WooCommerce y ausente en PostgreSQL/OpenClaw queda BLOCKED / MANUAL_REVIEW; no delete automatico. READY
Stock frecuente Payload minimo: stock_quantity, stock_status, manage_stock. READY
Datos sensibles Costos, proveedor, descuentos, margenes y listas multiples quedan fuera del payload Woo. READY

E. Reglas PENDING

Pendiente Por que falta Efecto
Mapping real Category/SubCategoria -> product_cat No existe tabla/lista aprobada de categorias WooCommerce, IDs o slugs finales. Bloquea publish y write final de catalogo.
Politica de publicacion sin stock Este candidate propone draft, pero negocio puede querer publicar outofstock. Requiere aprobacion comercial.
Politica de imagen Falta decidir si se acepta placeholder, banco de imagenes, carga manual o bloqueo total. Bloquea publish automatico.
Vigencia de oferta PrecioOfertaFinal no trae fecha de inicio/fin en la autoridad leida. sale_price queda protegido por guard.
Lista ecommerce alternativa PrecioListaFinal queda como base candidate; no se confirmo que PrecioL1 u otra lista sea la lista ecommerce. Puede cambiar regular_price futuro.
Regla editorial de descripcion Falta definir description y short_description finales. Puede permitir create draft, pero bloquea publish cuidado.
Imagenes por SKU No hay fuente aprobada de imagen principal/galeria ni naming convention. Bloquea publish.
Modelo fisico wc_product_id Falta tabla/control definitivo y migracion futura. No bloquea dry-run; bloquea sync eficiente real.

F. Casos BLOCKED

Caso Accion candidate Motivo
SKU vacio, nulo o duplicado BLOCKED Rompe identidad tenant_id + sku.
SKU sin precio ecommerce valido BLOCKED Woo no debe publicar producto vendible sin precio correcto.
SKU sin categoria mapeada BLOCKED_FOR_PUBLISH Mala navegacion y filtros; puede quedar draft solo con aprobacion.
SKU sin imagen DRAFT / BLOCKED_FOR_PUBLISH Evita experiencia frontend pobre.
SKU DE BAJA DEACTIVATE_DRAFT No delete automatico, preservar historial.
SKU en Woo y ausente en PostgreSQL/OpenClaw BLOCKED / MANUAL_REVIEW Evita desactivar productos validos por falso negativo.
PrecioOfertaFinal >= regular_price sale_price omitido Oferta invalida o no competitiva.
PrecioOfertaFinal <= 0 sale_price omitido No hay oferta valida.
Categoria candidata requiere crear termino Woo BLOCKED_UNTIL_CATEGORY_GATE No crear taxonomia por efecto lateral del write producto.
Marca vacia CREATE_DRAFT_OR_BLOCKED_FOR_PUBLISH Atributo visible incompleto; negocio decide si es publicable.
Campo sensible pedido para Woo BLOCKED Costos/proveedor/descuentos/margenes/listas multiples son PostgreSQL only.

G. Rule matrix

Regla Entrada Salida Woo candidate Decision
Identidad SKU sku READY
Nombre Articulo name READY
Categoria padre Category categories[].id o categories[].slug padre PENDING_MAPPING
Subcategoria SubCategoria categories[].id o categories[].slug hija PENDING_MAPPING
Marca Marca atributo visible Marca READY
Estado activo Estado = ACTIVO elegible para publish si pasa gates READY
Estado baja Estado = DE BAJA futuro status=draft READY
Stock positivo Stock > 0 stock_quantity, stock_status=instock READY
Stock cero Stock = 0 stock_quantity=0, stock_status=outofstock, status=draft READY
Precio base PrecioListaFinal regular_price READY
Oferta PrecioOfertaFinal sale_price solo con guard comercial READY_WITH_GUARD
Peso PesoxUnidad weight READY
Pack/minimos Unidades_x_Bulto, CantVtaMin, CantVentaAgrupada meta_data privada minima READY
Imagen fuente futura aprobada images[] PENDING_SOURCE
Proveedor/costos campos SOURCE-002 economicos/proveedor no enviar READY

H. Payload decision matrix

Campo payload Fuente Incluir en catalog sync Incluir en stock sync Regla
sku SKU YES lookup/cache only Identidad canonica.
name Articulo YES NO No tocar en stock sync.
status reglas PDF-009E YES NO publish solo si pasa gates; draft para baja/sin stock/sin imagen.
catalog_visibility reglas PDF-009E opcional NO No usar como reemplazo de draft para DE BAJA.
regular_price PrecioListaFinal YES NO Bloquea si nulo/cero/invalido.
sale_price PrecioOfertaFinal guarded NO Solo oferta aprobada, positiva y menor que regular.
manage_stock regla fija YES YES true.
stock_quantity Stock YES inicial YES Payload minimo frecuente.
stock_status derivado de Stock YES inicial YES instock si Stock > 0, outofstock si Stock = 0.
categories mapping futuro YES si resuelto NO No crear terminos automaticamente.
attributes.Marca Marca YES NO Atributo visible, no variacion.
images fuente futura YES si resuelto NO Bloquea publish si falta imagen aprobada.
weight PesoxUnidad YES si valido NO Campo nativo Woo.
meta_data.units_per_pack Unidades_x_Bulto opcional minimo NO Privado, no filtro.
meta_data.min_sale_quantity CantVtaMin opcional minimo NO No implica regla carrito sin plugin/gate.
meta_data.sale_pack_quantity CantVentaAgrupada opcional minimo NO No implica regla carrito sin plugin/gate.
costos/proveedor/margenes/listas SOURCE-002 economico NO NO PostgreSQL only.
source_row_hash futuro preferir PostgreSQL NO Evitar metadata frecuente.
sync_batch_id futuro preferir PostgreSQL NO Evitar metadata frecuente.
wc_product_id Woo response futuro PostgreSQL control PostgreSQL control No es campo publico.

I. Payload final candidate

I.1 Producto publicable

Producto ACTIVO, precio valido, stock positivo, categoria mapeada, marca informada e imagen aprobada:

json { "sku": "0135", "name": "Mani Pelado Kra x110gr", "status": "publish", "regular_price": "1825.84", "manage_stock": true, "stock_quantity": 554, "stock_status": "instock", "categories": [ { "id": 0 } ], "attributes": [ { "name": "Marca", "visible": true, "variation": false, "options": ["KRACHITOS"] } ], "images": [ { "id": 0 } ] }

id = 0 es placeholder documental. El dry-run final debe reemplazarlo por IDs reales aprobados o bloquear el write.

I.2 Producto sin stock

json { "sku": "2442", "name": "Pudding de Choco c/chip x300 grs", "status": "draft", "regular_price": "2020.90", "manage_stock": true, "stock_quantity": 0, "stock_status": "outofstock" }

I.3 Producto DE BAJA

json { "status": "draft" }

I.4 Stock sync frecuente

json { "manage_stock": true, "stock_quantity": 212, "stock_status": "instock" }

J. Blocked cases matrix

Bloqueo Deteccion Salida esperada
Categoria sin mapping Category/SubCategoria sin ID/slug aprobado BLOCKED_FOR_PUBLISH
Precio invalido regular_price <= 0 o no numerico BLOCKED
Oferta invalida sale_price <= 0 o sale_price >= regular_price omitir sale_price
Imagen ausente sin imagen real o placeholder aprobado DRAFT
Stock cero Stock = 0 DRAFT + outofstock
Baja comercial estado futuro DE BAJA DEACTIVATE_DRAFT
Woo solo SKU existe en Woo y no en PostgreSQL/OpenClaw MANUAL_REVIEW
Termino Woo inexistente categoria o marca requiere creacion BLOCKED_UNTIL_TAXONOMY_GATE
Campo sensible en payload costo/proveedor/margen/lista multiple remover campo y marcar BLOCKED_POLICY

K. Pending commercial decisions

Decision Recomendacion candidate Necesita aprobacion
Categoria/subcategoria final Arbol Category -> SubCategoria en product_cat YES
Marca Atributo visible Marca NO, salvo que se quiera taxonomia navegable
Sin stock draft hasta reposicion/regla comercial YES para publicar out-of-stock
Sin imagen draft hasta imagen/placeholder aprobado YES
Precio ecommerce PrecioListaFinal YES si se cambia a PrecioL1 u otra lista
Oferta No publicar oferta sin vigencia aprobada YES
Descripciones Construccion editorial desde Articulo y reglas futuras YES
Placeholder de imagen No usar sin aprobacion YES
Categoria auto-create No crear en write producto YES para habilitar gate propio

L. Final write gate prerequisites

Antes de cualquier write WooCommerce real debe existir:

  • SAFE POINT nuevo limpio.
  • Autorizacion explicita de write gate.
  • Dry-run final completo sobre muestra o universo definido.
  • Mapping aprobado Category/SubCategoria -> product_cat con IDs/slugs reales.
  • Politica aprobada para sin stock, sin precio y sin imagen.
  • Politica aprobada de oferta y vigencia.
  • Fuente o placeholder aprobado de imagenes.
  • Modelo de control para wc_product_id futuro.
  • Confirmacion de payload sin costos, proveedor, margenes, descuentos ni listas multiples.
  • Confirmacion de logs no sensibles.
  • Plan de rollback logico sin delete automatico.
  • Separacion explicita entre catalog sync y stock sync.
  • Validacion git diff --check y mkdocs build --strict para documentacion.

M. Decision

PDF-009E deja las reglas pre-write en estado candidate:

  • suficientes para preparar un dry-run final de payload;
  • insuficientes para ejecutar writes reales porque faltan mapping de categorias, politica de imagenes, aprobacion comercial de stock cero/ofertas y modelo persistente de wc_product_id;
  • alineadas con WooCommerce native first, meta_data privada minima y PostgreSQL/OpenClaw como fuente fuerte.

N. Proximo paso recomendado

Abrir gate separado PDF-009F para construir el payload dry-run final con:

  • mapping de categorias resuelto o matriz explicita de categorias bloqueadas;
  • muestra representativa con producto publicable, sin stock, sin imagen, sin precio y baja conceptual;
  • payloads finales CREATE_DRAFT, CREATE_PUBLISH, UPDATE_CATALOG, UPDATE_STOCK, DEACTIVATE_DRAFT y MANUAL_REVIEW;
  • cero writes.

O. Confirmacion de alcance

Durante este gate documental no se ejecuto API nueva, no se hicieron writes, no se modifico WooCommerce, no se modifico La Directa, no se toco PostgreSQL con writes, no se imprimieron secretos, no se mostro .env, no se ejecuto sync, no se ejecuto scheduler, no se ejecuto cron y no se ejecutaron pipelines. El cierre documental posterior quedo publicado en origin/main y desplegado en Knowledge Portal sobre HEAD 00dcc8b30998e3a4cf88fe8da983199ed0202b63.