Saltar a contenido

SOURCE-003 Dedicated DB Pilot Load Gate

Fecha local: 2026-06-11

Estado: APTO PARA REVISION / NO EJECUTAR

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-DEDICATED-DB-PILOT-LOAD-GATE.md

1. Objetivo

Preparar documental y tecnicamente el gate para una futura carga piloto minima de SOURCE-003 / Tabla 2 V2 en la DB local dedicada openclaw_business_observer_dev, sin ejecutar la carga y sin modificar PostgreSQL.

Este gate deja revisable:

  • el alcance de la carga piloto minima;
  • los controles previos y posteriores;
  • el criterio de rollback;
  • el criterio de exito;
  • SQL de preflight, candidate, post-checks y rollback, todos marcados como NO EJECUTAR en esta tarea.

2. Safe point inicial

Control Resultado
rama main
git status -sb ## main...origin/main
git rev-parse HEAD 3ac34e20fec5f08356c551c515b48ce2181d553a
git ls-remote origin main 3ac34e20fec5f08356c551c515b48ce2181d553a
ultimo commit esperado docs: plan source 003 pilot load gate
decision SAFE POINT PASS

3. Documentos leidos

Read-set obligatorio aplicado:

  • docs/governance/PROJECT-CONSTITUTION.md
  • CODEX.md
  • docs/governance/ACTIVE-CONTEXT.md
  • docs/governance/GATE-CODEX-EFFICIENCY.md
  • docs/governance/GOVERNANCE-CONTROL-TOWER.md
  • docs/governance/VALIDATION-STATE.md
  • docs/governance/documentation/DOCUMENT-HIERARCHY.md
  • docs/PROJECT-STATE.md
  • docs/ROADMAP.md
  • docs/governance/operations/CURRENT-BASELINE.md
  • docs/tenants/alpuntodeventa/business-observer/README.md
  • docs/tenants/alpuntodeventa/business-observer/design/POSTGRES-LOCAL-DEV-ENVIRONMENT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CREDENTIALS-PREFLIGHT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-DEDICATED-DB-DDL-PILOT-EXECUTION-001.md

Documentos vigentes SOURCE-003 revisados:

  • sources/SOURCE-003-SGC-VENTAS-COMPROBANTES.md
  • source-authority/SOURCE-AUTHORITY-REGISTRY.md
  • source-authority/SOURCE-003-VENTAS-TABLA2-AUTHORITY.sql
  • source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY.sql
  • source-authority/SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2.sql
  • source-authority/SOURCE-003-QUERY-DELTA-REVIEW.md
  • SOURCE-003-SNAPSHOT-001.md
  • SOURCE-003-DRIFT-ANALYSIS-001.md
  • data-dictionary/SOURCE-003-TABLA2-COLUMN-DICTIONARY.md
  • design/SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md
  • design/SOURCE-003-LINE-IDENTITY-DECISION.md
  • design/SOURCE-003-SALES-ITEMS-DDL-DESIGN.md
  • design/SOURCE-003-SALES-ITEMS-PILOT-MIGRATION.md
  • design/SOURCE-003-SALES-ITEMS-PILOT-LOAD.md
  • design/SOURCE-003-SALES-ITEMS-PILOT-LOAD-001.md
  • design/SOURCE-003-SALES-ITEMS-WINDOW-PILOT-001.md
  • design/SOURCE-003-DEDICATED-DB-DDL-PILOT-GATE.md
  • design/SOURCE-003-DEDICATED-DB-DDL-PILOT-PACKAGE.md
  • design/sql/001_source_003_sales_items_design.sql
  • design/sql/002_source_003_sales_items_pilot_migration.sql
  • design/sql/002_source_003_sales_items_pilot_rollback.sql
  • design/sql/003_source_003_dedicated_db_ddl_pilot_preflight.sql
  • design/sql/003_source_003_dedicated_db_ddl_pilot_forward.sql
  • design/sql/003_source_003_dedicated_db_ddl_pilot_post_checks.sql
  • design/sql/003_source_003_dedicated_db_ddl_pilot_rollback.sql

Clasificacion operativa: DESIGN + VALIDATE + SECURITY.

4. Estado solo lectura DB

Verificacion ejecutada con consultas SELECT, default_transaction_read_only y sin imprimir secretos, passwords ni connection strings.

Control Resultado
conexion a DB dedicada PASS
database observada openclaw_business_observer_dev
tabla destino business_observer.source_003_sales_items
tabla existe PASS
filas actuales 0
owner tabla openclaw_bo_admin
openclaw_bo_admin NOLOGIN
openclaw_bo_writer NOLOGIN
openclaw_bo_reader NOLOGIN
writer SELECT, INSERT, UPDATE; sin DELETE
reader SELECT; sin INSERT, UPDATE, DELETE
DDL ejecutado en esta tarea NO
DML ejecutado en esta tarea NO

