Saltar a contenido

SOURCE-003 Mart Layer Contract

Fecha local: 2026-06-15

Estado: CONTRATO MART 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-MART-LAYER-CONTRACT.md

1. Proposito

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

La capa mart es la capa de consumo analitico gobernado. Toma datos normalizados desde core, calcula metricas, agrega granularidades utiles y prepara lecturas para dashboards, reportes, consultas asistidas por LLM y futuras recomendaciones comerciales.

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, Core y Mart

Capa Responsabilidad Que no hace
raw Preserva evidencia del origen con metadata tecnica, hashes y batch. No corrige negocio ni calcula KPIs.
core Normaliza entidades, tipos, claves logicas y reglas de negocio base. No define agregados finales ni consumo ejecutivo.
mart Agrega, calcula metricas y expone vistas de consumo por negocio. No repara identidades ni reemplaza la trazabilidad de core.

Regla de interpretacion:

  • raw responde que se observo;
  • core responde que representa esa evidencia en el modelo de negocio;
  • mart responde que lectura analitica se consume para decidir;
  • ningun mart debe leer snapshots ambiguos si existe una capa core aprobada.

3. Criterios para promover Core -> Mart

Un batch, ventana o subconjunto de SOURCE-003 solo puede promoverse a mart si cumple:

  • contrato core vigente documentado;
  • promocion raw -> core validada o evidencia equivalente aprobada;
  • tenant_id = alpuntodeventa;
  • sync_batch_id trazable y esperado;
  • line_key no vacio y estable;
  • source_row_hash preservado desde core;
  • tipos de fechas, importes, cantidades y costos convertidos sin coercion silenciosa;
  • deduplicacion de tenant_id + line_key aprobada en core;
  • ventana de negocio declarada y conciliable;
  • reglas de signo por tipo de comprobante preservadas;
  • reglas de canal, vendedor, cliente, producto y territorio provenientes de core o contratos de cruce aprobados;
  • metricas candidatas definidas antes de materializar;
  • conteos y totales reconciliables contra core;
  • decision humana o gate documental si hay drift, reproceso o rebuild.

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

4. Marts candidatos iniciales

Los primeros marts candidatos para SOURCE-003 son:

Mart candidato Proposito Granularidad candidata
Ventas por dia Seguimiento diario de facturacion, unidades, clientes y tickets. tenant_id + business_date
Ventas por vendedor Medir performance transaccional por vendedor. tenant_id + periodo + seller_code
Ventas por cliente Entender compra, recurrencia, abandono y recuperacion. tenant_id + periodo + customer_code
Ventas por producto/SKU Medir mix, unidades, importes y participacion por articulo. tenant_id + periodo + sku
Ventas por territorio/zona Leer geografia, zona logistica y cobertura comercial. tenant_id + periodo + territory_key
Rentabilidad / CMV si aplica Analizar margen, contribucion y costo de mercaderia vendida cuando la evidencia sea confiable. tenant_id + periodo + dimension principal

Estos marts son candidatos documentales. No implican tablas fisicas, vistas, materializaciones ni consultas ejecutables.

5. Metricas candidatas

Metricas candidatas iniciales:

  • venta bruta;
  • venta neta;
  • descuentos;
  • impuestos;
  • cantidad vendida;
  • cantidad de bultos o unidades equivalentes cuando aplique;
  • cantidad de comprobantes;
  • cantidad de lineas;
  • clientes unicos;
  • SKU unicos;
  • ticket promedio;
  • unidades promedio por comprobante;
  • venta promedio por cliente;
  • CMV cuando exista evidencia confiable;
  • margen bruto;
  • contribucion;
  • porcentaje de margen;
  • variacion contra periodo anterior;
  • recuperacion o perdida de venta si se cruza con contratos futuros.

Regla: toda metrica monetaria debe declarar signo, moneda, escala decimal, tratamiento de anulaciones, notas de credito y comprobantes correctivos.

6. Dimensiones candidatas

