SOURCE-003 Importer Load Raw Plan¶

Fecha local: 2026-06-15

Estado: LOAD-RAW PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTABLE

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-IMPORTER-LOAD-RAW-PLAN.md

1. Objetivo futuro de load-raw¶

Definir el plan controlado para un futuro comando:

text python scripts/source_003_importer.py load-raw

El objetivo futuro de load-raw sera cargar evidencia validada de SOURCE-003 / Tabla 2 V2 hacia una capa raw gobernada, trazable, idempotente y auditable.

Este documento no implementa el comando, no modifica Python, no crea tablas, no crea DDL, no ejecuta SQL, no toca PostgreSQL, no genera CSV y no carga datos.

2. Alcance permitido futuro¶

El alcance permitido futuro queda limitado a:

entorno local-dev o DB dedicada explicitamente aprobada;
base con fingerprint documentado y validado antes de escribir;
batch unico, explicito y aprobado;
tabla raw futura con DDL aprobado en una tarea separada;
rollback por batch aprobado en una tarea separada.

Restricciones duras:

nunca usar postgres-sandbox como produccion;
nunca asumir que postgres-sandbox es DB productiva del observer;
nunca tocar VPS produccion sin contrato previo de entorno, datos, permisos, rollback, observabilidad y aprobacion humana;
nunca ejecutar load-raw desde un PASS de status, validate-prepared o dry-run.

La auditoria vigente de VPS PostgreSQL indica que solo hay postgres-sandbox visible para ese frente. Esa evidencia bloquea cualquier lectura de ese sandbox como produccion.

3. Precondiciones obligatorias¶

Antes de implementar o ejecutar load-raw en el futuro deben existir todas estas precondiciones:

python scripts/source_003_importer.py validate-prepared con resultado PASS;
CSV prepared historico existente y fuera de Git;
CSV generated existente y validado;
contrato RAW SOURCE-003 publicado;
contrato importer publicado;
DDL raw aprobado en una tarea separada;
rollback raw aprobado en una tarea separada;
target DB aprobada como local-dev o DB dedicada, no sandbox productivo;
fingerprint DB esperado documentado;
batch explicito aprobado;
politica idempotente aprobada para batch ya existente;
evidencia de que el prepared CSV contiene 1886 filas, 83 columnas, source_row_hash no vacio y line_key no vacio.

Si falta una sola precondicion, el resultado esperado del futuro comando debe ser BLOCKED.

4. Comportamiento esperado del comando futuro¶

El comportamiento futuro debe ser seguro por defecto.

Reglas de CLI:

el modo por defecto debe ser plan o dry-run;
--dry-run debe estar disponible y no tocar DB;
--execute debe ser obligatorio para escribir;
--execute no debe alcanzar por si solo: debe combinarse con confirmaciones exactas de DB, batch, tabla y hash;
fingerprint de DB obligatorio antes de cualquier escritura;
batch explicito obligatorio;
target table explicita o gobernada por contrato;
tenant explicito obligatorio: --tenant-id alpuntodeventa;
source explicito obligatorio: SOURCE-003;
salida humana y JSON opcional con flags de auditoria.

Campos minimos de salida esperados:

json { "command": "load-raw", "result": "BLOCKED|DRY_RUN|PASS|FAIL", "tenant_id": "alpuntodeventa", "source_id": "SOURCE-003", "sync_batch_id": "1827f887-9499-4579-b4f3-234d54f41f7f", "rows_expected": 1886, "db_fingerprint_checked": true, "postgresql_touched": false, "sql_executed": false, "data_written": false, "rollback_executed": false }

En dry-run, postgresql_touched, sql_executed, data_written y rollback_executed deben quedar en false, salvo que exista un modo read-only futuro explicitamente nombrado y aprobado para fingerprint.

5. Relacion con tablas existentes¶

La tabla piloto existente:

text business_observer.source_003_sales_items

debe revisarse antes de cualquier diseno fisico futuro, pero no debe asumirse como raw final.

