Saltar a contenido

SOURCE-003 Load Raw Technical Review

Fecha local: 2026-06-15

Estado: REVISION TECNICA DOCUMENTAL / LOAD-RAW NO IMPLEMENTABLE TODAVIA

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

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

1. Objetivo

Revisar tecnicamente el plan documental del futuro comando:

text python scripts/source_003_importer.py load-raw

La revision contrasta el plan contra el contrato RAW, los contratos CORE y MART, el contrato del Python importer, el skeleton, los comandos seguros inspect-source, generate-prepared y validate-prepared, el hito SOURCE-003 Data Layers y la auditoria vigente de topologia PostgreSQL en VPS.

Esta revision no implementa load-raw, no modifica Python, no crea DDL, no ejecuta SQL, no toca PostgreSQL, no genera CSV, no carga datos y no toca VPS, Docker, OpenClaw, NPM ni Portainer.

2. Veredicto ejecutivo

Resultado:

text APTO PARA DISENAR DDL RAW NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA

Lectura:

  • el plan load-raw respeta el contrato RAW en nivel documental;
  • preserva la separacion raw / core / mart;
  • bloquea correctamente el uso de postgres-sandbox como produccion;
  • define guardrails suficientes para iniciar un diseno de DDL RAW separado;
  • todavia no cierra las precondiciones necesarias para implementar escritura.

3. Respuestas de revision

Pregunta Respuesta Observacion tecnica
1. El plan respeta el contrato RAW? Si Usa metadata minima, sync_batch_id, source_row_hash, line_key, staging, validaciones previas, idempotencia, deduplicacion y rollback por batch.
2. Preserva separacion raw / core / mart? Si load-raw queda limitado a persistir evidencia gobernada; no promueve a core, no construye mart y no calcula KPI.
3. Evita usar postgres-sandbox como produccion? Si Declara explicitamente que postgres-sandbox no es produccion y que la auditoria VPS bloquea leerlo como DB productiva.
4. Quedan claros los modos plan, dry-run, execute? Si, con condicion El default debe ser plan o dry-run; --execute debe ser obligatorio y no suficiente por si solo. Falta formalizar sintaxis exacta antes de implementar.
5. Queda claro que DB puede tocarse y bajo que fingerprint? Parcialmente suficiente para plan Solo local-dev o DB dedicada aprobada. Falta documento futuro con fingerprint exacto, entorno, host, database, user, owner y permisos de la raw table.
6. Queda claro que la tabla piloto no es raw final? Si business_observer.source_003_sales_items queda como evidencia piloto, no como contrato fisico raw final.
7. Queda clara la estrategia de batch? Si Batch unico, explicito, con sync_batch_id, ventana, conteos, hashes y aprobacion.
8. Queda clara la idempotencia? Si, no implementable aun Las reglas estan claras, pero la politica exacta para batch existente y conflictos debe cerrarse antes de escribir.
9. Queda clara la deduplicacion? Si Debe detectar duplicados por tenant_id + line_key, source_row_hash, conflictos intra-batch e inter-batch.
10. Queda claro el rollback por batch? Si Rollback separado por tenant_id + sync_batch_id + source_id, sin TRUNCATE y con gate humano.
11. Quedan claros logs y auditoria? Si Incluye SAFE POINT, operador, batch, rutas, hashes, fingerprint, conteos, commit/rollback transaccional y flags de auditoria.
12. Faltan precondiciones antes de DDL RAW? Si Falta diseno fisico de raw table, catalogos, constraints, indices, grants, ownership, esquema de staging, naming y estrategia de particion o retencion si aplica.
13. Faltan precondiciones antes de implementar load-raw? Si Falta DDL RAW aprobado, rollback aprobado, fingerprint real aprobado, politica idempotente cerrada, pruebas locales sin DB y gate humano de escritura.
14. Faltan validaciones antes de ejecutar contra DB? Si Falta preflight read-only especifico para raw table futura, validacion de permisos, compatibilidad DDL/CSV, batch inexistente o politica aprobada y conteos esperados de impacto.

4. Consistencia con contrato RAW

El plan es consistente con el contrato RAW porque conserva:

  • evidencia de origen o prepared validado sin reinterpretacion semantica;
  • tenant_id = alpuntodeventa;
  • source_system, source_object y source_query_version;
  • sync_batch_id como unidad de corrida;
  • source_row_hash como identidad tecnica de contenido;
  • line_key como identidad de linea aprobada;
  • record_status, extracted_at y loaded_at;
  • validacion de filas 1886, columnas 83, fecha 2026-06-09 y hashes esperados para el batch piloto vigente.

No se detecta contradiccion documental entre el plan y el contrato RAW.

5. Separacion de capas

La separacion queda preservada:

