Saltar a contenido

SOURCE-003 Importer Promote Core Plan

Fecha local: 2026-06-15

Estado: PROMOTE-CORE PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

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

1. Objetivo

Disenar documentalmente el futuro flujo:

powershell python scripts/source_003_importer.py promote-core

El comando futuro debera promover evidencia ya cargada y validada desde RAW local-dev hacia una tabla CORE gobernada de negocio, preservando trazabilidad, normalizacion, idempotencia y rollback logico por batch.

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

2. Safe point documental

Control Resultado
workspace C:\APV\openclawai
rama main
git status --short --branch inicial ## main...origin/main
git rev-parse HEAD inicial 8aa0c16171158996392d959d0903d14e24a173a6
ultimo commit inicial 8aa0c16 docs: review source 003 raw local dev execution
decision SAFE POINT PASS

3. Documentos base leidos

  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CORE-LAYER-CONTRACT.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-LOAD-RAW-LOCAL-DEV-POST-EXECUTION-REVIEW.md
  • docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-RAW-DDL-LOCAL-DEV-FORWARD-001.md
  • scripts/source_003_importer.py

Lectura vigente:

  • RAW local-dev tiene 1886 filas validadas;
  • batch autorizado: 1827f887-9499-4579-b4f3-234d54f41f7f;
  • tabla RAW final local-dev: business_observer.raw_source_003_sales_items;
  • promote-core existe en el importer solo como comando futuro declarado y bloqueado;
  • contrato CORE esta documentado pero no implementado;
  • no existe todavia DDL CORE candidato aprobado.

4. Preconditions

El futuro promote-core solo podra avanzar si antes se cumplen todas estas condiciones:

  • ejecutar desde C:\APV\openclawai;
  • rama y HEAD documentados en un SAFE POINT nuevo;
  • target limitado a local-dev;
  • DB permitida: openclaw_business_observer_dev;
  • schema permitido: business_observer;
  • RAW source table existente: business_observer.raw_source_003_sales_items;
  • RAW source table validada con 1886 filas del batch autorizado;
  • batch permitido exactamente: 1827f887-9499-4579-b4f3-234d54f41f7f;
  • sync_enabled=false;
  • produccion no involucrada;
  • postgres-sandbox no usado como produccion;
  • source_row_hash no vacio en todas las filas RAW del batch;
  • line_key no vacio en todas las filas RAW del batch;
  • loaded_at no nulo;
  • 0 duplicados por tenant_id + line_key dentro del batch;
  • contrato CORE vigente y revisado;
  • DDL CORE candidato disenado, revisado y ejecutado en local-dev antes de cualquier promocion;
  • rollback o rebuild por batch disenado antes de escribir CORE;
  • autorizacion humana explicita para cualquier futura escritura.

Si alguna precondicion falla, el resultado esperado del comando futuro debe ser FAIL o BLOCKED, sin escrituras.

5. RAW source table

La unica fuente RAW permitida para este plan es:

text database: openclaw_business_observer_dev schema: business_observer table: raw_source_003_sales_items relation: business_observer.raw_source_003_sales_items

Reglas:

  • leer solo el batch autorizado;
  • no leer la tabla piloto business_observer.source_003_sales_items como fuente de promocion;
  • no consultar SGC vivo;
  • no regenerar prepared CSV;
  • no recalcular identidad de linea si ya viene validada desde RAW;
  • preservar metadata RAW como evidencia de trazabilidad.

6. Futura CORE target table

Tabla candidata futura, pendiente de DDL:

text database: openclaw_business_observer_dev schema: business_observer table candidate: core_source_003_sales_items relation candidate: business_observer.core_source_003_sales_items

El nombre fisico queda propuesto para diseno del DDL CORE candidato. No queda aprobado hasta que exista:

  • DDL CORE candidato;
  • revision tecnica del DDL CORE;
  • ejecucion DDL CORE local-dev;
  • post-checks CORE con tabla vacia;
  • grants y ownership revisados;
  • rollback/rebuild CORE por batch documentado.

7. Batch permitido

El unico batch permitido para este plan es:

text 1827f887-9499-4579-b4f3-234d54f41f7f

Reglas:

  • cualquier otro sync_batch_id debe quedar BLOCKED;
  • un batch vacio debe quedar FAIL;
  • un batch parcial debe quedar FAIL;
  • un batch con 1886 filas y checks RAW en verde puede pasar a etapa de validacion pre-core;
  • el batch no habilita produccion ni sync diaria.

8. Reglas RAW -> CORE

La promocion futura debe convertir evidencia RAW en registros CORE de negocio:

