Saltar a contenido

SOURCE-003 Core Layer Contract

Fecha local: 2026-06-15

Estado: CONTRATO CORE DOCUMENTADO / NO IMPLEMENTADO

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/SOURCE-003-CORE-LAYER-CONTRACT.md

1. Proposito

Definir documentalmente el contrato formal de la capa core para SOURCE-003 / SGC Ventas / Tabla 2 V2.

La capa core es el primer modelo gobernado de negocio. Toma evidencia validada desde raw y artefactos prepared CSV, normaliza campos, tipos e identidades logicas, y deja una base estable para construir mart sin perder trazabilidad hacia el origen.

Este contrato se ubica dentro de la arquitectura objetivo:

text raw -> prepared CSV -> core -> mart -> Python importer/runner -> OpenClaw executor -> sync futura

Este documento no implementa tablas, no crea DDL, no ejecuta SQL, no toca PostgreSQL, no ejecuta runner, no genera CSV y no carga datos.

2. Raw, Prepared CSV y Core

Capa Responsabilidad Que no hace
raw Preserva evidencia del origen con metadata tecnica, hashes y batch. No corrige negocio ni decide semantica final.
prepared CSV Materializa un artefacto reproducible y validado desde raw, listo para gates controlados. No es modelo canonico de negocio ni habilita produccion.
core Normaliza entidades, tipos, claves logicas y reglas de negocio basicas para consumo gobernado. No calcula indicadores finales, recomendaciones ni automatizaciones.

Regla de interpretacion:

  • raw responde que se observo;
  • prepared CSV responde como se preparo la evidencia para carga controlada;
  • core responde que representa esa evidencia dentro del modelo de negocio;
  • mart respondera preguntas analiticas, KPIs y vistas de consumo.

3. Criterios para promover Raw -> Core

Una fila o batch de SOURCE-003 solo puede promoverse a core si cumple:

  • contrato raw vigente documentado;
  • artefacto prepared CSV validado o raw table futura validada;
  • tenant_id unico y esperado;
  • sync_batch_id declarado, unico para la corrida y trazable;
  • source_row_hash no vacio y calculado con regla canonica vigente;
  • line_key no vacio y estable para la identidad de linea aprobada;
  • columnas minimas presentes segun diccionario y mapping vigentes;
  • tipos convertibles sin perdida silenciosa;
  • deduplicacion interna del batch aprobada;
  • ventana de negocio dentro del alcance aprobado;
  • validaciones de importes, cantidades, fechas y estados sin errores bloqueantes;
  • decision humana o gate documental si hay drift, reproceso o reemplazo de batch.

Un PASS de promocion raw -> core no habilita mart, sync diaria, carga masiva, produccion final ni OpenClaw executor.

4. Columnas Core Candidatas

La capa core futura para SOURCE-003 debe modelar columnas candidatas en grupos logicos. Los nombres exactos de tabla y columnas fisicas quedan fuera de este contrato.

Grupo Columnas candidatas
Identidad tenant tenant_id
Identidad de linea line_key, line_sequence, source_row_hash
Batch y trazabilidad sync_batch_id, source_system, source_object, source_query_version, extracted_at, loaded_at, promoted_at
Documento comercial business_date, document_type, document_number, document_status, document_time
Cliente customer_code, customer_name, customer_tax_id, customer_status_raw
Producto sku, product_name, brand, supplier_code, supplier_name
Vendedor y canal seller_code, seller_name, channel_raw, channel_normalized
Cantidades quantity, unit_quantity, package_quantity
Importes gross_amount, net_amount, discount_amount, tax_amount, cost_amount, contribution_amount
Logistica delivery_address_raw, delivery_city_raw, delivery_province_raw, delivery_driver_code, delivery_driver_name
Estado core core_record_status, last_seen_at, missing_from_source, valid_from, valid_to
Auditoria created_at, updated_at, created_by, updated_by, quality_status, quality_notes

Regla: core puede conservar campos raw relevantes como *_raw, pero debe exponer nombres canonicos para consumo posterior.

5. Claves logicas

tenant_id

tenant_id es obligatorio y debe ser alpuntodeventa para este contrato. Toda clave logica de core debe incluirlo para preservar aislamiento multi-tenant.

line_key

line_key identifica funcionalmente una linea de venta dentro de SOURCE-003. Debe venir desde la identidad aprobada para Tabla 2 V2 y no debe derivarse de posicion fisica del CSV ni de un surrogate tecnico aislado.

source_row_hash

source_row_hash representa el contenido canonico de la fila fuente. En core debe preservarse para detectar cambios, comparar batches y auditar la promocion desde raw.

