PDF-006C SOURCE-003 Staging Initial Load Execution Package¶

Fecha local: 2026-06-19

Estado: EXECUTION PACKAGE PREPARADO / NO LOAD EJECUTADO / STAGING ONLY / FUTURE EXECUTION GATE REQUIRED

Hotfix controlado: PDF-006C RAW COPY PATH CORREGIDO / NO LOAD EJECUTADO / NEXT GATE REQUIRED

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/production/PDF-006C-SOURCE-003-STAGING-INITIAL-LOAD-EXECUTION-PACKAGE.md

1. Contexto desde PDF-006B¶

PDF-006B dejo documentado el snapshot + preflight operativo para SOURCE-003 en PostgreSQL staging. El resultado fue GO para preparar un futuro paquete PDF-006C y NO-GO para cargar datos en esa etapa.

Estado heredado:

HEAD esperado al abrir este paquete: 56de612f1864ac2c38edc62817bbe5c1eb25721e;
ultimo commit esperado: 56de612 docs: record source-003 staging snapshot preflight;
snapshot autorizado: SOURCE-003-SNAPSHOT-001;
snapshot SHA256: 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3;
filas esperadas: 1886;
columnas esperadas: 68;
mapping activo: 68/68 MATCH;
staging: 7/7 tablas SOURCE-003 presentes y vacias;
backup post-DDL vigente validado;
resultado heredado: GO para preparar paquete futuro, NO-GO para cargar.

Esta tarea prepara y publica el paquete ejecutable candidate. No ejecuta carga real, no ejecuta COPY, no ejecuta INSERT/UPDATE/DELETE/TRUNCATE y no modifica PostgreSQL staging.

2. Alcance¶

Alcance permitido:

documentar el paquete PDF-006C;
crear scripts .candidate.sql para revision;
mantener todo apuntado a PostgreSQL staging openclaw_business_observer_staging;
parametrizar la futura carga desde snapshot autorizado fuera de Git;
definir validaciones previas, posteriores, idempotencia y rollback;
preservar line_key_v4 como AMARILLO ACEPTADO.

Fuera de alcance:

ejecucion real de carga;
SQL operativo contra PostgreSQL staging;
COPY real;
INSERT, UPDATE, DELETE, TRUNCATE;
produccion;
openclaw-postgres-sandbox;
sync diaria, scheduler, pipelines o jobs;
snapshot nuevo;
backup nuevo;
CSV snapshot, backups, dumps, .env, secretos o connection strings en Git.

3. Snapshot autorizado¶

Snapshot autorizado:

text SOURCE-003-SNAPSHOT-001

Referencia no versionada:

text C:\APV\openclawai\snapshots\source-003\SOURCE-003-TABLA2-V2-2026-06-09_20260610-210406-0300.csv

Evidencia heredada:

Control	Esperado
SHA256	`07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3`
filas	`1886`
columnas	`68`
mapping	`68/68`
orden	`MATCH`
clientes	`173`
vendedores	`25`
SKU	`180`
comprobantes	`428`
importe total	`48087486.83`
CMV total	`37881269.3025`

El snapshot no se agrega al repo.

4. Tablas destino¶

Capa	Tabla	Estado esperado antes de ejecutar gate futuro
base	`business_observer.source_003_sales_items`	presente y vacia
RAW	`business_observer.raw_source_003_sales_items`	presente y vacia
CORE	`business_observer.core_source_003_sales_items`	presente y vacia
MART	`business_observer.mart_source_003_sales_daily`	presente y vacia
MART	`business_observer.mart_source_003_sales_by_seller`	presente y vacia
MART	`business_observer.mart_source_003_sales_by_customer`	presente y vacia
MART	`business_observer.mart_source_003_sales_by_sku`	presente y vacia

5. Estrategia raw -> core -> mart¶