Dimensiones candidatas iniciales:

  • fecha comercial;
  • periodo diario, semanal, mensual y ventana movil;
  • vendedor transaccional;
  • cliente;
  • producto / SKU;
  • marca;
  • proveedor;
  • canal raw y canal normalizado;
  • tipo de comprobante;
  • estado de comprobante;
  • territorio normalizado;
  • zona logistica;
  • localidad;
  • provincia;
  • segmento o clasificacion futura del cliente;
  • familia, categoria o agrupacion futura del producto;
  • batch y version de fuente para auditoria.

Las dimensiones enriquecidas desde SOURCE-001 o SOURCE-002 requieren contrato de cruce o regla documental separada antes de materializarse.

7. Granularidad

La granularidad base del mart no debe ser unica para todos los consumos.

Granularidades candidatas:

  • diaria: tenant_id + business_date;
  • vendedor-periodo: tenant_id + period_key + seller_code;
  • cliente-periodo: tenant_id + period_key + customer_code;
  • producto-periodo: tenant_id + period_key + sku;
  • cliente-producto-periodo: tenant_id + period_key + customer_code + sku;
  • vendedor-cliente-producto-periodo: tenant_id + period_key + seller_code + customer_code + sku;
  • territorio-periodo: tenant_id + period_key + territory_key;
  • batch-auditoria: tenant_id + sync_batch_id + mart_name.

Todo mart debe declarar si su granularidad es transaccional agregada, snapshot, acumulado, ventana movil o historico cerrado.

8. Claves y trazabilidad

Cada mart futuro debe conservar trazabilidad suficiente hacia core.

Claves candidatas:

Uso Clave candidata
Aislamiento tenant tenant_id
Identidad del mart mart_name
Periodo period_key, period_start, period_end
Dimension principal seller_code, customer_code, sku, territory_key segun mart
Auditoria batch sync_batch_id
Auditoria de contenido source_row_hash_set_hash o equivalente aprobado
Rebuild mart_build_id

Un mart agregado no debe pretender conservar una unica line_key si resume muchas lineas. Debe conservar conteos, batch, ventana y una referencia de auditoria que permita reconstruir desde core.

9. Relacion con Batch, Source Row Hash y Line Key

Reglas obligatorias:

  • sync_batch_id debe permitir saber que batches de core alimentaron cada build de mart;
  • line_key vive en core como identidad de linea y puede aparecer en marts de detalle, pero no es clave principal de marts agregados;
  • source_row_hash debe preservarse en core y agregarse en mart mediante una huella de conjunto cuando el mart agrupe muchas filas;
  • un cambio en source_row_hash para una misma line_key debe invalidar o recalcular los marts afectados;
  • un rebuild por batch debe poder explicar cantidad de lineas fuente, cantidad de lineas agregadas, importe total, CMV total cuando aplique y periodo afectado.

Clave de auditoria minima candidata por build:

text tenant_id + mart_name + mart_build_id + sync_batch_id

10. Validaciones minimas

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

  • tenant_id = alpuntodeventa;
  • mart_name aprobado;
  • granularidad declarada;
  • periodo declarado;
  • sync_batch_id o conjunto de batches informado;
  • conteo de lineas fuente esperado desde core;
  • conteo de grupos resultantes esperado o explicado;
  • total de venta reconciliado contra core;
  • total de cantidad reconciliado contra core;
  • total de CMV reconciliado contra core cuando aplique;
  • no duplicados en la clave logica del mart;
  • no valores negativos inesperados fuera de reglas de comprobante;
  • dimensiones obligatorias no vacias segun mart;
  • reglas de timezone y fecha comercial documentadas;
  • ausencia de lectura directa a raw snapshot o CSV si existe core;
  • artefactos con datos reales fuera de Git si se usan archivos intermedios;
  • sin dependencias a OpenClaw executor para construir mart.

11. Errores esperados

