Saltar a contenido

PDF-008H - SOURCE-002 Products Official Load Scripts Formalization

Fecha: 2026-06-21

Estado: SCRIPTS OFICIALES FORMALIZADOS / CANDIDATE / SIN EJECUCION / WOOCOMMERCE NO TOCADO / SYNC NO-GO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

1. Contexto

PDF-008G dejo documentada en VERDE la carga inicial productiva SOURCE-002 Productos en PostgreSQL productivo dedicado, con 314 productos conciliados en RAW, CORE, catalogo, inventario, capa economica y mart de alertas.

La ejecucion operativa previa PDF-008F uso SQL temporal controlado derivado del paquete PDF-008D y del DDL aprobado. Esa ejecucion no habilito WooCommerce, sync, scheduler, cron, pipelines ni recargas automaticas.

Este gate formaliza el camino repetible en scripts versionados .candidate.sql sin ejecutar SQL, sin carga, sin COPY, sin DML, sin writes productivos, sin staging, sin sandbox y sin WooCommerce API.

2. Safe Point Inicial

Validacion Resultado
git status -sb ## main...origin/main
git rev-parse HEAD e167ab798b2492def3661e6094a0e291babf45f8
git rev-parse origin/main e167ab798b2492def3661e6094a0e291babf45f8
git log -1 --oneline e167ab7 docs: record source-002 products production initial load execution
git diff --check PASS
.\\.venv-portal\\Scripts\\mkdocs.exe build --strict PASS

Nota operativa: desde C:\APV\openclawai, la ruta solicitada ..\\.venv-portal\\Scripts\\mkdocs.exe no existe; el metodo funcional documentado y usado es .\\.venv-portal\\Scripts\\mkdocs.exe.

3. Warning Original

Los scripts oficiales de carga PDF-008D seguian bloqueados por diseno con RAISE EXCEPTION:

  • 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

rollback-source-002-products.candidate.sql tambien quedaba bloqueado y orientado a dropear tablas vacias, no a revertir una carga productiva ya ejecutada.

4. Motivo De Formalizacion

Antes de cualquier recarga controlada, sync, cron, scheduler o pipeline, el SQL operativo temporal usado en PDF-008F debe quedar expresado como scripts versionados, revisables y repetibles.

La formalizacion no autoriza ejecucion. Solo deja el paquete oficial listo para un gate futuro separado con autorizacion explicita, safe point propio, archivo de entrada controlado, hash confirmado y evidencia post-ejecucion.

5. Scripts Afectados

Paquete historico superado como camino operativo recomendado:

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

Nuevo paquete oficial candidate:

  • infra/business-observer/production/postgres/products/PDF-008H/001-source-002-products-official-load-preflight.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/002-source-002-products-official-load-raw.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/003-source-002-products-official-load-core.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/004-source-002-products-official-load-catalog-inventory-economic.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/005-source-002-products-official-load-marts.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/006-source-002-products-official-load-post-checks.candidate.sql
  • infra/business-observer/production/postgres/products/PDF-008H/rollback-source-002-products-official-load.candidate.sql

6. Logica Formalizada

La logica repetible queda dividida en pasos:

  1. Preflight read-only: valida DB productiva dedicada, schema, roles, tablas, ausencia de staging/sandbox, batch, hash, conteos esperados y baseline SOURCE-003.
  2. RAW: carga JSONL controlado a tabla temporal, valida 314 filas y 314 SKUs unicos, y promueve a raw_source_002_products.
  3. CORE: promueve RAW -> CORE por tenant_id + sku, preservando hash, snapshot, batch, fechas, stock, proveedor, marca y calidad.
  4. Derivadas: genera catalogo WooCommerce-ready sin API, inventario actual, snapshot diario y capa economica.
  5. MART: genera alertas out_of_stock para stock_quantity = 0, con 100 filas esperadas.
  6. Post-checks: valida conteos productivos 314/314/314/314/314/314/100, stock 212/100, precio/costo 312/2, PUBLIC sin grants y SOURCE-003 intacto.
  7. Rollback candidate: revierte solo el batch autorizado, con confirmacion explicita y guardas de conteos.

7. Guardas Obligatorias

  • DB esperada: openclaw_business_observer_prod.
  • Tenant esperado: alpuntodeventa.
  • Batch esperado: 7dddfc3b-2026-48f0-8002-000000000008.
  • Snapshot esperado: SOURCE-002-PRODUCTS-RUNTIME-PREFLIGHT-20260620-173614.
  • Snapshot SHA256 esperado: c961ffc2b352b6bb3dd0d59bf3d8b7c0f7facff58a9201f7cf45e290141b704f.
  • JSONL SHA256 esperado: 30fb804deba1d6492622f1f64c78f6e2ecbd207fd9a9c3d75bef36b516919531.
  • Filas esperadas: 314.
  • Columnas fuente esperadas: 81.
  • SKUs unicos esperados: 314.
  • SOURCE-003 esperado intacto: RAW 1886, CORE 1886, MART daily/seller/customer/sku 1/25/173/180.
  • Staging y sandbox quedan prohibidos como target.
  • No se incluyen credenciales, passwords ni connection strings.

