Saltar a contenido

SOURCE-003 Importer Build Mart Plan

Fecha local: 2026-06-16

Estado: BUILD-MART 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-BUILD-MART-PLAN.md

1. Objetivo

Disenar documentalmente el futuro flujo:

powershell python scripts/source_003_importer.py build-mart

El objetivo de build-mart sera construir una capa analitica gobernada desde CORE para consumo de negocio. Debe transformar filas normalizadas de ventas en agregados trazables, reconciliables e idempotentes para dashboards, reportes y consultas asistidas por LLM.

Este plan no implementa Python, no ejecuta importer, no ejecuta SQL, no toca PostgreSQL, no crea tablas, no carga datos, no genera CSV y no toca RAW/CORE/MART real.

2. Safe Point Documental

Control Valor
workspace C:\APV\openclawai
rama main
HEAD inicial 8fd042f5b3fed7f617cf85ed5cb99cc5fe50704d
origin/main inicial 8fd042f5b3fed7f617cf85ed5cb99cc5fe50704d
ultimo commit inicial 8fd042f docs: review source 003 core local dev execution
estado inicial main limpio

3. Base Autorizada

Origen futuro:

text business_observer.core_source_003_sales_items

Batch autorizado para diseno:

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

Evidencia vigente:

  • RAW local-dev: 1886 filas;
  • CORE local-dev: 1886 filas;
  • CORE post-execution review: PASS;
  • tenant_id = alpuntodeventa;
  • duplicados CORE por claves logicas: 0;
  • line_key, source_row_hash, promoted_at y raw_loaded_at completos;
  • produccion y sync diaria siguen bloqueadas.

Documentos base leidos:

  • SOURCE-003-MART-LAYER-CONTRACT.md;
  • SOURCE-003-PROMOTE-CORE-LOCAL-DEV-POST-EXECUTION-REVIEW.md;
  • SOURCE-003-CORE-DDL-LOCAL-DEV-FORWARD-001.md;
  • scripts/source_003_importer.py.

4. Alcance MART V1

MART V1 debe ser una primera capa de consumo analitico, no una capa de correccion de datos. Debe leer exclusivamente desde CORE aprobado y mantener trazabilidad suficiente para reconstruir cada agregado.

Alcance incluido:

  • agregados de ventas sobre SOURCE-003;
  • calculos de metricas comerciales basicas;
  • dimensiones directas ya presentes en CORE;
  • claves de auditoria por batch y build;
  • validaciones pre/post reconciliables contra CORE;
  • diseno para rebuild deterministico por batch.

Fuera de alcance:

  • enriquecimiento fisico con SOURCE-001 o SOURCE-002 sin contrato de cruce;
  • tablas productivas;
  • dashboards productivos;
  • consultas LLM operativas;
  • sync diaria;
  • carga masiva;
  • escritura real sobre MART.

5. Marts Candidatos

Mart candidato Objetivo Granularidad candidata
Ventas por dia Leer venta diaria, unidades, comprobantes, clientes y tickets. tenant_id + business_date
Ventas por vendedor Medir performance del vendedor transaccional. tenant_id + period_key + seller_code
Ventas por cliente Analizar compra, recurrencia, abandono y recuperacion. tenant_id + period_key + customer_code
Ventas por SKU/producto Leer mix, unidades, importes y participacion por articulo. tenant_id + period_key + sku
Ventas por zona/territorio si aplica Leer cobertura geografica o logistica cuando la dimension sea confiable. tenant_id + period_key + territory_key
Rentabilidad/CMV si aplica Analizar costo, margen y contribucion si la evidencia economica es estable. tenant_id + period_key + dimension principal

Riesgos semanticos:

  • territory_key no debe inferir vendedor responsable; puede representar zona logistica, localidad, provincia o territorio normalizado solo si existe regla aprobada;
  • CMV, cost_amount y contribution_amount deben conservar lectura de negocio pendiente si no hay conciliacion formal;
  • notas de credito, anulaciones y comprobantes correctivos deben respetar la regla de signo documentada antes de agregar metricas;
  • canal, vendedor, cliente y producto no deben corregirse en MART si la regla pertenece a CORE o a un contrato de cruce.