RAW CORE esperado
tenant_id tenant_id obligatorio, valor alpuntodeventa
sync_batch_id sync_batch_id preservado
line_key line_key preservado como identidad logica
source_row_hash source_row_hash preservado para auditoria y cambios
source_system source_system preservado
source_object source_object preservado
source_query_version source_query_version preservado
extracted_at extracted_at preservado
loaded_at raw_loaded_at o equivalente de trazabilidad
campos de negocio raw columnas CORE canonicas normalizadas
record_status core_record_status o estado derivado aprobado

Reglas bloqueantes:

  • no perder trazabilidad hacia RAW;
  • no hacer enriquecimiento con SOURCE-001 o SOURCE-002;
  • no calcular KPIs de mart;
  • no corregir importes sin regla documentada;
  • no convertir silenciosamente tipos invalidos;
  • no usar surrogate tecnico como unica clave de negocio;
  • no hacer hard delete.

9. Normalizacion

Reglas minimas del futuro promote-core:

  • textos con trim lateral;
  • vacios sin valor semantico a NULL;
  • codigos de cliente, producto, vendedor, proveedor y repartidor preservados como texto canonico;
  • nombres legibles preservados como texto normalizado;
  • fecha comercial a date;
  • hora del origen a time cuando sea valida;
  • valores raw relevantes preservados como *_raw;
  • canal separado entre channel_raw y channel_normalized;
  • direccion, localidad y provincia de entrega preservadas como raw hasta que exista normalizacion territorial aprobada;
  • importes y cantidades con signo de negocio preservado segun comprobante;
  • estados RAW mapeados solo contra catalogo aprobado;
  • quality_status debe reflejar si el registro queda valid, warning, blocked o equivalente aprobado.

10. Tipos de datos

Tipos candidatos para el DDL CORE:

Grupo Tipo logico requerido
claves y codigos text canonico no vacio cuando sean obligatorios
tenant_id text, valor esperado alpuntodeventa
sync_batch_id uuid o text con validacion UUID, definir en DDL
line_key text no vacio
source_row_hash text sha256 no vacio
fecha comercial date
hora comercial time nullable si el origen no convierte
timestamps tecnicos timestamptz o convencion equivalente documentada
cantidades numeric, no float
importes numeric, no float
porcentajes numeric, unidad documentada
flags boolean solo si el catalogo raw esta cerrado
estados text con CHECK o catalogo cerrado
notas de calidad text nullable

El DDL CORE candidato debe fijar precision y escala de numeric antes de implementar.

11. Claves logicas

Clave logica minima candidata:

text tenant_id + line_key

Clave de auditoria minima candidata:

text tenant_id + sync_batch_id + source_row_hash

Clave de promocion por batch:

text tenant_id + sync_batch_id + line_key

Reglas:

  • tenant_id es obligatorio en todas las claves;
  • line_key identifica la linea de negocio;
  • source_row_hash detecta cambios de contenido;
  • sync_batch_id permite auditar, reconstruir y revertir logicamente;
  • id tecnico, si existe, no reemplaza las claves logicas.

12. Idempotencia

El futuro comando debe ser idempotente:

  • reintentar el mismo batch con mismo contenido no duplica registros;
  • reintentar el mismo batch con distinto contenido queda BLOCKED;
  • reintentar un batch ya promovido debe permitir verificacion sin escritura;
  • la salida debe reportar inserted, updated, unchanged y blocked;
  • antes de escribir debe poder mostrar un plan de cambios esperado;
  • toda escritura debe quedar asociada a tenant_id, sync_batch_id, line_key y source_row_hash.

Estrategia candidata:

  • usar staging transaccional o CTE gobernado;
  • validar conteos y duplicados antes de tocar CORE;
  • aplicar UPSERT solo con clave aprobada en DDL CORE;
  • bloquear cambios conflictivos dentro del mismo batch;
  • registrar promoted_at con timestamp de DB o politica documentada.

13. Deduplicacion

La deduplicacion futura debe distinguir:

Caso Regla
duplicado exacto mismo tenant_id + line_key + source_row_hash; tratar como unchanged si ya esta promovido
duplicado interno de batch mismo tenant_id + line_key dentro del batch; FAIL
conflicto de cambio mismo tenant_id + line_key con distinto source_row_hash; BLOCKED o update gobernado segun DDL
batch repetido mismo sync_batch_id ya promovido; no duplicar
reemplazo autorizado requiere gate separado y evidencia humana

No se permite deduplicar solo por orden fisico, posicion del CSV o surrogate tecnico.

14. Rollback / rebuild por batch

El rollback futuro de CORE debe ser logico o reconstruible por batch.