Lectura obligatoria:

source_003_sales_items es una tabla piloto de ventas itemizadas;
no es automaticamente la tabla raw final;
no define por si sola el contrato de raw;
no habilita produccion;
no habilita sync diaria;
no reemplaza el DDL raw futuro.

Diferencias conceptuales:

Capa	Proposito	Estado
Piloto	Evidencia controlada de carga previa y validaciones.	Existe historicamente.
Staging	Area transitoria para validar antes de commit.	Futura, no implementada.
Raw	Evidencia persistida gobernada del origen o prepared validado.	Contractual, no implementada.
Produccion	Entorno operativo final con contratos, permisos, observabilidad y rollback.	Bloqueada.

6. Validaciones previas futuras¶

Antes de escribir, load-raw debe validar como minimo:

DB correcta por fingerprint;
schema correcto;
tabla correcta;
ownership correcto;
grants correctos;
target table compatible con contrato raw aprobado;
batch inexistente o politica idempotente clara;
row count esperado 1886;
columnas esperadas 83 para prepared CSV vigente;
hashes source_row_hash no vacios;
line_key no vacio;
tenant_id = alpuntodeventa;
sync_batch_id = 1827f887-9499-4579-b4f3-234d54f41f7f para el batch piloto vigente, si ese batch se usa como evidencia;
record_status = active;
fecha unica esperada 2026-06-09 para el batch piloto vigente;
CSV fuera de Git;
sha256 esperado del prepared historico: 3f16a957a79fc84d4ca37930988287cb81f05166210d057fcf8b45007f184afe;
sha256 esperado del generated vigente: 6fb44d9870a567e728df9bbdcc6b83279d84791bd732626c9e19ccf3a28dc903.

Si cualquier validacion falla, el futuro comando debe abortar antes de escribir.

7. Transaccion esperada¶

La futura escritura debe ocurrir en una unica transaccion controlada:

text BEGIN fingerprint/checks de sesion carga a staging temporal o area controlada validaciones post-copy/pre-commit insercion o merge gobernado hacia raw validaciones finales pre-commit COMMIT solo si todo pasa ROLLBACK si algo falla

Reglas:

staging temporal o carga controlada obligatoria;
no escribir directo sin validaciones intermedias;
no hacer COMMIT si faltan conteos, hashes, batch, grants o checks de integridad;
no ejecutar rollback automatico de batches anteriores;
no usar TRUNCATE;
no borrar datos fuera del batch actual;
registrar evidencia si una transaccion falla.

8. Idempotencia¶

La idempotencia futura debe proteger contra duplicacion de filas y contra reintentos ambiguos.

Reglas:

mismo sync_batch_id y mismo contenido: debe quedar como reintento seguro o BLOCKED segun politica aprobada;
mismo sync_batch_id con contenido distinto: BLOCKED;
batch nuevo con filas ya existentes por tenant_id + line_key: aplicar politica aprobada antes de escribir;
id tecnico no puede ser identidad funcional;
source_row_hash debe gobernar deteccion de cambios;
line_key debe gobernar identidad de linea cuando aplique.

La politica exacta debe estar documentada antes de implementar escritura.

9. Deduplicacion¶

Antes de cargar a raw, el futuro comando debe detectar:

duplicados internos por tenant_id + line_key;
duplicados internos por source_row_hash si aplica;
conflictos con datos ya existentes del mismo batch;
conflictos con datos existentes de otros batches;
lineas sin line_key;
filas sin source_row_hash.

Para el batch piloto vigente el criterio esperado es:

1886 filas;
0 line_key vacios;
0 source_row_hash vacios;
0 duplicados criticos por identidad aprobada.

10. Rollback por batch¶

El rollback futuro debe ser un comando separado:

text python scripts/source_003_importer.py rollback-batch

load-raw no debe ejecutar rollback automatico de datos ya commiteados.

Reglas obligatorias:

rollback solo por tenant_id + sync_batch_id + source_id;
fingerprint DB obligatorio;
aprobacion humana separada;
conteo esperado de filas a afectar;
bloqueo si hay dependencias en core o mart;
prohibido TRUNCATE;
prohibido borrar batches ajenos;
evidencia antes y despues.

11. Logs y auditoria esperados¶

El futuro comando debe registrar:

SAFE POINT;
comando;
operador o contexto de aprobacion;
tenant;
source;
batch;
ventana;
raw/prepared paths;
hashes esperados y observados;
target DB fingerprint;
target schema y table;
resultado de prevalidaciones;
cantidad de filas staged;
cantidad de filas insertadas, actualizadas, ignoradas o bloqueadas;
validaciones post-copy/pre-commit;
commit o rollback transaccional;
flags de auditoria: postgresql_touched, sql_executed, data_written, rollback_executed, sync_enabled.

Los logs no deben imprimir passwords, tokens, connection strings completas ni secretos.

12. Outputs esperados del comando¶

Outputs minimos:

resultado DRY_RUN, PASS, FAIL o BLOCKED;
resumen legible para operador;
JSON opcional;
exit code estable;
evidencia lista para documentar una ejecucion futura;
lista de guardrails evaluados;
lista de bloqueos preservados;
conteos esperados y observados;
decision final.

En esta etapa documental, la unica decision valida es:

text LOAD-RAW PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTABLE

13. Riesgos¶

Riesgos principales:

confundir tabla piloto con raw final;
usar postgres-sandbox como produccion;
ejecutar contra VPS sin contrato de entorno;
duplicar batch ya cargado;
escribir con fingerprint DB incorrecto;
aceptar drift de hash o conteo;
hacer commit parcial;
borrar datos por rollback demasiado amplio;
filtrar secretos en logs;
interpretar un PASS read-only como autorizacion de escritura;
mezclar piloto, staging, raw y produccion;
avanzar a sync diaria antes de cerrar idempotencia y observabilidad.

Mitigacion:

defaults seguros;
--execute obligatorio para escritura;
fingerprint obligatorio;
batch explicito;
target table gobernada;
staging y validaciones pre-commit;
rollback separado;
evidencia por batch;
produccion bloqueada hasta contrato previo.

14. Criterios de aceptacion para futura implementacion¶

Una futura implementacion de load-raw solo sera aceptable si:

mantiene dry-run como camino seguro;
exige --execute para escribir;
exige tenant, source, batch, hash y target;
valida fingerprint DB;
valida validate-prepared PASS;
valida row count 1886 para el batch piloto vigente;
valida hashes no vacios;
valida line_key no vacio;
bloquea duplicados;
usa transaccion con staging o carga controlada;
ejecuta validaciones post-copy/pre-commit;
commitea solo si todo pasa;
revierte la transaccion si falla antes de commit;
no ejecuta rollback de batches anteriores;
emite logs seguros;
emite JSON de auditoria;
preserva sync_enabled=false;
no toca postgres-sandbox como produccion;
no toca VPS produccion sin contrato especifico;
tiene pruebas locales sin DB para plan/dry-run;
tiene una tarea separada aprobando DDL raw;
tiene una tarea separada aprobando rollback por batch.

15. Que NO habilita¶

Este plan no habilita:

sync diaria;
carga masiva;
produccion;
OpenClaw executor;
jobs automaticos;
scheduler;
promote-core;
build-mart;
rollback real;
DDL;
tablas nuevas;
ejecucion SQL;
tocar PostgreSQL;
tocar VPS;
tocar Docker;
tocar OpenClaw;
tocar NPM;
deploy;
push.

16. Decision¶

text LOAD-RAW PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTABLE

El plan controlado para el futuro comando load-raw del importer SOURCE-003 queda documentado. La implementacion y cualquier escritura siguen bloqueadas hasta una tarea futura con aprobacion explicita, DDL raw aprobado, rollback aprobado, fingerprint DB y gate humano.