Saltar a contenido

PDF-008D - SOURCE-002 Products DDL Load Candidate

Fecha: 2026-06-20

Estado: DDL/LOAD CANDIDATE CONTROLADO / NO LOAD / NO SQL EJECUTADO / WOOCOMMERCE NO TOCADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

1. Contexto

PDF-008C dejo SOURCE-002 Productos en VERDE como preflight runtime read-only, con snapshot fuera de Git y conteos no sensibles validados.

Este gate prepara el paquete DDL/load candidate para una futura carga controlada. No ejecuta SQL contra PostgreSQL, no ejecuta COPY, no inserta datos, no llama API WooCommerce y no crea sync, scheduler, cron ni pipelines.

2. Safe Point Inicial

Validacion Resultado
git status -sb ## main...origin/main
git rev-parse HEAD 9eeff25308238cf446b433fd634e50d560491bb3
git rev-parse origin/main 9eeff25308238cf446b433fd634e50d560491bb3
git log -1 --oneline 9eeff25 docs: record source-002 products runtime preflight snapshot
git diff --check PASS
.\.venv-portal\Scripts\mkdocs.exe build --strict PASS

Nota: desde C:\APV\openclawai, el metodo funcional documentado para MkDocs es C:\APV\openclawai\.venv-portal\Scripts\mkdocs.exe.

3. Snapshot Evidence PDF-008C

Snapshot validado sin versionar el CSV:

Evidencia Valor
path local C:\APV\openclawai\snapshots\source-002\SOURCE-002-PRODUCTS-RUNTIME-PREFLIGHT-20260620-173614.csv
hash file C:\APV\openclawai\snapshots\source-002\SOURCE-002-PRODUCTS-RUNTIME-PREFLIGHT-20260620-173614.csv.sha256
SHA256 c961ffc2b352b6bb3dd0d59bf3d8b7c0f7facff58a9201f7cf45e290141b704f
CSV existe YES
.sha256 existe YES
SHA256 coincide YES
filas 314
columnas 81
SKUs unicos 314
SKUs duplicados 0
activos 314
inactivos 0 por filtro de autoridad
stock > 0 212
stock = 0 100
con precio 312
sin precio 2
con costo 312
sin costo 2
con proveedor 314
marcas unicas 49

La autoridad vigente filtra Estado = 'ACTIVO'; por eso los inactivos reales requieren una autoridad complementaria o nueva version aprobada.

4. Modelo De Tablas SOURCE-002

Modelo candidate propuesto:

Tabla Proposito Grano
raw_source_002_products preservar salida autoridad y metadata del snapshot tenant_id + sync_batch_id + sku
core_source_002_products producto vigente normalizado tenant_id + sku
catalog_source_002_products catalogo WooCommerce-ready sin API tenant_id + sku + sync_batch_id
inventory_source_002_current stock actual ultimo observado tenant_id + sku
inventory_source_002_daily_snapshot foto diaria de stock y contexto minimo tenant_id + sku + snapshot_date
economic_source_002_products costo, precio, IVA, margen y listas normalizadas tenant_id + sku + list_code + sync_batch_id
mart_source_002_stock_alerts faltantes, bajo stock y alertas futuras tenant_id + sku + alert_date + alert_type

Separaciones obligatorias:

  • catalogo WooCommerce: catalog_source_002_products;
  • stock actual: inventory_source_002_current;
  • snapshot diario: inventory_source_002_daily_snapshot;
  • faltantes/quiebres: mart_source_002_stock_alerts;
  • capa economica: economic_source_002_products;
  • proveedor/logistica: core_source_002_products con atributos lentos;
  • cruce con ventas SOURCE-003: futuro por tenant_id + sku.

5. DDL Candidate

El DDL candidate crea las siete tablas anteriores en business_observer, con guardas de base esperada openclaw_business_observer_prod, roles productivos, ownership openclaw_bo_prod_owner, revocacion de PUBLIC y grants controlados a roles productivos.