Los scripts con writes contienen confirmaciones psql BLOCKED por defecto. El operador de un gate futuro debe reemplazarlas de forma explicita y documentada; este documento no autoriza hacerlo.

8. Reglas De Idempotencia

  • RAW: tenant_id + sync_batch_id + sku unico.
  • CORE: tenant_id + sku y tenant_id + sync_batch_id + sku unicos.
  • Catalogo: tenant_id + sku + sync_batch_id unico.
  • Inventario actual: tenant_id + sku reemplazable por batch aprobado.
  • Snapshot diario: tenant_id + sku + snapshot_date unico.
  • Economia: tenant_id + sku + list_code + sync_batch_id unico.
  • MART: tenant_id + sku + alert_date + alert_type unico.

La recarga controlada del mismo batch debe ser NO-GO si los conteos ya coinciden, salvo rollback aprobado previamente. No se habilita hard delete de productos ausentes.

9. Rollback Esperado

El rollback PDF-008H no dropea tablas. Su alcance esperado es revertir solo el batch 7dddfc3b-2026-48f0-8002-000000000008 en orden inverso:

  • mart stock alerts;
  • economic;
  • inventory daily snapshot;
  • inventory current del batch;
  • catalog;
  • core del batch;
  • raw del batch.

El rollback aborta si el target no es produccion dedicada, si la confirmacion queda bloqueada, si el batch no coincide o si los conteos previos no coinciden con la evidencia PDF-008G.

10. Limites

Este gate mantiene bloqueados:

  • WooCommerce API;
  • sync;
  • scheduler;
  • cron;
  • pipelines;
  • recargas automaticas;
  • staging como target;
  • sandbox;
  • nuevos snapshots, dumps o backups;
  • versionado de JSONL, CSV o snapshots temporales.

11. GO / NO-GO Futuro

GO futuro solo si existe un gate separado con:

  • safe point limpio;
  • autorizacion explicita para ejecutar el paquete;
  • input JSONL controlado disponible en el contenedor;
  • SHA256 de snapshot y JSONL confirmados;
  • target productivo dedicado confirmado;
  • batch esperado confirmado;
  • conteos previos conocidos y aceptados;
  • rollback aceptado;
  • post-checks definidos como evidencia obligatoria.

NO-GO si:

  • el target no es openclaw_business_observer_prod;
  • aparece staging o sandbox como DB;
  • faltan roles o tablas;
  • el hash no coincide;
  • el batch no coincide;
  • hay datos parciales no conciliados;
  • SOURCE-003 no coincide con baseline;
  • se pretende llamar WooCommerce o activar automatizaciones.

12. PDF-008D Como Referencia Historica

PDF-008D fue el candidate inicial de DDL/load. Sus scripts de carga quedaron bloqueados por diseno y cumplieron la funcion de preparar el modelo y las guardas.

PDF-008F ejecuto la carga real con SQL temporal controlado.

PDF-008H formaliza el camino repetible. Desde este punto, PDF-008D queda como referencia historica y tecnica, no como camino operativo recomendado para recarga.

13. Proximo Gate Recomendado

PDF-008I SOURCE-002 products controlled reload rehearsal

Alcance sugerido:

  • safe point nuevo;
  • revisar paquete PDF-008H;
  • confirmar input y hash sin versionar datos;
  • ejecutar solo si hay autorizacion explicita separada;
  • documentar evidencia de preflight, carga, post-checks y rollback disponible;
  • mantener WooCommerce, sync, scheduler, cron y pipelines en NO-GO.

14. Confirmacion De Alcance

Durante este gate:

  • no se ejecuto SQL;
  • no se ejecuto carga;
  • no se ejecuto COPY;
  • no se ejecuto INSERT/UPDATE/DELETE/TRUNCATE;
  • no se ejecuto DML;
  • no se toco PostgreSQL produccion con writes;
  • no se toco PostgreSQL staging;
  • no se uso sandbox;
  • no se toco WooCommerce;
  • no se llamo API WooCommerce;
  • no se ejecuto sync;
  • no se ejecuto scheduler;
  • no se ejecuto cron;
  • no se ejecutaron pipelines;
  • no se creo snapshot nuevo;
  • no se creo backup nuevo;
  • no se creo dump nuevo;
  • no se versionaron JSONL, CSV ni snapshots temporales;
  • no se leyeron secretos;
  • no se imprimieron passwords ni connection strings reales;
  • no se modifico OpenClaw, NPM, Portainer ni Docker.