Nota operativa:

  • las variables APV_BO_LOCAL_POSTGRES_USER y APV_BO_LOCAL_POSTGRES_PASSWORD no estan cargadas en .env;
  • los roles BO estan documentados y observados como NOLOGIN;
  • la verificacion solo lectura se hizo con la credencial admin local ya existente, apuntando a la DB dedicada y forzando modo read-only.

5. Decision de fuente

Fuente exacta para la futura carga piloto minima:

text SOURCE-003-SNAPSHOT-001

Archivo local documentado, fuera de Git:

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

Hash documentado:

text 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3

Motivo de la decision:

  • es un snapshot congelado y ya documentado;
  • corresponde a una fecha cerrada;
  • ya tiene conteos, hash y agregados publicados;
  • evita depender de una relectura viva de SGC;
  • ya fue usado exitosamente en el piloto legacy local, sin habilitar produccion final.

La fuente viva SGC queda como autoridad funcional, pero no se propone consultarla durante esta carga piloto minima. Cualquier extraccion nueva desde SGC requiere autorizacion separada.

6. Query autorizada

Autoridad SQL funcional:

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

Regla obligatoria si una tarea futura aprueba una nueva extraccion:

Flag Valor
@ShowTabla1 0
@ShowTabla2 1
@ShowTabla3 0
@ShowTabla4 0
@ShowTabla5 0
@ShowTabla6 0

Para este gate, la carga piloto minima propuesta usa el snapshot ya congelado, no una ejecucion nueva de la query.

7. Alcance de carga piloto minima

Dimension Decision
entorno openclaw_business_observer_dev
schema business_observer
tabla source_003_sales_items
fuente SOURCE-003-SNAPSHOT-001
ventana temporal 2026-06-09 a 2026-06-09
dia en curso incluido NO
cantidad maxima de filas 1886
columnas destino 83 columnas fisicas
columnas negocio 68/68 columnas reales de Tabla 2 V2
modo de carga INSERT transaccional sobre tabla vacia
upsert NO para esta carga minima
DELETE / hard delete NO
missing_from_source NO
sync diaria BLOQUEADA
carga masiva BLOQUEADA
produccion final BLOQUEADA

La tabla debe seguir vacia al cierre de esta tarea.

8. Columnas destino

La carga piloto minima debe usar el DDL dedicado ya ejecutado:

text business_observer.source_003_sales_items

La tabla tiene:

  • 83 columnas fisicas;
  • 68 columnas reales de negocio segun mapping aprobado;
  • columnas tecnicas de trazabilidad;
  • primary key (id);
  • unique (tenant_id, line_key);
  • 21 constraints;
  • 8 indices secundarios requeridos.

El CSV de carga futura no debe ser el CSV raw de snapshot directo, sino un CSV preparado por pipeline revisado con las 83 columnas destino, incluyendo:

  • id;
  • tenant_id;
  • line_key;
  • line_sequence_v1;
  • source_row_hash;
  • sync_batch_id;
  • extracted_at;
  • last_seen_at;
  • created_at;
  • updated_at;
  • record_status.

9. Mapeo origen/destino

El mapping oficial vive en:

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

Reglas heredadas:

  • las 68/68 columnas reales deben estar presentes;
  • source_row_hash_v1 debe cubrir las 68 columnas reales;
  • codigos de negocio se preservan como text;
  • importes, descuentos, impuestos, costos y metricas fisicas usan numeric;
  • campos personales, logisticos y fiscales se persisten para trazabilidad, pero no se exponen sin controles posteriores.

10. Identidad de linea

Estrategia:

text line_key = line_key_v4

Formula conceptual:

text line_key_v4 = sha256(canonical( fecha, hora_origen_sgc, tipo_comp, nro_comp, tipo_doc_int, nro_int_doc, documento, codigo_cliente, sku, vendedor_codigo, line_sequence_v1 ))

Estado de identidad:

text AMARILLO ACEPTADO

Lectura:

  • apta para piloto analitico;
  • no es id fisico nativo del ERP;
  • no cierra auditoria legal perfecta de renglones;
  • debe recalcularse de forma deterministica por pipeline;
  • cualquier cambio futuro debe versionarse como line_key_v5 o superior.

11. source_row_hash

Estrategia:

text source_row_hash = source_row_hash_v1

Reglas:

  • debe calcularse fuera de PostgreSQL por pipeline revisado;
  • debe canonicalizar las 68 columnas reales de Tabla 2 V2;
  • no debe incluir columnas tecnicas como id, sync_batch_id, created_at, updated_at, extracted_at o last_seen_at;
  • debe estar no nulo y no vacio para las 1886 filas.