El writer queda con SELECT/INSERT/UPDATE y sin DELETE, TRUNCATE, REFERENCES ni TRIGGER.

El DDL no carga datos y no contiene credenciales.

6. Load Candidate

El load candidate queda dividido en pasos futuros:

  1. load-preflight: valida target, tablas y metadata esperada del snapshot.
  2. load-raw: deja documentado el futuro COPY parametrizado con path controlado y hash obligatorio.
  3. load-core: promueve RAW -> CORE solo despues de una carga RAW aprobada.
  4. load-catalog-inventory-economic: deriva catalogo, stock actual, snapshot diario y economia.
  5. load-marts: genera alertas de stock solo despues de las capas previas.
  6. load-post-checks: valida conteos, unicidad y presencia de capas.

Los scripts de carga quedan bloqueados por defecto con RAISE EXCEPTION. Ejecutarlos exige una autorizacion futura separada que reemplace los guards, provea sync_batch_id, path controlado y evidencia de hash.

7. Estrategia Raw -> Core -> Catalog/Inventory/Economic/Mart

raw_source_002_products conserva la salida de autoridad con metadata de snapshot, batch y hash.

core_source_002_products normaliza identidad, estado, proveedor, marca, categoria, logistica, stock y fechas operativas por tenant_id + sku.

catalog_source_002_products expone campos WooCommerce-ready sin llamar la API: sku, name, description, regular_price, sale_price, stock_quantity, manage_stock, brand, peso, volumen, pack, categoria raw y estado candidate.

inventory_source_002_current conserva la ultima observacion de stock.

inventory_source_002_daily_snapshot conserva una foto diaria comparable.

economic_source_002_products normaliza BASE, OFFER y listas L1..L9 como filas, preservando costo, precio, IVA, margen y descuentos.

mart_source_002_stock_alerts queda reservado para faltantes, bajo stock, recuperaciones y cruces futuros con ventas SOURCE-003.

8. Campos Por Dominio

WooCommerce-ready:

  • sku, name, description;
  • regular_price, sale_price;
  • stock_quantity, manage_stock;
  • brand, category_raw, subcategory_raw;
  • weight_kg, volume_m3, units_per_pack;
  • woo_status_candidate.

Stock y faltantes:

  • stock_quantity;
  • stock_pack_quantity;
  • units_per_pack;
  • last_sale_date;
  • days_without_sale;
  • alert_type, alert_severity, suggested_action.

Economia:

  • supplier_list_cost;
  • net_unit_cost;
  • purchase_discount_1_pct, purchase_discount_2_pct, purchase_discount_3_pct;
  • markup_pct, vat_rate_pct;
  • price_final, price_net, vat_amount, margin_pct;
  • list_code.

Proveedor/logistica:

  • supplier_code, supplier_name;
  • brand;
  • unit_of_measure;
  • weight_kg, volume_m3;
  • units_per_pack, units_per_pallet, packs_per_pallet;
  • plu_unit, plu_pack.

9. Reglas De Idempotencia

  • RAW: tenant_id + sync_batch_id + sku unico.
  • CORE: tenant_id + sku unico para producto vigente.
  • Catalog: tenant_id + sku + sync_batch_id unico.
  • Stock actual: tenant_id + sku se reemplaza en futuras cargas aprobadas.
  • Snapshot diario: tenant_id + sku + snapshot_date unico.
  • Economic: tenant_id + sku + list_code + sync_batch_id unico.
  • MART: tenant_id + sku + alert_date + alert_type unico.

No se habilita hard delete. Productos ausentes deben tratarse como missing_from_source en un gate futuro.

10. Reglas De Calidad

  • tenant_id = 'alpuntodeventa'.
  • sku obligatorio y no vacio.
  • source_row_hash obligatorio.
  • snapshot_sha256 obligatorio en RAW.
  • status_raw se preserva aunque hoy solo llegue ACTIVO.
  • stock_quantity obligatorio en CORE e inventory.
  • dos productos sin precio y dos sin costo quedan como warning esperado.
  • regular_price y sale_price siguen pendientes de decision final de negocio para WooCommerce.
  • categorias raw no se tratan como taxonomia WooCommerce final.
  • costos y descuentos son sensibles y deben consumirse solo por roles autorizados.