sync_batch_id

sync_batch_id identifica la corrida gobernada que origina la promocion. En core debe permitir filtrar, auditar, reconciliar y revertir logicamente una promocion por batch.

Clave logica minima candidata:

text tenant_id + line_key

Clave de auditoria minima candidata:

text tenant_id + sync_batch_id + source_row_hash

6. Reglas de normalizacion

Reglas minimas:

  • trim de espacios laterales en textos;
  • normalizacion de vacios a NULL cuando el campo no tenga valor semantico;
  • preservacion de valores originales relevantes en campos *_raw;
  • nombres canonicos en snake_case;
  • fechas de negocio separadas de timestamps tecnicos;
  • Hora del origen convertida a tiempo canonico cuando sea valida y preservada como raw si hay ambiguedad;
  • canal raw separado de canal normalizado;
  • vendedor transaccional separado de vendedor asignado futuro;
  • cliente y producto referenciados por codigos canonicos, no solo por nombre;
  • importes con signo de negocio preservado segun tipo de comprobante;
  • textos de direccion, localidad y provincia preservados como raw hasta que exista normalizacion territorial aprobada;
  • ningun enriquecimiento por SOURCE-001 o SOURCE-002 debe hacerse dentro de core SOURCE-003 sin contrato de cruce separado.

7. Reglas de tipos de datos

Reglas candidatas para implementacion futura:

Tipo logico Regla
Identificadores Texto canonico no vacio cuando sean claves de negocio.
Fechas date para fecha comercial; no mezclar con timestamps tecnicos.
Horas time cuando el formato sea valido; conservar raw si falla conversion.
Timestamps Con zona o convencion documentada; separar extracted_at, loaded_at y promoted_at.
Cantidades Decimal con escala suficiente; prohibido convertir silenciosamente a entero.
Importes Decimal exacto, no float; escala suficiente para ventas, costos, impuestos y descuentos.
Porcentajes Decimal normalizado y documentado como porcentaje o factor.
Booleanos Catalogo explicito (true/false) derivado de valores raw aprobados.
Estados Catalogos cerrados para core_record_status, quality_status y missing_from_source.
Hashes Texto sha256 o formato aprobado, no recalculado de forma ambigua.

Si un valor no convierte con la regla aprobada, el batch debe quedar FAIL o BLOCKED; no se permite coercion silenciosa.

8. Reglas de deduplicacion

La deduplicacion de core debe distinguir:

  • duplicado exacto: mismo tenant_id + line_key + source_row_hash;
  • conflicto de cambio: mismo tenant_id + line_key con distinto source_row_hash;
  • reproceso de batch: mismo sync_batch_id con contenido ya promovido;
  • reemplazo autorizado: batch nuevo que corrige o actualiza una ventana previamente promovida.

Reglas minimas:

  • bloquear duplicados dentro del mismo batch por tenant_id + line_key;
  • bloquear line_key vacios;
  • no usar id tecnico como unica deduplicacion;
  • no hacer hard delete si una fila desaparece de una fuente viva;
  • usar missing_from_source o estado equivalente cuando aplique;
  • requerir gate separado para resolver conflictos de batches ya promovidos.

9. Reglas de idempotencia

La promocion futura a core debe ser idempotente.

Reglas:

  • reintentar el mismo batch con el mismo contenido no debe duplicar filas;
  • reintentar el mismo batch con contenido distinto debe quedar BLOCKED;
  • un batch ya promovido debe poder verificarse sin escribir;
  • el resultado de promocion debe ser trazable por tenant_id, sync_batch_id, line_key y source_row_hash;
  • cambios detectados por source_row_hash deben tratarse como actualizacion gobernada, no como nueva linea silenciosa;
  • toda escritura futura debe poder producir conteos esperados de insert, update, unchanged y blocked antes de ejecutar.

10. Validaciones minimas

Antes de aceptar una promocion raw -> core futura deben pasar como minimo:

  • tenant_id = alpuntodeventa;
  • sync_batch_id informado y esperado;
  • source_row_hash no vacio;
  • line_key no vacio;
  • 0 duplicados en tenant_id + line_key dentro del batch;
  • columnas requeridas presentes;
  • tipos convertibles sin coercion silenciosa;
  • fechas de negocio validas y dentro de ventana aprobada;
  • importes y cantidades parseables como decimal;
  • estados raw dentro de valores observados o documentados;
  • conteo de filas esperado;
  • reconciliacion minima de importe total y CMV cuando exista evidencia;
  • rutas Windows validadas si se usan artefactos locales;
  • artefactos con datos reales fuera de Git;
  • sin dependencias a OpenClaw executor para promover core.