12. Metadata de carga

Valores propuestos:

Campo Valor
tenant_id alpuntodeventa
source_system snapshot:SOURCE-003-SNAPSHOT-001
source_object SOURCE-003 / Tabla 2 V2
source_query_version SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2
sync_batch_id UUID nuevo generado para la carga autorizada futura
extracted_at 2026-06-10T21:04:06-03:00
last_seen_at 2026-06-10T21:04:06-03:00
record_status active

sync_batch_id no se fija en este documento para evitar que una tarea futura reutilice accidentalmente un identificador sin autorizacion. Debe generarse y registrarse en la tarea de ejecucion.

13. Validaciones antes de cargar

Preflight DB:

  • DB actual = openclaw_business_observer_dev;
  • tabla destino existe;
  • owner = openclaw_bo_admin;
  • columnas = 83;
  • tabla vacia = 0 filas;
  • unique (tenant_id, line_key) existe;
  • roles y grants minimos siguen vigentes;
  • roles BO siguen NOLOGIN;
  • SOURCE-003 no fue cargado previamente.

Preflight fuente:

  • snapshot local existe fuera de Git;
  • sha256 del snapshot raw coincide con 07092c284b5b636b8a31cd616ef5b4fa5d0ce499b81c767437842b1f7edfcbc3;
  • CSV preparado de carga existe fuera de Git;
  • headers destino = 83;
  • filas = 1886;
  • fecha unica = 2026-06-09;
  • tenant_id = alpuntodeventa;
  • source_system = snapshot:SOURCE-003-SNAPSHOT-001;
  • source_object = SOURCE-003 / Tabla 2 V2;
  • source_query_version = SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2;
  • sync_batch_id igual al batch autorizado para la tarea futura;
  • record_status = active;
  • columnas de negocio = 68/68;
  • line_key_v4 distintos = 1886;
  • duplicados (tenant_id, line_key) = 0;
  • source_row_hash_v1 nulos o vacios = 0;
  • Hora formato HHMMSS = 1886;
  • nulos criticos = 0.

Conciliaciones pre-carga esperadas:

Metrica Esperado
filas 1886
importe total 48087486.83
CMV total 37881269.3025
clientes unicos 173
vendedores unicos 25
SKU unicos 180
comprobantes unicos 428

14. Validaciones despues de cargar

Post-checks esperados:

  • batch con 1886 filas;
  • fecha min = fecha max = 2026-06-09;
  • distinct line_key = 1886;
  • duplicados globales (tenant_id, line_key) = 0;
  • nulos criticos = 0;
  • source_row_hash no nulo y no vacio = 1886;
  • line_sequence_v1 no nulo = 1886;
  • line_key = line_key_v4 no nulo, no vacio y distinto para las 1886 filas;
  • Hora formato HHMMSS;
  • tenant_id = alpuntodeventa para todo el batch;
  • source_system = snapshot:SOURCE-003-SNAPSHOT-001;
  • source_object = SOURCE-003 / Tabla 2 V2;
  • source_query_version = SOURCE-003-VENTAS-VNEXT-TABLA2-AUTHORITY-V2;
  • record_status = active para las 1886 filas;
  • sync_batch_id exacto y unico para la carga autorizada;
  • conciliacion de filas, importe total y CMV;
  • conciliacion de clientes, vendedores, SKU y comprobantes unicos.

15. Controles de duplicados

Bloquean la carga:

  • duplicados en (tenant_id, line_key) dentro del CSV preparado;
  • line_key nulo o vacio;
  • line_sequence_v1 nulo;
  • colision con filas existentes en destino.

Para esta carga minima no se propone UPSERT: si la tabla no esta vacia, la carga debe detenerse.

16. Controles de nulos criticos

Campos criticos no nulos:

  • id;
  • tenant_id;
  • line_key;
  • line_sequence_v1;
  • source_row_hash;
  • fecha;
  • hora_origen_sgc;
  • tipo_comp;
  • nro_comp;
  • tipo_doc_int;
  • nro_int_doc;
  • documento;
  • codigo_cliente;
  • vendedor_codigo;
  • sku;
  • unidades;
  • importe_total_item;
  • sync_batch_id;
  • extracted_at;
  • last_seen_at;
  • record_status.

17. Rollback o limpieza piloto

Rollback propuesto:

  • no usar TRUNCATE por defecto;
  • limpiar por tenant_id + sync_batch_id + source_system + source_object + source_query_version + fecha;
  • exigir aprobacion explicita separada;
  • exigir evidencia del sync_batch_id cargado;
  • abortar dentro de la transaccion si deleted_rows <> 1886;
  • confirmar que quedan 0 filas del batch despues de la limpieza.