Error Ejemplo Resultado esperado
Core no aprobado Se intenta construir mart desde snapshot o CSV sin promocion gobernada. BLOCKED
Granularidad ambigua No esta declarada la clave del agregado. FAIL
Duplicado de mart Dos filas con la misma clave logica del mart. FAIL
Conciliacion fallida Total de venta o cantidad no coincide contra core. FAIL
CMV no confiable CMV ausente, incompleto o no reconciliado para rentabilidad. BLOCKED
Dimension desconocida Vendedor, cliente, SKU o territorio sin regla de resolucion. BLOCKED
Batch incompleto Faltan batches esperados para el periodo. BLOCKED
Drift detectado Cambia source_row_hash de lineas ya usadas en un build previo. BLOCKED
Signo invalido Nota de credito o anulacion no respeta regla documentada. FAIL
Consumo prematuro Dashboard, reporte o LLM intenta usar mart no aprobado. BLOCKED

12. Refresh y Rebuild Futuro

El refresh futuro de mart debe ser reproducible desde core.

Reglas:

  • preferir rebuild deterministico por periodo, batch o ventana;
  • registrar mart_build_id;
  • registrar built_at;
  • registrar version de contrato y regla de calculo;
  • distinguir refresh incremental de rebuild completo;
  • bloquear refresh si core tiene batches conflictivos;
  • no calcular mart directamente desde raw salvo gate excepcional documentado;
  • conservar historial de builds si el consumo o auditoria lo requiere.

Para fuente viva, el mart debe soportar una ventana movil futura y recalcular periodos afectados por cambios de source_row_hash sin hard delete silencioso.

13. Rollback logico o Rebuild por Batch

La reversa futura de mart debe resolverse preferentemente por rebuild, no por borrado manual.

Reglas obligatorias:

  • exigir tenant_id;
  • exigir mart_name;
  • exigir mart_build_id o sync_batch_id;
  • exigir periodo afectado;
  • exigir conteo esperado de filas o grupos a invalidar/reconstruir;
  • exigir conciliacion antes y despues;
  • exigir aprobacion humana separada si toca datos persistidos;
  • prohibir TRUNCATE;
  • prohibir borrado sin filtro completo de mart, periodo y batch;
  • bloquear rollback si dashboards, reportes o consultas LLM activas dependen de un build sin plan de comunicacion.

Rollback logico significa marcar un build como reemplazado, invalido o reconstruido con trazabilidad. No significa restaurar produccion ni habilitar escrituras operativas.

14. Relacion con Dashboards, Reportes y Consultas LLM Futuras

La capa mart sera la candidata natural para alimentar:

  • dashboards comerciales;
  • reportes diarios, semanales y mensuales;
  • consultas operativas por vendedor, cliente, producto y territorio;
  • alertas de riesgo, recuperacion o crecimiento;
  • explicaciones asistidas por LLM;
  • recomendaciones comerciales futuras;
  • comparaciones contra objetivos o metas futuras.

Reglas:

  • dashboards y reportes deben leer mart aprobado, no snapshots ni tablas raw;
  • consultas LLM futuras deben declarar que mart consumen y con que ventana;
  • respuestas asistidas deben poder explicar periodo, metrica y fuente;
  • ningun LLM debe inferir datos faltantes como hechos;
  • cualquier recomendacion debe distinguir metrica observada, regla aplicada e interpretacion sugerida.

15. 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;
  • vistas fisicas;
  • materializaciones;
  • DDL;
  • DML;
  • ejecucion SQL;
  • dashboards productivos;
  • reportes productivos;
  • consultas LLM operativas;
  • rollback real;
  • deploy;
  • push.

16. 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 importer, executor, gates, observabilidad, idempotencia, rollback, secretos, permisos y aprobacion humana;
  • cualquier dashboard, reporte o consulta LLM futura requiere mart aprobado, permisos de consumo y contrato de exposicion.

17. Relacion con documentos vigentes

Documentos base:

  • BUSINESS-OBSERVER-DATA-LAYERS-ARCHITECTURE.md;
  • SOURCE-003-RAW-LAYER-CONTRACT.md;
  • SOURCE-003-CORE-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;
  • SOURCE-003-CHANNEL-TAXONOMY.md.

Lectura vigente:

  • contratos RAW y CORE documentados y no implementados;
  • 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.

18. Decision

text CONTRATO MART DOCUMENTADO / NO IMPLEMENTADO

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

No se implementa tabla mart, 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, dashboards productivos, consultas LLM operativas ni OpenClaw executor.