15. Estado Final

Estado final: VERDE para formalizacion documental y scripts candidate.

La ejecucion futura sigue NO-GO hasta un gate separado.

16. Hotfix Posterior PDF-008I-B

El rehearsal PDF-008I quedo AMARILLO CONTROLADO / NO-GO PARA RELOAD porque el script RAW aborto por una guarda RAISE EXCEPTION incondicional antes de writes. El hotfix posterior PDF-008I-B corrige los scripts oficiales de este paquete para usar confirmaciones explicitas, preserva target productivo dedicado, batch, snapshot, backup pre-rehearsal y SOURCE-003 intacto, y ajusta la regla precio/costo para tratar NULL OR 0 como sin precio/costo.

Documento: docs/tenants/alpuntodeventa/business-observer/production/PDF-008I-B-SOURCE-002-OFFICIAL-LOAD-SCRIPTS-HOTFIX.md.

La recarga sigue NO-GO hasta un gate separado.

17. Hotfix Posterior PDF-008I-D

El rehearsal retry PDF-008I-C quedo AMARILLO CONTROLADO / NO-GO PARA RELOAD: preflight oficial PASS, backup pre-rehearsal retry validado, SOURCE-002 y SOURCE-003 intactos, y aborto RAW antes de writes por la forma FROM :'pdf008h_controlled_jsonl_path' usada dentro de psql \copy.

El hotfix posterior PDF-008I-D corrige el RAW copy para usar el path literal controlado /tmp/pdf008f-source002-products.jsonl y reemplaza el SHA del backup pre-rehearsal hardcodeado por una variable explicita pdf008h_expected_pre_rehearsal_backup_sha256. Los scripts de write y rollback abortan si falta ese SHA, si falta pdf008h_pre_rehearsal_backup_path o si la confirmacion pdf008h_confirm_pre_rehearsal_backup no coincide.

Documento: docs/tenants/alpuntodeventa/business-observer/production/PDF-008I-D-SOURCE-002-OFFICIAL-RAW-COPY-BACKUP-PARAM-HOTFIX.md.

La recarga sigue NO-GO hasta un gate separado.

18. Hotfix Posterior PDF-008I-F

El retry PDF-008I-E quedo AMARILLO CONTROLADO / NO-GO: RAW paso con COPY 314 y upsert 314, CORE paso con 314, pero el script derived aborto antes de COMMIT. La causa fue doble: daily snapshot usaba la fecha hardcodeada 2026-06-20 y el post-check contaba inventory_source_002_daily_snapshot por batch sin filtrar fecha, por lo que observo 628 filas al coexistir historico productivo 2026-06-21.

El hotfix posterior PDF-008I-F corrige el script derived y el post-check general para exigir pdf008h_inventory_snapshot_date con formato YYYY-MM-DD, usar esa fecha en inventory_source_002_daily_snapshot y validar 314 filas por fecha explicita y batch. El historico diario no se borra ni se usa como conteo global de fallo.

Documento: docs/tenants/alpuntodeventa/business-observer/production/PDF-008I-F-SOURCE-002-DERIVED-SNAPSHOT-DATE-HOTFIX.md.

La recarga sigue NO-GO hasta un gate separado.

19. Rehearsal Posterior PDF-008I-G

El retry posterior PDF-008I-G ejecuto el rehearsal controlado de recarga SOURCE-002 Productos con resultado VERDE, usando los scripts oficiales PDF-008H hotfixados hasta PDF-008I-F e inventory snapshot date 2026-06-21.

Resultado resumido:

  • preflight official load PASS;
  • RAW retry COPY 314, INSERT 0 314, COMMIT;
  • CORE retry INSERT 0 314, COMMIT;
  • derived retry PASS con catalog 314, inventory current 314, inventory daily 314 para 2026-06-21 y economic 314;
  • MARTS retry DELETE 100, INSERT 0 100, COMMIT;
  • post-checks PASS;
  • SOURCE-003 intacto.

Documento: docs/tenants/alpuntodeventa/business-observer/production/PDF-008I-G-SOURCE-002-PRODUCTS-CONTROLLED-RELOAD-REHEARSAL.md.

WooCommerce API no fue tocada y sync, scheduler, cron y pipelines siguen NO-GO. El proximo gate recomendado pasa a PDF-009A WooCommerce mapping/API candidate.