PDF-009D - WooCommerce Product Lifecycle and Stock Sync Policy¶

Fecha: 2026-06-22

Estado: PUBLICADO EN origin/main / DESPLEGADO EN KNOWLEDGE PORTAL / HTTP PUBLICO 200 / DISENO DOCUMENTAL / 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 [ahead 1]`
`git rev-parse HEAD`	`79fa2c7fa5bde55c05e783db46498512c8a93d3c`
`git rev-parse origin/main`	`f78dcf2fe65e60751e5109dd7167c3f70f491f5a`
`git log -1 --oneline`	`79fa2c7 docs: open pdf-009c woocommerce comparison dry-run`
`git diff --check` inicial	`PASS`

El repo inicio ahead 1 por el commit local de PDF-009C. No se hizo push.

B. Objetivo¶

Documentar la politica futura de ciclo de vida de productos y sincronizacion de stock entre PostgreSQL/OpenClaw y WooCommerce La Directa, antes de cualquier write gate.

Este documento no autoriza API nueva, create, update, delete, sync, scheduler, cron, pipelines, deploy ni cambios runtime.

C. Contexto vigente¶

PDF-009B valido API WooCommerce read-only.
PDF-009C comparo SOURCE-002 contra WooCommerce sin writes.
WooCommerce La Directa esta inicialmente vacio por diseno.
SOURCE-002 Productos ya existe en PostgreSQL/OpenClaw como fuente de catalogo importada desde SGC.
La futura tabla de stock disponible se actualizara con alta frecuencia diaria.
WooCommerce debera reflejar stock_quantity con frecuencia equivalente para productos existentes.

D. Separacion de flujos¶

D.1 Stock Sync frecuente¶

Objetivo: actualizar stock vendible de productos existentes en WooCommerce con payload minimo y baja carga operativa.

Aspecto	Politica
Fuente	tabla futura de stock disponible en PostgreSQL/OpenClaw
Destino WooCommerce	`stock_quantity`, `stock_status`, `manage_stock`
Frecuencia	alta / varias veces al dia
Alcance	productos existentes con relacion futura PostgreSQL/OpenClaw -> WooCommerce
Payload	minimo, solo stock y estado nativo de stock
Exclusiones	no descripcion, no precio, no categoria, no marca, no imagenes
Estado	`READY` como politica conceptual; ejecucion futura bajo gate separado

Payload minimo futuro conceptual:

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

Reglas:

Si solo cambia stock, no mandar payload completo.
No recalcular catalogo en este flujo.
No enviar meta_data pesada en cada actualizacion frecuente.
No usar meta_data para filtros, busquedas u ordenamiento masivo.
El stock frecuente debe ser idempotente por SKU y/o wc_product_id futuro.

D.2 Product Catalog Sync controlado¶

Objetivo: crear o actualizar catalogo comercial completo bajo un gate especifico, con reglas comerciales cerradas.

Aspecto	Politica
Fuente	`SOURCE-002 Productos` importado desde SGC a PostgreSQL/OpenClaw
Destino WooCommerce	producto WooCommerce completo
Frecuencia	menor, manual o bajo gate especifico
Alcance	creacion o actualizacion controlada de catalogo
Requiere antes	categorias, marca, precio, imagen, `publish/draft`, `hidden`
Estado	`PENDING_GATE` para writes reales

Campos tipicos del flujo catalogo:

sku
name
regular_price
sale_price si aplica
categories
attributes
images
short_description
description
dimensiones/peso si aplica
meta_data minima privada para trazabilidad puntual

Este flujo no debe ejecutarse con la frecuencia del stock.

D.3 Product Lifecycle¶

Objetivo: clasificar el estado conceptual de cada SKU entre PostgreSQL/OpenClaw y WooCommerce antes de cualquier escritura.

Situacion	Accion conceptual
producto existe en PostgreSQL/OpenClaw y no existe en WooCommerce	`CREATE` futuro
producto existe en ambos y solo cambia stock	`UPDATE_STOCK` futuro
producto existe en ambos y cambian campos comerciales	`UPDATE_CATALOG` futuro
producto con estado `DE BAJA`	`DEACTIVATE` futuro
producto existe en WooCommerce pero no en PostgreSQL/OpenClaw	`BLOCKED / MANUAL_REVIEW`
producto no aparece en fuente actual por error o gap	no borrar, bloquear y revisar

Regla fuerte: no borrar productos automaticamente.

E. Politica para productos nuevos¶

Si un producto existe en PostgreSQL/OpenClaw desde SGC pero no existe en WooCommerce, debe quedar como CREATE conceptual futuro.

Condiciones minimas antes de un CREATE real:

SKU unico y valido.
Nombre comercial aprobado.
Categoria WooCommerce resuelta.
Regla de marca cerrada.
Precio ecommerce definido.
Politica de stock inicial definida.
Politica de imagen definida.
Estado ACTIVO o regla equivalente aprobada.
Gate pre-write aprobado y dry-run final validado.

CREATE no significa crear inmediatamente. Significa que el producto entra en cola conceptual para una carga de catalogo controlada.

F. Politica para productos `DE BAJA`¶

Si el campo estado del producto en PostgreSQL/OpenClaw indica DE BAJA, la accion futura recomendada es desactivar el producto en WooCommerce.

Reglas:

No hacer delete.
No borrar automaticamente productos WooCommerce.
Mantener trazabilidad historica.
Evitar perdida de historial comercial, pedidos, URLs, SEO y auditoria.
No reutilizar el SKU para otro producto sin decision manual.

Acciones futuras candidatas:

Opcion	Descripcion	Estado
`status=draft`	el producto deja de estar publicado	`PENDING_RULE`
`catalog_visibility=hidden`	el producto puede quedar oculto del catalogo/busqueda	`PENDING_RULE`

Decision final: draft vs hidden queda como PENDING_RULE hasta el gate pre-write.

G. Politica de performance¶

El stock frecuente debe privilegiar estabilidad, payload minimo y bajo costo de API.

Decisiones:

Usar payload minimo para stock frecuente.
No mandar payload completo si solo cambia stock.
Evitar meta_data pesada en flujos frecuentes.
No usar meta_data para filtros, busquedas u ordenamiento masivo.
Usar campos nativos WooCommerce para campos comerciales y de frontend.
Preservar en PostgreSQL/OpenClaw los datos sensibles, economicos, analiticos y operativos que no deban exponerse.

Lectura de arquitectura:

WooCommerce debe ser el motor de venta y frontend.
WooCommerce no se convierte en ERP.
PostgreSQL/OpenClaw debe ser la fuente gobernada de analitica, costos, proveedor, margenes, descuentos, snapshots y trazabilidad.
meta_data debe ser minima, privada y puntual, no una base analitica.

H. Lifecycle decision matrix¶

Condicion	Accion conceptual	Metodo futuro	Riesgo	Decision
SKU existe en PostgreSQL/OpenClaw y no existe en WooCommerce	`CREATE`	Catalog sync controlado	crear producto incompleto si faltan reglas	`READY_CONCEPT / PENDING_GATE`
SKU existe en ambos y cambia solo stock	`UPDATE_STOCK`	Stock sync frecuente con payload minimo	carga API si se manda payload completo	`READY`
SKU existe en ambos y cambian precio/categoria/marca/descripcion/imagen	`UPDATE_CATALOG`	Catalog sync controlado	cambios frontend no revisados	`PENDING_RULE`
SKU en PostgreSQL/OpenClaw con estado `DE BAJA`	`DEACTIVATE`	`status=draft` o `catalog_visibility=hidden`	perdida de visibilidad o SEO si se decide mal	`PENDING_RULE`
SKU existe en WooCommerce pero no en PostgreSQL/OpenClaw	`BLOCKED / MANUAL_REVIEW`	reporte/manual review	borrar o desactivar erroneamente un producto valido	`READY`
SKU sin precio ecommerce definido	`BLOCKED`	catalog gate	producto vendible sin precio correcto	`PENDING_RULE`
SKU sin categoria resuelta	`BLOCKED`	catalog gate	mala navegacion/filtros	`PENDING_RULE`
SKU sin imagen	`BLOCKED` o `DRAFT`	catalog gate	mala experiencia frontend	`PENDING_RULE`
SKU con stock `0`	`CREATE_DRAFT`, `CREATE_HIDDEN` o `BLOCKED`	catalog gate	publicar sin disponibilidad	`PENDING_RULE`
SKU desaparece temporalmente de fuente stock	`BLOCKED / MANUAL_REVIEW`	auditoria antes de accion	falso negativo de fuente	`READY`

I. Stock sync payload matrix¶

Campo	Tipo de dato	Destino Woo	Frecuencia	Riesgo performance	Decision
`sku`	`text`	lookup/idempotencia	alta	bajo si se usa cache o `wc_product_id` futuro	`READY`
`wc_product_id` futuro	`integer`	identificador directo	alta	bajo	`PENDING_MODEL`
`stock_quantity`	`integer`	`stock_quantity`	alta / varias veces al dia	bajo	`READY`
`stock_status`	`instock/outofstock/onbackorder`	`stock_status`	alta / varias veces al dia	bajo	`READY`
`manage_stock`	`boolean`	`manage_stock`	alta / estable	bajo	`READY`
`source_stock_updated_at`	timestamp	PostgreSQL/OpenClaw only o log interno	alta	medio si se envia como `meta_data` frecuente	`POSTGRES_ONLY`
`source_row_hash` stock futuro	`text`	PostgreSQL/OpenClaw only	alta	medio si se envia a Woo	`POSTGRES_ONLY`
`sync_batch_id` futuro	`uuid/text`	logs/PostgreSQL/OpenClaw	alta	medio si se envia como `meta_data` frecuente	`POSTGRES_ONLY`
descripcion	`text`	no aplica en stock sync	nunca en este flujo	alto si se manda completo	`EXCLUDED`
precio	`decimal/string`	no aplica en stock sync	nunca en este flujo	medio	`EXCLUDED`
categoria/marca	taxonomy/attribute	no aplica en stock sync	nunca en este flujo	medio/alto	`EXCLUDED`
imagenes	array	no aplica en stock sync	nunca en este flujo	alto	`EXCLUDED`
`meta_data` pesada	array	no aplica en stock sync	nunca en este flujo	alto	`EXCLUDED`

J. Catalog sync payload matrix¶

Campo	Destino	Frecuencia	Impacto frontend	Regla pendiente
SKU	`sku`	baja / gate	alto	`READY`
Articulo/nombre	`name`	baja / gate	alto	`READY`
descripcion corta	`short_description`	baja / gate	alto	`PENDING_RULE`
descripcion larga	`description`	baja / gate	alto	`PENDING_RULE`
precio lista ecommerce	`regular_price`	baja / gate	alto	`PENDING_RULE`
precio oferta	`sale_price`	baja / gate	alto	`PENDING_RULE`
categoria	`categories` / `product_cat`	baja / gate	alto	`PENDING_RULE`
subcategoria	`categories` o atributo	baja / gate	alto	`PENDING_RULE`
marca	atributo visible o taxonomia	baja / gate	alto	`PENDING_RULE`
imagen principal	`images[0]`	baja / gate	alto	`PENDING_RULE`
galeria	`images[]`	baja / gate	medio/alto	`PENDING_RULE`
peso	`weight`	baja / gate	medio	`READY`
dimensiones	`dimensions`	baja / gate	medio	`PENDING_RULE`
stock inicial	`stock_quantity`	baja en create, luego stock sync	alto	`READY`
estado comercial	`status`	baja / gate	alto	`PENDING_RULE`
visibilidad catalogo	`catalog_visibility`	baja / gate	alto	`PENDING_RULE`
PLU / pack / minimo	`meta_data` privada minima	baja / gate	bajo	`READY`
costos	PostgreSQL/OpenClaw only	no enviar	ninguno frontend	`READY`
proveedor	PostgreSQL/OpenClaw only	no enviar	ninguno frontend	`READY`
margenes/descuentos/listas multiples	PostgreSQL/OpenClaw only	no enviar	ninguno frontend	`READY`

K. Decisiones READY¶

Separar Stock Sync frecuente de Product Catalog Sync controlado.
Stock frecuente actualiza solo stock_quantity, stock_status y manage_stock.
No actualizar descripcion, precio, categoria, marca ni imagenes dentro del flujo frecuente de stock.
Producto existente en PostgreSQL/OpenClaw y ausente en WooCommerce queda como CREATE conceptual futuro.
Producto existente en ambos queda como UPDATE_STOCK o UPDATE_CATALOG segun el tipo de cambio.
Producto existente en WooCommerce pero ausente en PostgreSQL/OpenClaw queda BLOCKED / MANUAL_REVIEW.
No borrar productos automaticamente.
WooCommerce usa campos nativos para venta/frontend.
PostgreSQL/OpenClaw conserva datos sensibles, economicos y analiticos.
meta_data no debe ser base de filtros, busqueda u ordenamiento masivo.

L. Reglas PENDING¶

Decision final draft vs hidden para productos DE BAJA.
Mapping final Category/SubCategoria -> product_cat.
Marca como atributo visible o taxonomia.
Politica para productos sin stock en primera carga.
Politica para productos sin precio.
Politica para productos sin imagen.
Regla final de precio ecommerce/oferta.
Modelo persistente futuro para wc_product_id.
Payload dry-run final antes de cualquier write.
Gate pre-write de catalogo y gate pre-write de stock.

M. Bloqueos / NO-GO¶

API WooCommerce write sigue NO-GO.
Create/update/delete sigue NO-GO.
PostgreSQL writes siguen NO-GO.
Sync, scheduler, cron y pipelines siguen NO-GO.
API WooCommerce write, sync, scheduler, cron y pipelines siguen NO-GO.
Publicacion Git y deploy del Knowledge Portal ya fueron completados para este cierre documental.

N. Archivos creados/modificados¶

Creado:

docs/tenants/alpuntodeventa/business-observer/production/PDF-009D-WOOCOMMERCE-PRODUCT-LIFECYCLE-STOCK-SYNC-POLICY.md

Actualizados:

docs/tenants/alpuntodeventa/business-observer/production/README.md
docs/PROJECT-STATE.md
docs/ROADMAP.md
docs/governance/ACTIVE-CONTEXT.md
mkdocs.yml

O. Validaciones ejecutadas¶

git diff --check -> PASS
.\.venv-portal\Scripts\mkdocs.exe build --strict -> PASS

P. Estado post-publicacion¶

HEAD publicado y desplegado: 2bc2434143022e55a94e81f835bf926067173e88
origin/main, local y VPS: alineados en 2bc2434143022e55a94e81f835bf926067173e88
Knowledge Portal: desplegado OK
HTTP local VPS: 200
HTTP publico: 200

Q. Cierre de restricciones¶

Durante este cierre documental no se ejecuto API nueva, no se hicieron writes, no se imprimieron secretos, no se mostro .env, no se toco WooCommerce, no se toco PostgreSQL, no se ejecuto SQL, no se ejecuto sync, scheduler, cron ni pipelines, y no se tocaron runtimes fuera del deploy documental del Knowledge Portal ya validado.