Saltar a contenido

PDF-006A SOURCE-003 Staging Initial Load Candidate

Fecha local: 2026-06-19

Estado: INITIAL LOAD CANDIDATE PREPARADO / NO LOAD / NO SQL EJECUTADO / STAGING ONLY / EXECUTION GATE REQUIRED

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

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

1. Contexto desde PDF-005C

PDF-005C documenta la ejecucion previa del DDL PDF-005B sobre PostgreSQL staging de Business Observer.

Estado heredado:

  • target staging: openclaw_business_observer_staging;
  • schema: business_observer;
  • tablas destino SOURCE-003: 7/7 creadas;
  • tablas destino vacias: 7/7 row_count = 0;
  • owner: openclaw_bo_staging_owner;
  • grants: writer SELECT/INSERT/UPDATE, reader SELECT, reporting SELECT;
  • PUBLIC: 0 grants;
  • estado final: VERDE.

Este documento prepara el candidate documental de carga inicial controlada. No ejecuta carga real, no ejecuta SQL operativo y no modifica PostgreSQL staging.

2. Alcance staging unicamente

Alcance permitido del candidate:

  • PostgreSQL staging openclaw_business_observer_staging;
  • schema business_observer;
  • fuente SOURCE-003 / Tabla 2 V2;
  • flujo candidate raw -> core -> mart;
  • scripts candidate versionados para revision;
  • validaciones previas y posteriores propuestas;
  • criterios GO/NO-GO, evidencia, idempotencia y rollback esperado.

El alcance de este gate es documental y preparatorio. Cualquier ejecucion futura requiere una autorizacion nueva y separada.

3. Exclusiones

Queda explicitamente fuera de alcance:

  • produccion;
  • openclaw-postgres-sandbox;
  • sync diaria;
  • scheduler;
  • pipelines;
  • jobs;
  • cambios en OpenClaw, Docker, NPM, Portainer o servicios;
  • carga real de SOURCE-003;
  • COPY real;
  • INSERT, UPDATE, DELETE, TRUNCATE o escritura real;
  • backups nuevos, dumps o artefactos runtime;
  • lectura de secret files;
  • publicacion de passwords o connection strings reales;
  • commit, push o deploy.

4. Fuente exacta

Fuente vigente:

text SOURCE-003 / Tabla 2 V2

Autoridad SQL:

text docs/tenants/alpuntodeventa/business-observer/source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql

Condiciones de uso:

  • la salida a persistir es Tabla 2;
  • Hora forma parte de la identidad;
  • los flags de extraccion futura deben forzar Tabla 2 como unico resultset;
  • SOURCE-003 / SGC Ventas es fuente viva;
  • las fechas piloto o de conciliacion deben congelarse desde snapshot y no desde una relectura posterior de SGC vivo.

5. Dependencias obligatorias

Dependencia de Source Authority V2:

  • define calculos, joins, filtros y salida Tabla 2;
  • no debe ser reemplazada por V_VENTAS cruda;
  • preserva Hora, impuestos, descuentos, CMV, contribucion, motivos, proveedor, producto, cliente, vendedor y contexto logistico.

Dependencia de mapping activo:

text docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md

Lectura requerida del mapping:

  • 68/68 columnas reales mapeadas;
  • source_row_hash_v1 cubre las 68 columnas reales;
  • line_key_v4 usa identidad documental, Hora, CodigoCliente, SKU, Vendedor y line_sequence_v1;
  • datos personales/logisticos se persisten con acceso controlado;
  • produccion final, sync diaria y carga masiva siguen no autorizadas.

6. Estrategia raw -> core -> mart

Estrategia propuesta:

  1. raw_source_003_sales_items
  2. recibiria el snapshot preparado y validado de Tabla 2 V2;
  3. preservaria las columnas de origen, metadata de extraccion, hash y lote;
  4. no haria interpretacion semantica fuerte.
  5. core_source_003_sales_items
  6. promoveria desde RAW a una capa normalizada y gobernada;
  7. preservaria tenant_id, sync_batch_id, line_key, source_row_hash, source_query_version, extracted_at, last_seen_at, created_at, updated_at y estado funcional;
  8. bloquearia duplicados por batch y por identidad logica.
  9. MART
  10. construiria agregados desde CORE;
  11. mantendria trazabilidad hacia core_source_003_sales_items;
  12. conservaria estado candidate hasta aprobacion posterior.

La estrategia no habilita sync diaria ni pipelines. Es solo el patron candidate para una carga inicial controlada futura.

7. Tablas destino

Capa Tabla Estado esperado antes de cargar
base/piloto controlado 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

8. Load package existente

No se detecto un paquete PDF-006A ni un paquete aprobado para carga inicial SOURCE-003 staging.

Se detectaron antecedentes:

  • DDL staging PDF-005B y ejecucion documentada PDF-005C;
  • candidatos y ejecuciones local-dev de RAW, CORE y MART;
  • scripts de diseno local-dev para build-mart.

Esos antecedentes son base tecnica, pero no autorizan carga inicial staging.

9. Scripts candidate

Paquete candidate preparado:

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

Archivos:

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

Regla de seguridad del paquete:

  • los scripts de escritura quedan bloqueados por defecto;
  • no contienen credenciales ni connection strings;
  • no incluyen COPY real;
  • no crean jobs, schedulers ni pipelines;
  • las operaciones que requieren datos externos quedan marcadas como BLOCKED_UNTIL_EXECUTION_GATE.

10. Validaciones previas

Validaciones previas requeridas para una ejecucion futura:

Control Esperado
SAFE POINT nuevo y limpio
target openclaw_business_observer_staging
schema business_observer presente
produccion excluida
sandbox excluido
tablas destino 7/7 presentes
row counts iniciales 0 en las 7 tablas
owner openclaw_bo_staging_owner
grants writer sin DELETE/TRUNCATE, reader/reporting read-only
PUBLIC sin grants
backup post-DDL validado fuera de Git
snapshot/fuente declarado con fecha, hash, filas y columnas
autoridad Source Authority V2 vigente
mapping mapping activo 68/68 vigente
autorizacion explicita para ejecutar carga real

11. Validaciones posteriores

Validaciones posteriores esperadas si se autorizara una carga futura:

  • RAW rows = filas esperadas del snapshot autorizado;
  • CORE rows = filas promovidas esperadas;
  • duplicados RAW por tenant_id + sync_batch_id + line_key = 0;
  • duplicados CORE por tenant_id + line_key = 0;
  • line_key nulo o vacio = 0;
  • source_row_hash nulo, vacio o no sha256 = 0;
  • line_sequence_v1 nulo o menor a 1 = 0;
  • source_query_version coincide con Source Authority V2;
  • record_status o estado equivalente queda dentro de valores permitidos;
  • MART rows esperadas conciliadas contra CORE;
  • importes principales conciliados contra snapshot autorizado;
  • produccion, sandbox, sync, scheduler y pipelines siguen sin tocarse.

12. Conteos esperados

Conteos esperados para el primer gate de ejecucion:

text RAW expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION CORE expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION MART daily expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION MART seller expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION MART customer expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION MART sku expected rows = BLOCKED_UNTIL_SNAPSHOT_AUTHORIZATION

Referencia historica local-dev no ejecutable en staging:

  • snapshot piloto local 2026-06-09: 1886 filas;
  • MART local-dev estimada desde CORE: daily 1, seller 25, customer 173, sku 180.

Esos valores no son autorizacion de carga staging. Deben revalidarse contra el snapshot autorizado del gate futuro.

13. Reglas de idempotencia

Reglas candidate:

  • bloquear carga si RAW tiene filas para el sync_batch_id autorizado;
  • bloquear promocion si CORE tiene filas para el sync_batch_id autorizado;
  • bloquear si existe tenant_id + line_key duplicado en CORE;
  • usar source_row_hash para detectar cambios de contenido;
  • no hacer hard delete;
  • no usar TRUNCATE;
  • no borrar ni reemplazar batches fuera del batch autorizado;
  • mantener last_seen_at y missing_from_source como reglas futuras, no como atajo de carga inicial.

14. Riesgo line_key_v4

line_key_v4 queda preservado como AMARILLO ACEPTADO.

Lectura obligatoria:

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

15. GO / NO-GO

GO futuro solo si:

  • existe autorizacion humana explicita para ejecutar carga real;
  • backup post-DDL valido existe fuera de Git;
  • preflight read-only pasa;
  • snapshot autorizado tiene ruta, hash, fecha, filas y columnas declaradas;
  • Source Authority V2 y mapping activo siguen vigentes;
  • conteos esperados quedan declarados antes de escribir;
  • rollback esperado queda aceptado;
  • produccion, sandbox, sync, scheduler y pipelines siguen excluidos.

NO-GO inmediato si:

  • falta autorizacion explicita;
  • falta snapshot autorizado;
  • falta backup post-DDL validado;
  • el target no es staging;
  • aparece produccion o openclaw-postgres-sandbox;
  • hay tablas con filas previas no explicadas;
  • hay drift de autoridad, mapping o columnas;
  • se intenta ejecutar COPY, sync, scheduler o pipelines en el mismo gate;
  • se requiere imprimir secretos o connection strings reales.

16. Rollback esperado

Rollback esperado para una futura carga:

  • requiere autorizacion separada;
  • debe operar solo sobre staging;
  • debe limitarse al sync_batch_id autorizado;
  • no debe usar TRUNCATE;
  • no debe tocar produccion ni sandbox;
  • debe preservar evidencia previa y posterior;
  • debe abortar si detecta filas fuera del batch autorizado o conteos no conciliados.

En este gate se publica solo un rollback candidate bloqueado por defecto. No se ejecuta rollback real.

17. Evidencia requerida

Evidencia minima para una futura ejecucion:

  • SAFE POINT inicial y final;
  • path no sensible del snapshot autorizado;
  • hash sha256 del snapshot;
  • fecha o ventana del snapshot;
  • conteo de filas y columnas;
  • version exacta de Source Authority;
  • mapping activo confirmado;
  • resultado preflight;
  • comandos ejecutados sin secretos;
  • conteos RAW/CORE/MART;
  • conciliaciones de importes;
  • resultado de idempotencia;
  • confirmacion de produccion y sandbox excluidos;
  • confirmacion de sync, scheduler y pipelines no ejecutados;
  • decision final VERDE, AMARILLO o ROJO.

18. Autorizacion requerida para futura ejecucion

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

text Autorizo ejecutar la carga inicial controlada SOURCE-003 en PostgreSQL staging Business Observer usando el paquete PDF-006A, con snapshot autorizado, conteos esperados declarados y rollback aceptado. No autorizo produccion, openclaw-postgres-sandbox, sync diaria, scheduler ni pipelines.

Sin esa autorizacion, PDF-006A permanece como candidate documental.

19. Estado final de este candidate

text PDF-006A PREPARED LOAD PACKAGE = CANDIDATE ONLY SQL EXECUTION = NOT AUTHORIZED / NOT EXECUTED SOURCE-003 LOAD = NOT EXECUTED COPY = NOT EXECUTED INSERT_UPDATE_DELETE_TRUNCATE = NOT EXECUTED SYNC_SCHEDULER_PIPELINES = NOT EXECUTED PRODUCTION = NO-GO SANDBOX = NO-GO NEXT GATE = EXPLICIT EXECUTION AUTHORIZATION