Reglas obligatorias:

  • exigir tenant_id;
  • exigir sync_batch_id;
  • exigir conteo esperado de filas a afectar;
  • exigir evidencia de promocion previa;
  • exigir aprobacion humana separada;
  • prohibir TRUNCATE;
  • prohibir borrados sin filtro completo de batch;
  • bloquear rollback si MART ya depende del batch sin plan de rebuild;
  • preferir invalidacion o core_record_status antes que borrar evidencia;
  • documentar invalidated, replaced, unchanged y blocked.

Rebuild candidato:

  • invalidar o aislar registros CORE del batch;
  • reconstruir desde RAW source table validada;
  • recalcular solo transformaciones CORE aprobadas;
  • revalidar conteos, claves, importes y hashes;
  • dejar evidencia documental antes de habilitar MART.

15. Validaciones pre

Validaciones minimas antes de cualquier escritura futura:

  • DB observada = openclaw_business_observer_dev;
  • schema = business_observer;
  • RAW table existe;
  • CORE target table existe y esta aprobada por DDL local-dev;
  • batch = 1827f887-9499-4579-b4f3-234d54f41f7f;
  • RAW batch rows = 1886;
  • RAW total esperado para este gate = 1886 o decision explicitamente documentada si hay mas batches futuros;
  • tenant_id = alpuntodeventa;
  • source_row_hash no vacio;
  • line_key no vacio;
  • loaded_at no nulo;
  • 0 duplicados por tenant_id + line_key dentro del batch;
  • columnas CORE requeridas presentes en DDL;
  • conversiones de fecha, hora, cantidades e importes sin errores;
  • estados y canales dentro de catalogos aprobados o bloqueados;
  • plan de cambios calculado antes de escribir.

16. Validaciones post

Validaciones minimas despues de una promocion futura:

  • filas CORE afectadas esperadas = 1886 para el batch autorizado;
  • inserted + updated + unchanged = 1886;
  • blocked = 0;
  • tenant_id unico y esperado;
  • sync_batch_id unico y esperado para la corrida;
  • 0 line_key vacios;
  • 0 source_row_hash vacios;
  • 0 duplicados por clave CORE aprobada;
  • promoted_at no nulo;
  • importes y cantidades conciliados contra RAW;
  • conteos por fecha comercial conciliados contra RAW;
  • auditabilidad desde CORE hacia RAW por tenant_id + sync_batch_id + line_key + source_row_hash;
  • sync_enabled=false;
  • produccion no tocada.

17. Relacion futura con MART

promote-core no construye MART.

El resultado CORE futuro debe habilitar, en una etapa posterior separada, el flujo:

text core -> mart

Reglas:

  • CORE conserva granularidad de linea;
  • MART agrega, calcula KPIs y prepara consumo;
  • MART no corrige identidad ni tipos que debieron resolverse en CORE;
  • MART debe poder auditarse hacia CORE y RAW por tenant_id, line_key, sync_batch_id y source_row_hash;
  • cualquier build-mart futuro requiere plan, DDL o vistas, validaciones y gate separados.

18. Que falta antes de implementar

Antes de tocar Python o ejecutar promote-core, faltan estos entregables:

  1. DDL CORE candidato
  2. revision DDL CORE
  3. ejecucion DDL CORE local-dev

Ademas deben quedar cerrados:

  • nombre fisico definitivo de la tabla CORE;
  • columnas, constraints, indices, owner y grants;
  • precision de numeric;
  • politica de promoted_at;
  • catalogos de estados, canales y calidad;
  • estrategia de update vs invalidacion;
  • rollback/rebuild CORE por batch;
  • salida JSON esperada del comando;
  • flags de autorizacion exactos para escritura local-dev.

19. Prohibiciones preservadas

Este plan mantiene bloqueado:

  • modificar Python;
  • tocar PostgreSQL;
  • ejecutar SQL;
  • crear tablas;
  • cargar datos;
  • tocar CORE/MART real;
  • generar CSV;
  • ejecutar runner;
  • usar VPS, Docker, OpenClaw, NPM o Portainer;
  • hacer push o deploy;
  • habilitar produccion;
  • habilitar sync diaria.

20. Conclusion

text PROMOTE-CORE PLAN DOCUMENTADO / NO IMPLEMENTADO / NO EJECUTADO APTO PARA DISENAR DDL CORE CANDIDATO NO APTO PARA PRODUCCION NO APTO PARA SYNC DIARIA

El futuro flujo python scripts/source_003_importer.py promote-core queda disenado documentalmente como promocion gobernada desde business_observer.raw_source_003_sales_items hacia una tabla CORE candidata pendiente de DDL.

No se implemento Python, no se ejecuto el importer, no se toco PostgreSQL, no se ejecuto SQL, no se crearon tablas, no se cargaron datos, no se genero CSV y no se toco CORE/MART real.