RAW recibe un CSV preparado fuera de Git, derivado del snapshot autorizado, con columnas de negocio y metadata tecnica requerida por el DDL staging.
CORE promueve exclusivamente el sync_batch_id autorizado desde RAW, preservando line_key, source_row_hash, source_query_version, timestamps y trazabilidad.
MART construye agregados candidate desde CORE, limitados al mismo sync_batch_id, sin scheduler, jobs ni pipeline.

El paquete no define sync diaria. La ejecucion futura debe ser manual, controlada y autorizada por un gate separado.

6. Orden de ejecucion futuro¶

Orden candidate para un gate futuro separado:

001-source-003-initial-load-execution-preflight.candidate.sql
002-source-003-initial-load-raw-execution.candidate.sql
003-source-003-initial-load-core-execution.candidate.sql
004-source-003-initial-load-marts-execution.candidate.sql
005-source-003-initial-load-execution-post-checks.candidate.sql

Rollback candidate, solo con autorizacion separada:

text rollback-source-003-initial-load-execution.candidate.sql

6.1 Hotfix RAW copy path¶

Intento operativo PDF-006C posterior al preflight termino ROJO controlado en RAW con:

text psql:<stdin>:117: error: :: No such file or directory

Causa: el \copy RAW usaba FROM :'pdf006c_prepared_csv_path'. En el contexto actual de psql \copy, esa forma no resolvio el path como filename usable y el cliente intento abrir : como archivo local.

Correccion aplicada:

archivo: infra/business-observer/staging/postgres/load/PDF-006C/002-source-003-initial-load-raw-execution.candidate.sql;
linea del \copy: FROM '/tmp/pdf006c-source003-prepared.csv';
el CSV preparado debe existir dentro del contenedor en /tmp/pdf006c-source003-prepared.csv;
se preservan guardas de staging, snapshot, SHA256, filas 1886, columnas 68, sync_batch_id, tablas vacias e idempotencia.

No se ejecuto carga, COPY, INSERT/UPDATE/DELETE/TRUNCATE, rollback, sync, scheduler, pipelines, produccion ni openclaw-postgres-sandbox durante este hotfix.

7. Validaciones previas¶

Validaciones previas obligatorias para una ejecucion futura:

Control	Esperado
SAFE POINT	nuevo, limpio y documentado
target	`openclaw_business_observer_staging`
schema	`business_observer` presente
tablas destino	`7/7` presentes
tablas vacias	`7/7 row_count = 0`
roles	staging roles presentes y `NOLOGIN`
grants	writer sin `DELETE/TRUNCATE`, reader/reporting `SELECT`
`PUBLIC`	sin grants
snapshot	`SOURCE-003-SNAPSHOT-001` o nuevo snapshot autorizado por gate propio
hash	SHA256 declarado y verificado
filas	`1886` para el snapshot autorizado actual
columnas	`68`
mapping	`68/68 MATCH`
backup post-DDL	vigente y aceptado fuera de Git
autorizacion	explicita para ejecutar carga real

8. Validaciones posteriores¶

Validaciones posteriores esperadas:

RAW rows = 1886;
CORE rows = 1886;
MART daily rows = 1;
MART seller rows = 25;
MART customer rows = 173;
MART sku rows = 180;
duplicados RAW por tenant_id + sync_batch_id + line_key = 0;
duplicados CORE por tenant_id + line_key = 0;
line_key vacio = 0;
source_row_hash no sha256 = 0;
line_sequence menor a 1 = 0;
source_query_version = SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2;
importe_total_item conciliado contra 48087486.83;
cmv_bruto_item conciliado contra 37881269.3025;
produccion, sandbox, sync, scheduler y pipelines no usados.

9. Idempotencia¶

Reglas candidate:

abortar si cualquiera de las 7 tablas destino tiene filas antes de la carga inicial futura;
abortar RAW si ya existe el sync_batch_id;
abortar CORE si ya existe el sync_batch_id o tenant_id + line_key;
abortar MART si ya existe el sync_batch_id;
no usar TRUNCATE;
no borrar batches no autorizados;
no hacer hard delete;
limitar rollback al sync_batch_id autorizado.

10. Rollback¶

