Business Observer Data Layers Architecture

Fecha local: 2026-06-15

Estado: ARQUITECTURA FUTURA DOCUMENTADA / NO EJECUTIVA

portal_visible = yes

Scope: tenant

tenant_id: alpuntodeventa

Owner: Gabi / Carlos Canu

Fuente de verdad: docs/tenants/alpuntodeventa/business-observer/design/BUSINESS-OBSERVER-DATA-LAYERS-ARCHITECTURE.md

1. Objetivo

Definir la arquitectura objetivo futura para Business Observer APV y SOURCE-003, dejando un patron reutilizable para futuros frentes de clientes, productos y otros dominios.

Esta arquitectura documenta capas, responsabilidades y bloqueos. No ejecuta runtime, no crea tablas, no modifica datos y no habilita automatizaciones.

2. Arquitectura objetivo

Flujo futuro gobernado:

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

Lectura por responsabilidad:

text origen/snapshot/query -> raw -> prepared CSV -> core -> mart -> Python importer / Python runner -> OpenClaw executor gobernado -> sync futura aprobada

La secuencia es una arquitectura objetivo. No significa que todas las capas esten implementadas hoy.

3. Definicion de capas

Capa	Definicion	Estado actual
raw	Copia fiel del origen, snapshot o query autorizada. Conserva la evidencia de entrada sin reinterpretarla como modelo final.	Parcial para SOURCE-003 por snapshots congelados.
prepared CSV	Artefacto reproducible, validado, fuera de Git, listo para una carga controlada o comparacion.	Existe para piloto SOURCE-003; generador Python documentado.
core	Modelo normalizado, estable y validado, con claves canonicas, trazabilidad y reglas de calidad.	Futuro; no formalizado para produccion.
mart	Capa analitica para KPIs, reportes, dashboards, segmentaciones y lecturas de negocio.	Futuro; no materializado como contrato final.
Python generator	Componente local que transforma raw -> prepared CSV con validaciones reproducibles.	Existe para SOURCE-003 como generador preparado.
Python importer	Componente futuro que cargara datos gobernados hacia raw o core segun contrato, con idempotencia, batch y rollback.	No implementado formalmente.
Python runner	Capa de ejecucion controlada de SQL, gates y verificaciones, con confirmaciones explicitas y lectura/escritura separadas.	Existe runner piloto para SOURCE-003, con modos de escritura bloqueados.
OpenClaw executor	Futuro disparador gobernado. Puede iniciar flujos aprobados, pero no decide autonomamente cargas, sync ni rollback.	No habilitado.
sync futura	Operacion posterior, gobernada, observable e idempotente.	No habilitada.

4. Contrato conceptual por capa

raw

• preserva copia fiel del origen, snapshot o query;
• no corrige semanticamente el negocio;
• debe conservar source_system, version de query, fecha de extraccion y evidencia de batch;
• puede provenir de SGC, WooCommerce, CSV congelado u otra fuente aprobada;
• no debe mezclarse con decisiones analiticas.

prepared CSV

• vive fuera de Git;
• debe ser reproducible desde raw;
• debe validar columnas, filas, fechas, batch, hashes, duplicados y nulos criticos;
• debe poder compararse contra evidencia previa;
• no equivale a carga ni a sync.

core

• normaliza entidades de negocio;
• fija claves canonicas como tenant_id + codigo_cliente, tenant_id + SKU o tenant_id + line_key, segun dominio;
• separa atributos, mediciones, relaciones, historicos y auditoria;
• debe cumplir el Data Design Standard global;
• no debe depender de planillas manuales como autoridad final.

mart

• consume core y no el origen crudo directamente, salvo excepcion documentada;
• expresa KPIs, semaforos, rankings, cohortes, reportes y vistas de consumo;
• debe preservar trazabilidad hacia batch, fuente y regla de calculo;
• puede alimentar dashboards, alertas, recomendaciones e IA futura.

Python generator

• transforma snapshots raw en prepared CSV;
• debe ser deterministico salvo campos tecnicos explicitamente documentados;
• no toca PostgreSQL;
• no lee secretos;
• no ejecuta SQL.