11. Errores esperados

Error Ejemplo Resultado esperado
Identidad ausente line_key vacio o nulo. FAIL
Hash ausente source_row_hash vacio. FAIL
Duplicado interno Dos filas con mismo tenant_id + line_key. FAIL
Cambio conflictivo Mismo sync_batch_id con contenido distinto. BLOCKED
Drift de fuente viva Conteos o importes cambiaron contra evidencia congelada. BLOCKED
Tipo invalido Importe, cantidad, fecha u hora no convertible. FAIL
Catalogo desconocido Estado o canal fuera de valores documentados. BLOCKED
Batch no autorizado sync_batch_id no coincide con el gate. BLOCKED
Trazabilidad incompleta Falta source_query_version o metadata de origen. FAIL
Ruta insegura Artefacto con datos reales versionado en Git o path inexistente. FAIL

12. Rollback logico por batch

El rollback futuro de core debe ser logico y 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 borrado sin filtro completo de batch;
  • preferir marcar estado de reversa o invalidacion antes que borrar evidencia;
  • bloquear rollback si ya existen dependencias en mart sin plan de reversa;
  • documentar inserts, updates, unchanged y registros invalidados.

Rollback logico no significa restaurar produccion. Significa dejar trazable que una promocion de batch queda revertida, reemplazada o invalidada.

13. Relacion Core -> Mart

core debe alimentar mart con datos normalizados y trazables.

Reglas:

  • core conserva granularidad de linea y semantica de negocio base;
  • mart agrega, calcula KPIs y prepara consumo por dashboards, reportes, alertas o recomendaciones;
  • mart no debe corregir problemas de identidad que debieron resolverse en core;
  • mart debe poder auditarse hacia tenant_id, line_key, source_row_hash y sync_batch_id;
  • indicadores como ventas por cliente, vendedor, SKU, canal, margen, contribucion, recuperacion o riesgo deben derivar desde core o cruces aprobados, no desde snapshots ambiguos.

14. Que NO habilita

Este contrato no habilita:

  • sync diaria;
  • carga masiva;
  • produccion final;
  • OpenClaw executor;
  • scheduler;
  • runner en modo escritura;
  • generacion de CSV;
  • carga a PostgreSQL;
  • creacion de tablas;
  • DDL;
  • DML;
  • ejecucion SQL;
  • rollback real;
  • deploy;
  • push.

15. Bloqueos preservados

Quedan preservados:

  • PostgreSQL no tocado;
  • SQL no ejecutado;
  • DB no modificada;
  • runner no ejecutado;
  • CSV no generado;
  • datos no cargados;
  • VPS, Docker, OpenClaw y NPM no tocados;
  • clientes y productos siguen no iniciados en runtime;
  • cualquier sync futura requiere contratos mart, importer, executor, gates, observabilidad, idempotencia, rollback, secretos y aprobacion humana.

16. Relacion con documentos vigentes

Documentos base:

  • BUSINESS-OBSERVER-DATA-LAYERS-ARCHITECTURE.md;
  • SOURCE-003-RAW-LAYER-CONTRACT.md;
  • SOURCE-003-PYTHON-IMPORTER-CONTRACT.md;
  • SOURCE-003-PYTHON-IMPORTER-SKELETON-001.md;
  • SOURCE-003-IMPORTER-GENERATE-PREPARED-001.md;
  • SOURCE-003-IMPORTER-VALIDATE-PREPARED-001.md;
  • SOURCE-003-TABLA2-COLUMN-DICTIONARY.md;
  • SOURCE-003-SALES-ITEMS-COLUMN-MAPPING.md;
  • SOURCE-003-LINE-IDENTITY-DECISION.md.

Lectura vigente:

  • contrato RAW documentado y no implementado;
  • piloto dedicado SOURCE-003 en verde;
  • 1886 filas cargadas en el piloto historico;
  • batch 1827f887-9499-4579-b4f3-234d54f41f7f;
  • prepared CSV validado fuera de Git;
  • importer seguro con inspect-source, generate-prepared y validate-prepared;
  • sync diaria, carga masiva, produccion final y OpenClaw executor bloqueados.

17. Decision

text CONTRATO CORE DOCUMENTADO / NO IMPLEMENTADO

El contrato formal de la capa core para SOURCE-003 queda documentado como base de normalizacion de negocio para el flujo futuro raw -> prepared CSV -> core -> mart.

No se implementa tabla core, no se crea DDL, no se toca PostgreSQL, no se ejecuta SQL, no se ejecuta runner, no se genera CSV, no se cargan datos y no se habilita sync diaria, carga masiva, produccion final ni OpenClaw executor.