Rollback candidate:

requiere autorizacion separada;
staging only;
batch only;
sin TRUNCATE;
aborta si el batch no coincide con SOURCE-003-SNAPSHOT-001;
borra en orden MART -> CORE -> RAW -> base, solo para el sync_batch_id autorizado;
exige evidencia antes y despues.

11. line_key_v4¶

line_key_v4 permanece como AMARILLO ACEPTADO.

Lectura obligatoria:

no existe line_id_source fisico ERP disponible en la vista accesible;
line_sequence_v1 es tecnico y no identidad legal perfecta;
el alcance aceptado es analitico para Business Observer, BI, IA y ML;
no debe presentarse como semaforo VERDE ni auditoria legal de renglon ERP.

12. GO / NO-GO¶

GO futuro solo si:

existe autorizacion humana explicita para ejecutar carga real;
el preflight read-only pasa;
snapshot/hash/filas/columnas coinciden;
el backup post-DDL vigente sigue aceptado;
las tablas estan vacias;
rollback queda aceptado;
los scripts se ejecutan manualmente en orden;
produccion, sandbox, sync, scheduler y pipelines quedan excluidos.

NO-GO inmediato si:

falta autorizacion explicita;
el target no es staging;
aparece produccion o openclaw-postgres-sandbox;
hay filas previas no explicadas;
drift de snapshot, mapping o autoridad;
falta el CSV preparado fuera de Git;
se requiere imprimir secretos o connection strings reales;
se intenta combinar carga inicial con sync, scheduler o pipeline.

13. Evidencia requerida¶

Evidencia minima para un gate futuro:

SAFE POINT inicial/final;
comandos ejecutados sin secretos;
variables no sensibles usadas: sync_batch_id, snapshot_id, hash, filas, columnas y ruta no sensible;
resultado de cada script;
conteos RAW, CORE y MART;
conciliacion de importes y CMV;
confirmacion de idempotencia;
confirmacion de produccion y sandbox excluidos;
confirmacion de sync, scheduler y pipelines no ejecutados;
decision final VERDE, AMARILLO o ROJO.

14. Autorizacion futura requerida¶

La ejecucion futura requiere una autorizacion nueva y separada con texto equivalente a:

text Autorizo ejecutar la carga inicial controlada SOURCE-003 en PostgreSQL staging Business Observer usando el paquete PDF-006C, snapshot SOURCE-003-SNAPSHOT-001, 1886 filas esperadas, 68 columnas esperadas, SHA256 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3 y rollback aceptado. No autorizo produccion, openclaw-postgres-sandbox, sync diaria, scheduler ni pipelines.

Sin esa autorizacion, PDF-006C permanece como paquete candidate preparado.

15. Paquete creado¶

Ruta:

text infra/business-observer/staging/postgres/load/PDF-006C/

Archivos:

001-source-003-initial-load-execution-preflight.candidate.sql;
002-source-003-initial-load-raw-execution.candidate.sql;
003-source-003-initial-load-core-execution.candidate.sql;
004-source-003-initial-load-marts-execution.candidate.sql;
005-source-003-initial-load-execution-post-checks.candidate.sql;
rollback-source-003-initial-load-execution.candidate.sql.

16. Estado final de esta tarea¶

text PDF-006C PREPARED LOAD PACKAGE = CANDIDATE EXECUTION PACKAGE FOR FUTURE REVIEW SOURCE-003 LOAD = NOT EXECUTED SQL OPERATIONAL EXECUTION = NOT EXECUTED COPY = NOT EXECUTED INSERT_UPDATE_DELETE_TRUNCATE = NOT EXECUTED SNAPSHOT_NEW = NOT CREATED BACKUP_NEW = NOT CREATED SYNC_SCHEDULER_PIPELINES = NOT EXECUTED PRODUCTION = NOT TOUCHED OPENCLAW_POSTGRES_SANDBOX = NOT TOUCHED NEXT GATE = EXPLICIT REAL LOAD EXECUTION AUTHORIZATION