El script revisable queda en:

text docs/tenants/alpuntodeventa/business-observer/design/sql/004_source_003_dedicated_db_pilot_load_rollback.sql

No se ejecuto en esta tarea.

18. Criterio de exito

Una futura carga piloto minima sera exitosa solo si:

  • fue aprobada explicitamente en una tarea separada;
  • safe point inicial coincide con el esperado de esa tarea futura;
  • preflight DB y fuente pasan;
  • el snapshot raw mantiene hash esperado;
  • el CSV preparado contiene 1886 filas y 83 columnas destino;
  • la tabla estaba vacia antes de cargar;
  • la carga se ejecuta en transaccion unica;
  • se cargan exactamente 1886 filas;
  • no hay duplicados (tenant_id, line_key);
  • no hay nulos criticos;
  • agregados y conteos coinciden contra SOURCE-003-SNAPSHOT-001;
  • la evidencia queda documentada;
  • sync diaria, carga masiva y produccion final siguen bloqueadas.

19. Criterio de bloqueo

Bloquea la futura carga:

  • falta de autorizacion explicita;
  • tabla destino no vacia;
  • DB actual distinta de openclaw_business_observer_dev;
  • ausencia o cambio del snapshot;
  • sha256 del snapshot raw distinto;
  • CSV preparado inexistente o versionado por error;
  • headers destino distintos de 83;
  • filas distintas de 1886;
  • fecha distinta de 2026-06-09;
  • duplicados de line_key;
  • nulos criticos;
  • source_row_hash nulo o vacio;
  • diferencias de importe total, CMV, clientes, vendedores, SKU o comprobantes;
  • grants/roles fuera del minimo esperado;
  • intento de leer SGC vivo sin aprobacion separada;
  • intento de UPSERT, DELETE, hard delete, sync diaria, carga masiva o produccion final.

20. Scripts creados

Archivo Rol Ejecutar ahora
design/sql/004_source_003_dedicated_db_pilot_load_preflight.sql preflight DB solo lectura NO
design/sql/004_source_003_dedicated_db_pilot_load_candidate.sql candidate de carga piloto minima NO
design/sql/004_source_003_dedicated_db_pilot_load_post_checks.sql post-checks solo lectura para carga futura NO
design/sql/004_source_003_dedicated_db_pilot_load_rollback.sql limpieza por batch con guarda explicita NO

El script candidate queda documentado como NO EJECUTAR TODAVIA y contiene guardas psql que exigen variables de aprobacion explicitas. Antes del INSERT, tambien aborta si el stage contiene filas fuera del tenant, ventana, batch, metadata de fuente o record_status autorizados.

El script de rollback queda documentado como NO EJECUTAR TODAVIA y aborta si el borrado transaccional no elimina exactamente 1886 filas del batch autorizado.

21. Endurecimiento aplicado

Observaciones resueltas en esta revision:

  • candidate valida record_status = active antes del INSERT;
  • candidate valida valores exactos de source_system, source_object y source_query_version;
  • candidate valida tenant_id, sync_batch_id y ventana 2026-06-09 antes del INSERT;
  • post-checks validan metadata exacta, record_status, source_row_hash_v1, line_key_v4, filas esperadas, duplicados y nulos criticos;
  • rollback borra solo el batch autorizado con filtros de tenant, batch, metadata de fuente y fecha, y aborta si deleted_rows <> 1886.

22. Restricciones vigentes

Siguen bloqueados:

  • carga de datos en esta tarea;
  • INSERT, COPY, MERGE, UPSERT ejecutados en esta tarea;
  • cambios en PostgreSQL;
  • borrado de datos;
  • extraccion nueva desde SGC;
  • sync diaria;
  • carga masiva;
  • produccion final;
  • cambios en gestion_de_negocios_core;
  • cambios en VPS;
  • cambios en Docker;
  • cambios en OpenClaw;
  • cambios en NPM;
  • deploy del portal.

23. Decision

text APTO PARA REVISION / NO EJECUTAR

Lectura exacta:

  • el gate de carga piloto minima queda preparado;
  • la tabla dedicada existe y sigue vacia;
  • la carga piloto requiere autorizacion explicita separada;
  • el paquete no habilita sync diaria;
  • el paquete no habilita carga masiva;
  • el paquete no habilita produccion final;
  • la decision no autoriza ejecutar los SQL 004.

24. Proximo paso recomendado

Revisar humanamente este gate. Si se aprueba una tarea futura de ejecucion, generar primero el CSV preparado de 83 columnas fuera de Git, verificar el hash del snapshot raw, ejecutar solo el preflight autorizado y mantener la tabla vacia hasta el momento exacto de la carga piloto aprobada.