6. Metricas Candidatas

Metricas base candidatas:

  • venta bruta;
  • venta neta;
  • descuentos;
  • impuestos;
  • cantidad vendida;
  • cantidad de unidades;
  • cantidad de bultos o paquetes cuando aplique;
  • cantidad de lineas CORE;
  • cantidad de comprobantes;
  • clientes unicos;
  • SKU unicos;
  • ticket promedio;
  • unidades promedio por comprobante;
  • venta promedio por cliente;
  • primera y ultima fecha comercial del agregado.

Metricas economicas condicionadas:

  • CMV;
  • margen bruto;
  • contribucion;
  • porcentaje de margen;
  • margen promedio por comprobante, cliente, vendedor o SKU.

Toda metrica monetaria debe declarar moneda, signo, escala decimal, tratamiento de anulaciones, notas de credito, descuentos, impuestos y redondeos.

7. Dimensiones Candidatas

Dimensiones directas candidatas desde CORE:

  • tenant_id;
  • business_date;
  • period_key, period_start, period_end;
  • document_type;
  • document_status;
  • customer_code;
  • customer_name;
  • sku;
  • product_name;
  • brand;
  • supplier_code;
  • supplier_name;
  • seller_code;
  • seller_name;
  • channel_raw;
  • channel_normalized;
  • delivery_city_raw;
  • delivery_province_raw;
  • logistic_zone_raw;
  • sync_batch_id.

Dimensiones enriquecidas futuras:

  • territorio normalizado;
  • segmento de cliente;
  • categoria de producto;
  • familia comercial;
  • proveedor normalizado;
  • canal consolidado;
  • vendedor asignado vs vendedor transaccional.

Las dimensiones enriquecidas requieren contrato o review separado antes de materializar.

8. Granularidad

Granularidades candidatas:

  • diaria: tenant_id + business_date;
  • periodo-vendedor: tenant_id + period_key + seller_code;
  • periodo-cliente: tenant_id + period_key + customer_code;
  • periodo-SKU: tenant_id + period_key + sku;
  • periodo-zona: tenant_id + period_key + territory_key;
  • periodo-cliente-SKU: tenant_id + period_key + customer_code + sku;
  • periodo-vendedor-cliente-SKU: tenant_id + period_key + seller_code + customer_code + sku;
  • auditoria de build: tenant_id + mart_name + mart_build_id + sync_batch_id.

Cada mart debe declarar si representa agregado diario, agregado de periodo, ventana movil, historico cerrado o snapshot.

9. Claves de Trazabilidad

Claves minimas candidatas:

Uso Clave
Tenant tenant_id
Fuente source_id = SOURCE-003
Batch origen sync_batch_id
Build MART mart_build_id
Nombre de mart mart_name
Periodo period_key, period_start, period_end
Dimension principal seller_code, customer_code, sku, territory_key segun mart
Auditoria de contenido source_row_hash_set_hash o equivalente aprobado
Reconciliacion source_core_row_count, source_document_count, source_net_amount_total

line_key y source_row_hash deben permanecer como identidad de linea en CORE. En MART agregado no deben usarse como clave primaria unica, sino como base para conteos y huellas de conjunto.

10. Idempotencia

build-mart debe ser idempotente por:

text tenant_id + mart_name + mart_build_scope + sync_batch_id

Reglas esperadas:

  • bloquear build duplicado si ya existe un build vigente equivalente;
  • permitir rebuild solo con modo explicito futuro y scope completo;
  • no hacer hard delete silencioso;
  • registrar mart_build_id, built_at, version de contrato y batch origen;
  • reconciliar conteos y totales antes de marcar un build como vigente;
  • invalidar o reemplazar logicamente builds afectados si cambia un source_row_hash usado por el agregado.