11. Rollback Esperado

rollback-source-002-products.candidate.sql queda con guardas:

  • base esperada openclaw_business_observer_prod;
  • bloqueo intencional por defecto;
  • aborta si cualquier tabla target contiene filas;
  • solo dropea tablas vacias en un gate futuro separado y aprobado.

No se ejecuta rollback en este gate.

12. GO / NO-GO

GO de este gate:

  • usar PDF-008D como candidate documental y tecnico;
  • revisar DDL de siete tablas;
  • revisar estrategia de carga futura desde snapshot PDF-008C;
  • avanzar a un gate separado de DDL o carga solo con autorizacion explicita.

NO-GO:

  • ejecutar DDL;
  • ejecutar carga real;
  • ejecutar COPY;
  • ejecutar INSERT/UPDATE/DELETE/TRUNCATE;
  • tocar PostgreSQL produccion, staging o sandbox;
  • llamar WooCommerce API;
  • crear sync, scheduler, cron o pipelines;
  • versionar CSV, dumps, backups o snapshots.

13. Riesgos

  • La autoridad actual filtra Estado = 'ACTIVO'; inactivos reales no quedan cubiertos.
  • Stock requiere definicion final: teorico, disponible o vendible.
  • categorias Category/SubCategoria no son taxonomia final WooCommerce.
  • regular_price, sale_price, moneda y estado WooCommerce siguen pendientes de decision.
  • SOURCE-002B imagenes y wc_product_id siguen pendientes.
  • la lista SKU NOT IN ('0124', '3857', '3998', '3793') debe externalizarse antes de sync.
  • faltantes/quiebres requieren reglas de umbral y cruce con SOURCE-003.

14. Paquete Candidate

Carpeta:

  • infra/business-observer/production/postgres/products/PDF-008D/

Scripts:

  • 001-source-002-products-ddl-preflight.candidate.sql
  • 002-source-002-products-ddl-forward.candidate.sql
  • 003-source-002-products-ddl-post-checks.candidate.sql
  • 004-source-002-products-load-preflight.candidate.sql
  • 005-source-002-products-load-raw.candidate.sql
  • 006-source-002-products-load-core.candidate.sql
  • 007-source-002-products-load-catalog-inventory-economic.candidate.sql
  • 008-source-002-products-load-marts.candidate.sql
  • 009-source-002-products-load-post-checks.candidate.sql
  • rollback-source-002-products.candidate.sql

15. Proximo Gate Recomendado

PDF-008E SOURCE-002 products production DDL preflight/forward gate

Alcance sugerido:

  • safe point nuevo;
  • backup/baseline productivo confirmado;
  • ejecutar solo preflight DDL read-only;
  • ejecutar forward DDL solo si se aprueba explicitamente;
  • post-checks con tablas vacias;
  • carga real sigue NO-GO.

La carga inicial real deberia quedar para un gate posterior separado, con snapshot confirmado, path controlado, hash validado, sync_batch_id real, rollback aceptado y evidencia post-load.

16. Confirmacion De Alcance

Durante este gate:

  • no se ejecuto carga;
  • no se ejecuto COPY;
  • no se ejecuto DML;
  • no se ejecuto DDL;
  • no se ejecuto SQL operativo;
  • no se toco PostgreSQL produccion;
  • no se toco PostgreSQL staging;
  • no se toco sandbox;
  • no se llamo API WooCommerce;
  • no se ejecuto sync, scheduler, cron ni pipelines;
  • no se leyeron secretos;
  • no se imprimieron passwords ni connection strings reales;
  • no se agregaron dumps, backups, snapshots ni CSV al repo.

17. Estado Final

Estado final: VERDE para candidate documental y tecnico.

SOURCE-002 queda preparado para revision de DDL/load candidate desde la evidencia runtime PDF-008C, sin habilitar ejecucion.