Python importer

• futuro componente de carga gobernada;
• debera cargar a raw o core segun contrato formal;
• debera exigir batch, checksum, entorno, tenant y permisos;
• debera soportar idempotencia, rollback por batch y reintentos seguros;
• no existe todavia como contrato final.

Python runner

• gobierna ejecucion controlada de SQL y gates;
• separa preflight-before-load de status / verify-existing-pilot;
• no convierte un PASS read-only en permiso de escritura;
• debe exigir confirmaciones exactas para cualquier modo que toque DB.

OpenClaw executor

• futuro disparador gobernado;
• no debe ser autonomo para decidir cargas;
• solo podra ejecutar flujos aprobados por contrato, gate y permisos;
• debera registrar operador, tenant, objetivo, batch y resultado.

sync futura

• queda posterior a contratos formales y observabilidad;
• no puede basarse solo en ultima fecha cargada;
• para fuentes vivas como SOURCE-003 debe contemplar ventana movil, upsert, source_row_hash, last_seen_at, missing_from_source y no hard delete;
• requiere aprobacion separada.

5. Estado actual de SOURCE-003

Estado documentado:

• piloto dedicado VERDE;
• DDL ejecutado;
• 1886 filas cargadas;
• batch publicado: 1827f887-9499-4579-b4f3-234d54f41f7f;
• CSV preparado validado fuera de Git;
• Python generator documentado para raw -> prepared CSV;
• Python runner documentado con semantica preflight vs status;
• runner status validado en DB read-only con PASS;
• evidencia publica del piloto dedicada publicada;
• sigue sin sync diaria;
• sigue sin produccion final.

Decision operativa vigente:

text SOURCE-003 PILOTO DEDICADO VERDE / NO ES SYNC DIARIA / NO ES PRODUCCION FINAL

6. Que falta antes de sync

Antes de habilitar cualquier sync diaria, carga masiva o uso productivo se requiere cerrar como minimo:

• contrato raw formal;
• contrato core formal;
• contrato mart formal;
• Python importer formal;
• contrato de OpenClaw executor;
• gates de ejecucion;
• observabilidad y logs;
• idempotencia;
• rollback por batch;
• estrategia de reintentos;
• validaciones de calidad;
• seguridad de secretos;
• permisos y minimo privilegio;
• criterio de ventanas moviles para fuentes vivas;
• politica anti hard-delete;
• manejo de missing_from_source;
• evidencia de recuperacion ante fallos.

7. Relacion con clientes y productos

Clientes y productos siguen no iniciados en runtime.

Reglas para futuros frentes:

• deben reutilizar esta arquitectura por capas;
• deben abrir blueprint propio antes de cargar o sincronizar;
• no deben copiar automaticamente SOURCE-003;
• deben definir sus propios contratos raw, core, mart, importer, runner, gates, calidad y rollback;
• deben preservar sus claves canonicas ya documentadas: tenant_id + codigo_cliente para clientes y tenant_id + SKU para productos;
• no deben mezclar evidencia de ventas con autoridad de clientes o productos.

SOURCE-003 sirve como patron de gobierno y trazabilidad, no como plantilla ejecutable automatica para otros dominios.

8. Bloqueos preservados

Esta arquitectura no habilita:

• sync diaria;
• carga masiva;
• produccion final;
• OpenClaw executor;
• scheduler;
• nuevas tablas;
• nuevas migraciones;
• ejecucion SQL;
• runner en modo escritura;
• importer formal;
• deploy;
• push.

9. Decision

text ARQUITECTURA FUTURA DOCUMENTADA / NO EJECUTIVA

El flujo raw -> prepared CSV -> core -> mart -> Python importer/runner -> OpenClaw executor -> sync futura queda definido como arquitectura objetivo para Business Observer APV.

La decision formaliza capas y responsabilidades, preserva el estado verde del piloto SOURCE-003 y mantiene bloqueadas sync diaria, carga masiva, produccion final y OpenClaw executor.