11. Rebuild por Batch

El rebuild futuro debe ser deterministico desde CORE.

Scope minimo:

  • tenant_id;
  • mart_name;
  • sync_batch_id;
  • periodo afectado;
  • granularidad;
  • cantidad esperada de filas CORE;
  • cantidad esperada de grupos MART o criterio de variacion aceptado.

Resultado esperado:

  • build nuevo con mart_build_id distinto;
  • build anterior marcado como reemplazado, invalido o superseded si existia;
  • conciliacion antes/despues;
  • evidencia documental o log operativo;
  • sin TRUNCATE;
  • sin borrado sin filtro completo.

12. Validaciones Pre

Antes de un futuro build-mart:

  • comando build-mart implementado y revisado en tarea separada;
  • DDL MART candidato aprobado;
  • tabla o vista MART creada por forward local-dev separado;
  • CORE post-execution review en PASS;
  • business_observer.core_source_003_sales_items existe;
  • batch 1827f887-9499-4579-b4f3-234d54f41f7f existe en CORE con 1886 filas;
  • tenant_id = alpuntodeventa;
  • line_key y source_row_hash completos;
  • no duplicados por claves logicas CORE;
  • mart_name aprobado;
  • granularidad y periodo declarados;
  • reglas de signo y moneda declaradas;
  • DB fingerprint aprobado;
  • postgres-sandbox no usado como destino;
  • produccion y sync diaria no habilitadas.

13. Validaciones Post

Despues de un futuro build-mart local-dev:

  • filas o grupos MART generados coinciden con expectativa o explicacion;
  • no duplicados en clave logica del mart;
  • totales de venta reconciliados contra CORE;
  • totales de cantidad reconciliados contra CORE;
  • CMV y margen reconciliados solo si aplican;
  • conteo de lineas CORE fuente registrado;
  • conteo de comprobantes registrado;
  • periodo minimo y maximo registrado;
  • mart_build_id, built_at, sync_batch_id y tenant_id completos;
  • huella de conjunto o equivalente calculada;
  • data_written, db_write y sql_write reportados de forma explicita;
  • sync_enabled=false;
  • produccion false;
  • dashboard, reporte y LLM siguen bloqueados salvo gate posterior.

14. Relacion Futura con Dashboards, Reportes y LLM

MART sera la fuente candidata para:

  • dashboards comerciales diarios y mensuales;
  • reportes por vendedor, cliente, producto y zona;
  • tableros de rentabilidad si CMV esta aprobado;
  • consultas asistidas por LLM con ventana y metrica declaradas;
  • recomendaciones comerciales futuras.

Reglas:

  • dashboards no deben leer RAW ni snapshots si MART aprobado existe;
  • reportes deben declarar mart_name, periodo y metrica;
  • LLM no debe inferir datos faltantes como hechos;
  • toda respuesta asistida debe poder explicar fuente, periodo, batch y metrica;
  • recomendaciones deben separar hecho observado, regla aplicada e interpretacion sugerida.

15. Que Falta Antes de Implementar

Falta una cadena de gates separada:

  1. DDL MART candidato.
  2. Review tecnica del DDL MART.
  3. Preflight local-dev del DDL MART.
  4. Forward local-dev del DDL MART.
  5. Implementacion futura de build-mart en Python.
  6. Gate execute local-dev para build-mart.
  7. Post-execution review local-dev.

Cada paso requiere SAFE POINT nuevo y autorizacion explicita si toca runtime, DB, SQL o datos.

16. Prohibiciones Preservadas

Este plan no habilita:

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

17. Decision

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

La evidencia CORE LOCAL-DEV POST-EXECUTION REVIEW PASS permite disenar el DDL MART candidato en una tarea posterior. No permite crear tablas, ejecutar SQL, implementar build-mart, cargar MART, activar dashboards productivos, usar consultas LLM operativas, habilitar produccion ni habilitar sync diaria.