Capa Lectura de la revision
raw Evidencia gobernada futura, con metadata, batch, hash, staging y commit controlado.
core Sigue como normalizacion futura separada; load-raw no la implementa.
mart Sigue como consumo analitico futuro separado; load-raw no calcula agregados ni KPIs.
Piloto business_observer.source_003_sales_items es antecedente y evidencia, no raw final.

6. Precondiciones antes de DDL RAW

Antes de disenar DDL RAW conviene cerrar como minimo:

  • nombre de schema y tabla raw futura;
  • columnas fisicas minimas y columnas de negocio a preservar;
  • decision sobre si raw persiste las 68 columnas reales, las 83 columnas prepared o ambas mediante grupos tecnicos diferenciados;
  • tipos fisicos para fechas, importes, cantidades, hashes y metadata;
  • constraints obligatorias para tenant_id, sync_batch_id, source_row_hash, line_key y record_status;
  • indices para batch, linea, hash y auditoria;
  • ownership y grants esperados;
  • tabla o estrategia de staging;
  • politica de retencion o historizacion si aplica;
  • rollback por batch compatible con dependencias futuras core y mart.

7. Precondiciones antes de implementar load-raw

Antes de modificar scripts/source_003_importer.py para escribir en DB deben existir:

  • DDL RAW aprobado en tarea separada;
  • rollback RAW aprobado en tarea separada;
  • fingerprint DB esperado documentado y validado por gate read-only;
  • target DB aprobada como local-dev o DB dedicada, nunca postgres-sandbox como produccion;
  • politica idempotente final para mismo batch, batch nuevo y conflictos;
  • politica de deduplicacion final intra-batch e inter-batch;
  • pruebas locales para plan y dry-run sin DB;
  • contrato de flags de auditoria que no pueda ocultar contacto DB real;
  • confirmaciones exactas requeridas para --execute;
  • evidencia de que ningun PASS read-only habilita escritura por arrastre.

8. Validaciones antes de ejecutar contra DB

Antes de cualquier ejecucion que toque PostgreSQL, deben existir y pasar:

  • SAFE POINT documentado;
  • validate-prepared PASS;
  • CSV historico y generated fuera de Git;
  • sha256 historico y generated esperados;
  • conteo 1886, columnas 83, fecha 2026-06-09;
  • 0 line_key vacios;
  • 0 source_row_hash vacios;
  • 0 duplicados criticos por identidad aprobada;
  • fingerprint DB real igual al esperado;
  • schema, tabla, owner y grants correctos;
  • batch inexistente o politica aprobada para reintento;
  • conteo esperado de filas a escribir, ignorar, bloquear o actualizar;
  • rollback por batch aprobado y no automatico;
  • logs sin secretos ni connection strings completas.

9. Riesgos detectados

Riesgos principales:

  • implementar load-raw antes de cerrar el DDL RAW;
  • reutilizar la tabla piloto como raw final por conveniencia;
  • tocar postgres-sandbox interpretandolo como produccion;
  • aceptar un PASS de validate-prepared o status como permiso de escritura;
  • definir --execute sin confirmaciones exactas de DB, batch, tabla y hash;
  • escribir sin staging o sin validaciones pre-commit;
  • duplicar el batch piloto ya validado;
  • permitir mismo sync_batch_id con contenido distinto;
  • hacer rollback demasiado amplio;
  • mezclar responsabilidades de raw con normalizacion core;
  • filtrar secretos en logs;
  • no registrar de forma monotonicamente honesta si hubo contacto DB.

10. Hallazgos principales

  • El plan es tecnicamente apto como gate documental previo.
  • La frontera raw / core / mart queda bien protegida.
  • La evidencia VPS vigente obliga a mantener postgres-sandbox fuera de toda lectura productiva.
  • La tabla piloto actual debe quedar solo como antecedente controlado.
  • La idempotencia y deduplicacion estan bien planteadas, pero aun requieren politica final antes de codigo.
  • El rollback esta correctamente separado de load-raw.
  • El siguiente trabajo correcto es DDL RAW documental, no implementacion del importer.

11. Bloqueos preservados

Quedan preservados:

  • load-raw no implementado;
  • Python no modificado;
  • DDL no creado;
  • SQL no ejecutado;
  • PostgreSQL no tocado;
  • DB no modificada;
  • runner no ejecutado;
  • CSV no generado;
  • datos no cargados;
  • VPS, Docker, OpenClaw, NPM y Portainer no tocados;
  • push no realizado;
  • deploy no realizado;
  • sync diaria, carga masiva, produccion final y OpenClaw executor bloqueados.

12. Recomendacion final

text APTO PARA DISENAR DDL RAW NO APTO PARA IMPLEMENTAR LOAD-RAW TODAVIA

El proximo paso recomendado es abrir una tarea documental separada para disenar el DDL RAW de SOURCE-003, incluyendo staging, constraints, indices, ownership, grants, rollback por batch y fingerprint objetivo.

La implementacion de load-raw debe seguir bloqueada hasta que ese DDL RAW, el rollback y el gate de DB esten aprobados.